SAML 2.0
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.
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 Active Directory Federation Services (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.
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.
Logout redirect URL
In Settings ⚙️ Account Security and single sign-on, you can enter a Logout redirect URL. This is the URL that a user's browser window will navigate to after they have successfully signed out.
Entering a logout redirect URL is optional, but it adds extra security as it ensures that the user session is completely terminated. Without a logout redirect URL, users may think they have signed out when their session may still be active, which can pose a security risk.
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.
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 , or else 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
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
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 account permissions to do this.
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 administrator with account permissions 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 in a public portal, 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 private 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.
It is possible to invite an ideas portal user from your ideas portal configuration 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.
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.
Troubleshooting
We have created an article to help you troubleshoot common SSO configuration issues, complete with explanations and resolutions.
The best place to start in most of these situations is the Recent SSO events for your SSO configuration, at the bottom of the configuration page. Those messages will help diagnose and solve the problem.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.
