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! Roadmaps ideas 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:
This article discusses proxy votes or ideas portal custom domains. You need to be an Aha! Ideas Advanced plan customer to access these features. Please contact us if you would like a live demo or would like to try using it in your account. If your Aha! account was created before October 20, 2020, you may have access to these integrations, but you will need to upgrade to Aha! Ideas Advanced for any future enhancements.
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 whose settings you wish to edit.
From Ideas -> Overview, click the Pencil icon by the name of the ideas portal whose settings you wish to edit.
Once your ideas portal settings are open, navigate to Users -> SSO.
Click Add new provider.
Choose JSON Web Token as your identity provider Type. Click Save.
-
The JSON Web Token configuration will display. Add a Remote login URL. This is the URL that users should be redirected to in order to authenticate before redirecting back to your ideas portal. Then copy the Callback URL. You will use this when building the JWT response.
Optional: Add a Remote logout URL if you want to send your users to a specific URL when they log out of your portal.
Click Enable SSO to enable the configuration.
Access for Aha! users
Aha! ideas portals prompt the user for their email address to determine if they already have an Aha! account 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 re-directed to login via Aha! Roadmaps to ensure they do not have two separate logins.
When using SSO, email addresses should be managed within the identity provider system. If an email address is modified within Aha! Roadmaps, the email address will be reset to the value in the identity provider system.
The JWT single sign-on process
When a user authenticates using SSO they go through the following process:
The user navigates to your ideas portal, e.g. https://myportal.ideas.aha.io, or if you are using a custom domain, your CNAME, e.g. https://ideas.yourcompany.com.
Your ideas portal recognizes that it 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 your ideas portal using the Callback URL in your SSO configuration, including the JWT response, like the following URL: https://#{account_domain}.identity.aha.io/idea_portal_provider/jwt_callback/123456?jwt=#{payload}&state=#{state}.
The ideas portal validates the JWT response. If this user has never accessed the ideas portal before a new portal user record is created.
The user is granted access to the ideas portal.
It is possible to start the process at step 5 without the user visiting your ideas portal 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 ideas portal.
sub - A unique identifier for the user, different from their email. This is optional but recommended.
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. This URL can be copied from the Callback URL in your SSO configuration:
"https://#{account_domain}.identity.aha.io/idea_portal_provider/jwt_callback?jwt=#{payload}"Here is an example URL:
https://yoursubdomain.identity.aha.io/idea_portal_provider/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" }If the request contains state query parameter then the value of that parameter should also be included in the redirect:
"https://#{account_domain}.identity.aha.io/idea_portal_provider/jwt_callback?jwt=#{payload}&state=#{state}"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.
"https://#{account_domain}.identity.aha.io/idea_portal_provider/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 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.
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! Roadmaps also provides this capability.
Advanced settings
There are two additional advanced settings in your SSO configuration 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. You must also enter a custom CNAME below to enable this feature.
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.
Troubleshooting
If you run into issues with portal SSO:
Start with the integration log messages for your SSO configuration. They often pinpoint the exact claim or setting that you need to adjust.
Review the list of common SSO configuration issues in our knowledge base. These examples include typical problems with claims, scopes, and redirect URLs.
Set contact custom field values
Portal SSO can set idea portal contact custom fields when a user signs in. Your SSO provider (JWT or SAML) sends attributes that map to specific contact custom fields in your Aha! account. Each incoming attribute maps to a contact custom field by its API key and then sets or updates the value on the portal contact. This works for both new and existing portal users.
This capability is useful when you already maintain important user data in your identity provider. You can store an internal user identifier, region, or other key attributes directly on the portal contact. New contacts receive these values at creation. Existing contacts are updated the next time the user signs in, so your Aha! account stays aligned with your source of truth without additional API calls.
To set contact custom field values through portal SSO:
Identify the data you want to sync.
-
Configure custom fields on your contact layout.
Navigate to User menu -> Settings -> Account -> Custom layout.
Edit the contact layout for your account and confirm or create new fields for each attribute you want to sync.
For each field, note the API key exactly as it appears in the configuration. You will use this in your SSO mapping.
-
Map attributes in your SSO identify provider.
Add attributes to the assertion for your portal.
Set each attribute name to match the corresponding contact custom field API key from your Aha! account.
Map each attribute to the correct data source in your identity provider so the value reflects what you want stored in the portal contact.
-
Test with a single user.
Choose a test user in your identity provider and use it to log in to your portal via SSO.
In your Aha! account, open the portal contact record for that user and confirm that the custom fields now contain the expected values.
Share your SSO configuration between portals (Aha! Ideas Advanced plan)
To share your identity provider configuration between multiple ideas portals:
Open each portal's settings.
Once you have your portal settings open, navigate to the Users tab, then the SSO section.
Select the identity provider you just created from the Identity provider dropdown.
Congratulations! You just shared your configuration with another portal.
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.
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.