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.
OneLogin is a single sign-on provider that your Aha! account connects with through our SAML 2.0 support.
Click any of the following links to skip ahead:
Configure OneLogin
Create a new App by going to the Apps tab in OneLogin and selecting Add App.
On the Find Applications page, search for Aha! and select it.
Select SAML 2.0 connector then Save.
Configure the subdomain in the Configuration section by setting it to your Aha! account subdomain.
Go to the SSO section. Copy the Issuer URL so you can finish the setup process in your Aha! account.
Configure your Aha! account
Now that OneLogin is set up, go to your Aha! account and navigate to Settings ⚙️ → Account → Security and Single Sign-On. You will need to be an administrator with account privileges to do this. In the Single Sign-On section, select SAML 2.0 as the Identity Provider.
Name the SSO configuration. This will be used throughout your Aha! account to help users identify how they are logging in.
Configure using the Metadata URL. Fill in the Metadata URL field with the Issuer URL copied from the OneLogin SSO page and hit Enable. After the metadata is fetched from OneLogin, your Aha! account will switch to Manual Settings. This lets you confirm that they match the info in OneLogin.
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.
Log in with OneLogin
Go to your Aha! account login page. Your login page will now have an additional Login with OneLogin option available.
Click Login with OneLogin to authenticate with OneLogin. If you are already logged in, your browser will go right to Step 3 without showing you a login form.
You are now logged into your Aha! account.
New user SSO login experience
Users logging in with OneLogin are separate accounts from ones that log in with an email and password. If an email and password user exists that has a matching email address to the OneLogin user, it will be automatically converted to use OneLogin SSO. Otherwise, a new user will be automatically provisioned.
Auto-provisioned users are added with a permissions role of None for all workspaces or teams. They also fall under the same seat restrictions as any other user.
After a new user is added through SSO login, an Aha! will need to configure their user permissions. All SSO users will be specifically tagged for the SSO platform they are using on the administrator's Settings ⚙️ → Account → Users page.
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.