Aha! Develop Advanced plan required. Contact us if you want a demo, or to try using this in your account. No salespeople here at Aha! — just product experts. |
Aha! Develop | SAML 2.0 (Advanced plan)
Single sign-on (SSO) allows users of your Aha! Develop account to log in using your existing SAML-enabled ID provider, such as Active Directory, OneLogin, Ping Identity, Okta, and many more.
For accounts that already have local users, you can switch them to SAML or keep them the same.
User permissions |
|
Troubleshooting | |
Further reading |
|
Click any of the following links to skip ahead:
Overview
Security Assertion Markup Language (SAML) is a standard protocol that gives identity providers (IdP) a secure way to let a service provider (SP) such as Aha! know who a user is. It does this by sending your Aha! account a cryptographically signed XML document confirming users' identities, along with some basic user information.
Once configured, users can authenticate with the following process:
The user navigates to your account (e.g. https://myaccount.aha.io/)
Your account presents the user with an additional login option (e.g. "Login with <your account name>")
When clicked, the user's browser will be redirected to the identity providers.
The identity provider authenticates the user.
Once authenticated, the browser is redirected to your account with a SAML assertion.
Your account verifies the SAML assertion and provisions new users.
The user is granted access to your account.
The user is redirected to the original link (if prior authentication was required).
Configure SSO for your Aha! account with SAML
To get started, go to Settings ⚙️ Account Security and single sign-on and select a the SAML 2.0 provider from the Identity provider dropdown. This will display the SSO settings where you can give your SSO provider a name (required) and add details of your identity provider.
Aha! products support the SAML 2.0 standard, which provides a few ways to streamline configuration. Although each identity provider will have different interfaces and nuances, most provide configuration metadata as a URL or downloadable file. Since each identity provider is unique, we will focus on a generic SAML identity provider in this article.
Change SAML 2.0 SSO identity providers
Before you change identity providers in your SAML 2.0 SSO implementation, you must first disable your current provider. This will help avoid SSO identity provider conversion issues.
Metadata URL
In Settings ⚙️ Account Security and single sign-on, you can choose to configure SSO by using a Metadata URL, Metadata file, or Manual settings.
The easiest way to configure SSO is to use a link to your identity provider's metadata file, if they provide one. Select the Metadata URL radio button, enter the URL, and click Enable. Your Aha! account will download the configuration file, parse it, and configure everything.
Metadata file
In Settings ⚙️ Account Security and single sign-on, you can choose to configure SSO by using a Metadata URL, Metadata file, or Manual settings.
Some identity providers require you to download the metadata file instead of giving you a link. In that case, select the Metadata File radio button, choose the file you downloaded from your identity provider, and click Enable. This sends the file to your Aha! account, where it is parsed and the crucial information is extracted.
It is important to note that your Aha! account does not save the metadata file. If you must make any configuration changes, you will need to upload the file again or make changes using the Manual Settings option.
Manual settings
In Settings ⚙️ Account Security and single sign-on, you can choose to configure SSO by using a Metadata URL, Metadata file, or Manual settings.
Sometimes, you just need a little more control. That's where the Manual Settings option comes in. Only two things are needed for SAML to work: the Single sign-on endpoint and Certificate fingerprint.
The Single sign-on endpoint tells your Aha! account where to find the identity provider.
The Certificate fingerprint lets us verify that we are talking to the correct identity provider.
Multiple IdP certificate fingerprints can be provided, which helps with the following situations:
Providing compatibility with Microsoft ADFS, which often uses multiple signing certificates
Managing cutovers to new fingerprints in a transparent manner without any disruption
When entering multiple certificate fingerprints, separate them with a comma.
Note: Some identity providers will give you a certificate, but not a certificate fingerprint. If this is the case, you can usually inspect the certificate on your local machine to get the fingerprint. Aha! products expect the fingerprint to be a SHA-1 of the certificate in the format F4:DC:06:92:D4:FC:40:DF:FD:A6:53:78:32:AA:52:39:3E:AA:6E:54 or its successor, SHA-256.
Once you have completed the required manual settings, click Enable.
User attributes
The SAML identity provider must be configured to provide four attributes:
EmailAddress
FirstName
LastName
NameID
The NameID attribute must be included in the subject. Your Aha! account uses it to uniquely identify the user (separately from their email address). We recommend using a persistent, unique identifier in this field, rather than the user's email address. You must use a unique identifier so that Aha! can maintain a mapping between the user record in Aha! and within your identity provider. This ensures that any changes to the email address within the identity provider will be transparently reflected in your Aha! account.
Note: You cannot use EmailAddress as a unique identifier. If you do, your single sign-on configuration will error.
Your Aha! account will use these attributes to properly identify the user and automatically provision users. You can also configure your provider to include two additional optional attributes:
ProductRole
ProductPrefix
Note: By default, users are provisioned with no access or any assigned role. Therefore, an administrator in your Aha! account will need to set the roles for all users. The exception to this is when the administrator is setting up custom attributes to provision specific users to specific roles and/or permissions, such as when using ProductPrefix and ProductRole.
EmailAddress
Every user in your Aha! account is required to have a valid email address, even when using SSO. Since the identity provider is responsible for managing user information, it must send the user's email address to your Aha! account in its assertion. Identity providers use different naming conventions, so your Aha! account will look for an email address in the following attributes sequentially:
EmailAddress
email
Email
mail
emailAddress
User.email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
Note: This attribute is supported for older versions of Azure. It is not recommended.
FirstName
Just like email addresses, identity providers may send the first name in several common fields. To provide out-of-the-box compatibility with most identity providers, your Aha! account will try to find the first name in the following attributes:
FirstName
first_name
firstname
firstName
User.FirstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
LastName
Just like email addresses, identity providers may send the last name in several common fields. To provide out-of-the-box compatibility with most identity providers, your Aha! account will try to find the last name in the following attributes:
LastName
last_name
lastname
lastName
User.LastName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
NameID
Each user in your Aha! account needs to have a unique NameID. This value must be unique — an email addresses cannot be used as a NameID. This ensures that any changes to a user's email address can be reflected in your Aha! account.
Custom attributes
Not all identity providers support custom attributes, but if yours does, you can use it to provision your users with user and hierarchy permissions. This makes it easier for new users to engage with your Aha! account, and saves you time managing users individually.
ProductPrefix (optional)
The ProductPrefix attribute is an optional one, but you can include it to automatically grant access to a specific workspace, line, or team in your hierarchy.
This attribute needs to be configured in your identity provider, and not all identity providers support custom attributes. You can find a list of workspace prefixes by navigating to:
Aha! Roadmaps and Aha! Ideas: Settings ⚙️ Account Workspaces
Aha! Develop: Settings ⚙️ Account Teams
You will need to be an administrator with customization permissions to access these pages.
The workspace or team you select with ProductPrefix is added to the user only at the time that they are first provisioned, and will not update if you change this attribute later. This attribute is very handy for giving new users a default workspace or team when they first join your account. For advanced hierarchy permissions, navigate to
Settings ⚙️ Account Users
You will need to be an administrator with billing permissions to do this.
Note: If you set the ProductPrefix attribute, you also need to set the ProductRole attribute.
ProductRole (optional)
The ProductRole attribute works in conjunction with the ProductPrefix attribute and allows you to specify which level of access a user should have.
Just like ProductPrefix, you need to configure this attribute in your identity provider, and not all identity providers support custom attributes.
ProductPrefix is only used when a user is initially provisioned. Values match with Aha! user permission roles and must be one of the following:
product_owner
contributor
reviewer
viewer
none
Preexisting account users
You can have a mix of SAML and password users in the same account. The first time a password user logs in with SAML, their account will be converted to use SAML automatically. Subsequently, the user will not be able to log in using their password again. This is so that if the user account is disabled via SAML, they will not be able to bypass that and log in with their password.
It is possible for administrators in your Aha! account to manually convert SSO users back to using a password in Settings ⚙️ Account Users. All history for the user will be maintained during this process.
When using SSO, email addresses should be managed within the identity provider system. If an email address is modified within your Aha! account, the email address will be reset to the value in the identity provider system.
Preexisting ideas portal users
If your team uses Aha! Roadmaps or Aha! Ideas, you have access to ideas portals.
When a user authenticates to the ideas portal, they will be presented with the option to authenticate to the portal via SSO only. If they are already logged in to the SSO provider, they will automatically be logged in to your portal without any additional actions.
Public portal: Once SSO is configured, users will be prompted to log in before posting or voting on ideas. Anyone can view ideas, regardless of whether they are logged in.
Private portal: In order to access the portal, users will be prompted to log in via SSO. If SSO is configured, any user with the SSO account will be able to access the ideas portal, regardless of email domain.
Note: It is possible to invite an ideas portal user from your ideas portal settings who has not been configured with the identity provider your portal is using. The user will not be able to log in to the ideas portal until they can be authenticated by the identity provider.
When using SSO in your account, email addresses, first names, and last names should be managed within the identity provider system. If these fields are modified within your Aha! account, they will be reset to the value in the identity provider system.
Note:
When an ideas portal user tries to log in using SSO for the first time, it will convert the email address account to SSO and keep their idea submissions intact.
Okta provides an Aha! account connector application. This connector is only used for setting up SSO with the Aha! application. It does not work for ideas portals. To setup SSO with Okta on an ideas portal, you must use the manual setup option.
New user messages
If users sign in to your Aha! account through SAML 2.0 without access to a workspace or a team, they will receive a banner message. By default, this message informs the user that they do not have access to a workspace or a team and gives them a list of administrators in your Aha! account that they can contact, but you can personalize the message to include any information that would be useful to a user in this situation.
If you get stuck, please reach out to our Product Success team. Our team is made up entirely of product experts and responds fast. |