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

Click any of the following links to skip ahead:

• Configuration

• Remote login URL

• Remote logout URL

• Access for Aha! Ideas users

• The JWT single sign-on experience

• Building the JWT response

• Redirecting a user to a specific page after login

• Single sign-out

• Share your SSO configuration between portals (Advanced plan)

• Troubleshooting

Configuration

To do this, you will need to open your ideas portal settings. Navigate to Settings ⚙️ → Account → Ideas -> Ideas portals or Ideas → Overview. You will need to be an administrator with customizations permissions to configure an ideas portal.

• From your account settings, click the name of the ideas portal you wish to edit.

• From Ideas → Overview, click the pencil icon by the name of the ideas portal you wish to edit.

Once your ideas portal settings are open, navigate to Users → SSO.

1. Click Add new provider.

2. Choose JSON Web Token as your identity provider Type. Click Save.

3. The JSON Web Token configuration will display. Fill in the remaining optional fields.

4. Click Enable SSO to enable the configuration.

If the same identity provider configuration is used for more than one ideas portal, then a user may be prompted to choose which portal (or 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 Aha!) will redirect the user to the correct portal immediately.

Top

Remote login URL

This field is required. It must contain the URL that users should be redirected to in order to authenticate before redirecting back to your Aha! account.

Top

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.

Top

Access for Aha! Ideas 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 your Aha! account, they will be redirected to SSO based upon your configuration. If their email address is registered in your Aha! account, they will be redirected to login via your Aha! account to ensure they do not have two separate logins.

This setting is selected by default and can be disabled by navigating to Settings ⚙️→ Account → Ideas -> Single sign-on, clicking your identity provider, and unchecking the box next to Access for Aha! users.

It is possible to invite an ideas portal user from your ideas portal settings who has not been configured with the identity provider your portal is using. The user will not be able to log in to the ideas portal until they can be authenticated by the identity provider.

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.

Disabling this option on custom CNAME portals, available to Ideas Advanced users, will prevent Aha! users from accessing the portal.

There are two additional advanced settings beneath Access for Aha! users. They are disabled by default, and most Aha! accounts will not need to use them — in fact, unless you configure these settings carefully, you can break your SSO configuration. If 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. It may be useful if your customers have strict corporate networking policies. Enabling this option causes SSO to use the CNAME as well. This is not necessary for most portals, even when using a CNAME for the portal. It may be useful if your customers have strict corporate networking policies.

• CNAME: This must match an existing CNAME used in an active ideas portal 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.

Top

The JWT single sign-on experience

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

1. The user navigates to your private ideas portal, e.g. https://myaccount.ideas.aha.io/, or if you are using a custom domain, your CNAME, e.g. https://ideas.yourcompany.com.

2. Your Aha! account 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 JSON Web Token (JWT) configuration 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 https://myaccount.ideas.aha.io/auth/jwt/callback?jwt=<encoded token>, including the JWT response.

7. Your Aha! account 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.

All of the communication between your Aha! account and your application happens via URL parameters in the user's browser. There is no direct communication between the systems. It is possible to start the process at step 5 without the user visiting your Aha! account first.

Top

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 email address is used to uniquely identify the user within the Aha! ideas portal.

Here is sample Ruby code to generate a response:

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)

Here is the format of a URL used for login:

"https://#{subdomain}.ideas.aha.io/auth/jwt/callback?jwt=#{payload}"

Here is an example URL:

https://yoursubdomain.ideas.aha.io/auth/jwt/callback?jwt=your-jwt

Your URL will generate a JWT that looks like this:

{ "iat": 158258345634, "jti": "1234567890abcdefg", "first_name": "John", "last_name": "Doe", "email": "john.doe@aha.io" }

The JWT is provided back to Aha! by redirecting the user to the callback URL and including the JWT as a parameter:

"https://#{subdomain}.ideas.aha.io/auth/jwt/callback?jwt=#{payload}"

If the request contains state query parameter then the value of that parameter should also be included in the redirect:

"https://#{subdomain}.ideas.aha.io/auth/jwt/callback?jwt=#{payload}&state=#{state}"

When using an identity provider configuration that is shared across multiple portals, the format of the callback URL will be a little different:

"https://#{account_domain}.identity.aha.io/idea_portal_provider/jwt_callback/123456?jwt=#{payload}&state=#{state}"

Top

Redirecting a 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:

"https://#{subdomain}.ideas.aha.io/auth/jwt/callback?jwt=#{payload}&return_to=/ideas/APP-I-469"

Top

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, your Aha! account also provides this capability.

Top

Share your SSO configuration between portals (Advanced plan)

If you have added Ideas Advanced functionality to your Aha! account, the process to create and assign an identity provider looks a little different.

1. Follow the same steps in Azure AD listed above.

2. Navigate to Settings ⚙️→ Account → Ideas portals or Ideas → Overview. You will need to be an administrator with customizations permissions to configure an ideas portal.

   1. From your account settings, click the name of the ideas portal you wish to edit.

   2. From Ideas → Overview, click the pencil icon by the name of the ideas portal you wish to edit.

3. Once you have your portal settings open, navigate to the Users tab, then the SSO section.

4. Select Add new provider from the Identify Provider dropdown.

   1. Name: Name your identity provider.
      Note: We recommend that you name your provider something easily recognizable to the different portals that might want to use it, like Employees, or Customers.

   2. Type: Choose JWT as your identity provider type.

   3. Click Save and continue in Aha!

   4. Enter the remaining fields following the JWT configuration instructions.

5. Click Enable SSO to enable your identity provider.

To share your identity provider configuration between multiple ideas portals:

1. Open each portal's settings.

2. Once you have your portal settings open, navigate to the Users tab, then the SSO section.

3. Select the identity provider you just created from the Identity provider dropdown.

4. Congratulations! You just shared your configuration with another portal.

5. Repeat these steps for each portal you wish to use the shared Identity provider configuration.

You can manage your identity provider configuration — and the portals that use it — from the Identity providers tab in Settings ⚙️→ Account → Ideas portals.

Top

Troubleshooting

If you run into trouble, we have gathered common SSO configuration issues into one article, along with common resolutions.

The best place to start in most of these situations is the integration log messages for your SSO configuration. Those messages will help diagnose and solve the problem.

Top