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.
JSON web token (JWT) is a technique that can be used for single sign-on (SSO) between a custom application and another application. In this case, JWT can be used for SSO to an Aha! knowledge base so that users of your web application can log in to the knowledge base and access documentation using their application credentials.
Click any of the following links to skip ahead:
The JWT single sign-on experience
When a user authenticates using SSO, they go through the following process:
The user navigates to your knowledge base e.g. https://myaccount.aha.site/kb/kbname.
Your knowledge base recognizes that your account is configured to use JWT.
The user's browser is redirected to your application using the Remote login URL that you configured on the JSON Web Token (JWT) configuration screen.
Your application recognizes that it has received a JWT authentication request.
Your application authenticates the user.
Your application builds a JWT response and redirects the user back to knowledge base using the URL https://myaccount.aha.site/auth/jwt/callback?jwt=<encoded token>, including the JWT response.
Your knowledge base validates the JWT response.
The user is granted access to the knowledge base.
All of the communication between your knowledge base and your application happens via URL parameters in the user's browser. There is no direct communication between the systems.
Configuration
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 JSON Web Token SSO 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 JSON Web Token and click Save.
If you already have SSO set up for a separate 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 JSON Web Token configuration will display. Fill in the remaining fields.
Click Enable SSO to enable the configuration.
If the same identity provider configuration is used for more than one knowledge base, then a user may be prompted to choose which knowledge base they are logging in to. If the identity provider supports relay state, or state passthrough, then service provider-initiated logins (when the login starts at your Aha! account) will redirect the user to the correct knowledge base immediately.
Building the JWT response
When it receives a JWT authentication request, your application must generate a JWT response. The response should include a HS256-signed token containing these fields:
iat: The integer time the response was created in seconds since the Unix epoch.
jti: A randomly created token that uniquely identifies this response.
first_name: The first name of the user that was authenticated.
last_name: The last name of the user that was authenticated.
email: The email address of the user that was authenticated.
The name and email fields are not used by the knowledge base, so any values can be used in these fields.
Here is sample Ruby code to generate the JWT payload which is signed and base 64 encoded:
iat = Time.now.utc.to_i
jti = "#{iat}/#{rand(36**64).to_s(36)}"
payload = JWT.encode(
{
iat: iat,
jti: jti,
first_name: "John",
last_name: "Doe",
email: "john.doe@aha.io",
},
secret_key)An example JWT input looks like this. Note that the iat is a number and the other fields are strings:
{ "iat": 158258345634, "jti": "1234567890abcdefg", "first_name": "John", "last_name": "Doe", "email": "john.doe@aha.io" }The URL the user should be redirected back to for login will look like this:
https://#{account_domain}.identity.aha.io/idea_portal_provider/jwt_callback/123456?jwt=#{payload}&state=#{state}If the request contains state query parameter then the value of that parameter should also be included in the redirect. The state query parameter ensures the user is redirected back to the correct knowledge base.
Remote login URL
This field is required. It must contain the URL that users should be redirected to in in order to authenticate before redirecting back to Aha! Knowledge.
Remote logout URL
This field is optional. Use it if you want to send your users to a specific URL after they have logged out of the portal.
Redirecting the user to a specific page after login
After a user successfully logs in to your knowledge base, you can direct them to a specific URL.
The request to the SSO page will contain a parameter named return_to. If this parameter is included in the JWT response, then the user will be redirected to that page after the login process completes. e.g:
"https://#{subdomain}.aha.site/auth/jwt/callback?jwt=#{payload}&return_to=/ideas/APP-I-469"Single sign-out
Single sign-out allows the user to sign out of one application and be automatically signed out of both applications. Single sign-out is optional.
There are two parts of single sign-out:
Sign out from the knowledge base. Enter a Remote logout URL in the JWT configuration. When the user logs out of the knowledge base they will be redirected to this URL. Your application should detect the access of this URL and also log the user out of the application.
Sign out from your application. When the user logs out of your application you should redirect them to the /portal_session/logout URL of the knowledge base. If you are sharing your SSO configuration with another knowledge base, this will log the user out of that knowledge base as well. The user will be redirected back to your application to log in again.
For those who prefer a SAML single sign-on process, your Aha! account also provides this capability.
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.