Configure single sign-on with JSON web token

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! idea portal so that users of your web application can login to the portal and submit ideas using their application credentials.

Click any of the following links to skip ahead: 


To enable SSO for an ideas portal, navigate to Settings ⚙️ > Account > Configure ideas portals, then select the ideas portal you wish to update. You will need to be an administrator with customizations permissions to do this. 

Click on the Single sign-on tab, then choose the JSON Web Token identity provider. Fill in the optional fields, then click Enable to save your changes.


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!


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. 


Access for Aha! users

Aha! ideas portals prompt the user for their email address to determine if they already have an Aha! login. If the email entered is not registered in Aha! they will be redirected to SSO based upon your configuration. If their email address is registered in Aha! they will be re-directed to login via Aha! to ensure they do not have two separate logins.

This setting is selected by default, and can be disabled by unchecking the box Access for Aha! users.

When using SSO, email addresses should be managed within the identity provider system.  If an email address is modified within Aha!, the email address will be reset to the value in the identity provider system.

Note: Disabling this option on custom CNAME portals will prevent Aha! users from accessing the portal.


The JWT single sign-on process

When a user authenticates using SSO they go through the following process:

  1. The user navigates to your private ideas portal, e.g.
  2. Aha! recognizes that your account is configured to use JWT.
  3. The user's browser is redirected to your application using the Remote login URL that you configured on the Configure portal screen.
  4. Your application recognizes that it has received a JWT authentication request.
  5. Your application authenticates the user.
  6. Your application builds a JWT response and redirects the user back to your ideas portal using the URL, including the JWT response.
  7. Aha! validates the JWT response. If this user has never accessed the ideas portal before a new portal user record is created.
  8. The user is granted access to the private ideas portal.

Note that all of the communication between Aha! and your application happens via URL parameters in the user's browser and there is no direct communication between the systems.

It is possible to start the process at step 5 without the user visiting Aha! first.


Building the JWT response

When it receives a JWT authentication request your application must wait for a JWT response. The response should include a HS256-encoded 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 email address is used to uniquely identify the user within the Aha! ideas portal.

Here is sample Ruby code to generate a response:

iat =
jti = "#{iat}/#{rand(36**64).to_s(36)}"

payload = JWT.encode({
:iat => iat,
:jti => jti,
:first_name => "John",
:last_name => "Doe",
:email => "",
}, secret_key)

redirect_to "https://#{subdomain}{payload}"

{ "iat": 158258345634, "jti": "1234567890abcdefg", "first_name": "John", "last_name": "Doe", "email": ""}


Redirecting the user to a specific page after login

After a user successfully logs in to your portal, 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.

redirect_to "https://#{subdomain}{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:

  1. Sign-out from the idea portal. Enter a "Remote logout" URL in the JWT configuration. When the user logs out of the idea portal 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.
  2. 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 ideas portal. This will log the user out of the ideas portal 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, Aha! also provides this capability.


Was this article helpful?
2 out of 4 found this helpful