This article discusses functionality that is included in the Aha! Knowledge Advanced plan. Please contact us if you would like a live demo or want to try using it in your account.
Single sign-on (SSO) allows users of your Aha! account to log in using your existing SAML-enabled ID provider, such as OneLogin, Okta, and more. This means users do not have to keep track of yet another email and password. It also makes provisioning new users a breeze. For accounts that already have local users, you can switch them to SAML or keep them the same.
If you are an Aha! Knowledge Advanced plan subscriber, you can configure SSO for account access and knowledge bases. Because many customers have different needs for individual access but use SSO to keep access secure, you will need to set up separate SSO configurations for your account and your knowledge base.
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).
Removing a user from your IDP will not remove them from your Aha! account.
Configure SSO for your Aha! account with SAML
To get started, go to Settings ⚙️→ Account → Security and single sign-on and select a 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 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 role attribute is applied once, upon user creation. It is not applied to existing users.
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 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.
This role attribute is applied once, upon user creation. It is not applied to existing users.
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:
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 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.
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.
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.