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 your users to log in to your knowledge base using their existing OpenID Connect-enabled identity provider, such as Active Directory, OneLogin, PingIdentity, Okta and many more. With SSO, you can increase engagement of your idea portals as employees and customers no longer need to keep track of yet another email and password.
OpenID Connect can be very difficult to configure — and for the purposes of knowledge base SSO — does not offer significant benefits over a traditional SAML configuration.
Click any of the following links to skip ahead:
How it works
When a user navigates to the knowledge base, they will be presented with the option to authenticate to the knowledge base via SSO only. If they are already logged in to the SSO provider, they will automatically be logged in to your knowledge base without any additional actions.
Enable SSO for any knowledge base
You can configure SSO differently for each knowledge base in your Aha! account. To get started, go to Settings ⚙️ -> Account -> Knowledge -> Knowledge bases. You will need to be an administrator with customizations permissions to configure a knowledge base.
To enable OpenID Connect in your knowledge base:
Navigate to Settings ⚙️ -> Account -> Knowledge -> Knowledge bases.
Click the knowledge base you want to configure. This opens that knowledge base's settings.
On the Overview tab, find the Access settings. Next to the Authentication dropdown, select SSO.
In the SSO identity provider dropdown, select +Add new provider.
-
On the next screen, enter a Name to identify the SSO configuration. Next to Type, select OpenID. Click Save.
If you already have SSO set up for a different knowledge base and would like to share that SSO configuration with this one, you can select the existing provider you have already set up during this step and skip adding a new one.
The OpenID Connect configuration will display. It may differ based on the provider that you use, but you will want to consider these configuration options:
Callback URL: Copy the Callback URL and paste it into your identity provider's setting (e.g. Login redirect).
Single sign-on endpoint: In your provider, copy the exact endpoint URL specified by your identity provider. Paste it here.
Note: The Single sign-on endpoint value must match the issuer value in your identity provider's discovery response. You can view this discovery response by appending/.well-known/openid-configurationto the SSO endpoint. For example, if your Single sign-on endpoint is https://myprovider.example.com, you can view the discovery response at https://myprovider.example.com/.well-known/openid-configuration.Identifier: In your provider's settings, copy the Identifier (e.g. Client ID). Paste it here.
Secret: In your provider's settings, copy the Secret and paste it here.
Beneath Access for Aha! users, you will find two additional advanced settings. These are disabled by default for knowledge base SSO configurations.
Most Aha! accounts will not need these advanced settings — and you can break your SSO configuration if you do not use them correctly. If you are also using this configuration for both your knowledge base and you need help configuring these options, you are welcome to reach out to our Customer Success team.
Enable CNAME for SSO URLs: This option is rarely needed and will break SSO if not carefully configured. Enabling this option causes SSO to use the CNAME as well. This is not necessary for knowledge bases, even when using a CNAME. It may be useful if your customers have strict corporate networking policies.
CNAME: This must match an existing CNAME used in an active knowledge base in your Aha! account. After adding the CNAME click Update URLs and Save or Update SSO. If you have previously configured SSO the URLs must be updated in your external system.
Configure your OIDC identity provider
In most cases, once you save your OIDC SSO configuration in Aha! Roadmaps, you are ready to go — no further configuration needed. However, if your identity provider does not include the required claims, Aha! Roadmaps will let you know what is missing when you save your SSO settings, so you can configure your identity provider to send the right information.
The following are required OpenID Connect claims:
email
given_name
family_name
Share your SSO configuration
Since SSO for ideas portals is configured in the same way as knowledge base SSO, knowledge bases and ideas portals can share an SSO configuration.
The table below explains how many ideas portals and knowledge bases can share a single SSO configuration, depending on which Aha! plan(s) you are subscribed to.
Aha! plans |
Number of ideas portals on a single SSO configuration |
Number of knowledge bases on a single SSO configuration |
Notes |
Aha! Roadmaps |
1 |
0* |
One SSO configuration per ideas portal. |
|
Aha! Roadmaps + Aha! Ideas Advanced |
2+ |
0* |
One SSO configuration can be shared between multiple ideas portals. |
|
Aha! Roadmaps + Aha! Knowledge Advanced |
2+ |
2+ |
One SSO configuration can be shared between one ideas portal and multiple knowledge bases. |
|
Aha! Roadmaps + Aha! Ideas Advanced + Aha! Knowledge Advanced |
2+ |
2+ |
One SSO configuration can be shared between multiple ideas portals and multiple knowledge bases. |
* Publishing a knowledge base requires an Aha! Knowledge Advanced plan.
To share your identity provider configuration between multiple knowledge bases and/or with a single ideas portal:
Navigate to Settings ⚙️ -> Account -> Knowledge -> Knowledge bases. You will need to be an administrator with customizations permissions to do this.
Click a knowledge base to open its settings.
Once you have your knowledge base settings open, navigate to Overview -> Authentication.
Select an identity provider you have configured from the Identity provider dropdown.
Repeat these steps for each knowledge you wish to use the shared Identity provider configuration.
You can manage your identity provider configuration — and the knowledge bases or portal that uses it — from the Identity providers tab in Settings ⚙️ -> Account -> Knowledge -> SSO.
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.