Okta
Single sign-on (SSO) allows users of your Aha! account to log in using your existing SAML 2.0 identity provider, such as Okta. This means users do not have to keep track of yet another email and password. It also makes provisioning new users simple. For accounts that already have local users, you can switch them to Okta or keep their settings the same.
Click any of the following links to skip ahead:
In your Aha! account
Log into your Aha! account and go to Settings ⚙️ Account Security and single sign-on Single sign-on.
Select SAML 2.0 as your Identity provider.
Name your configuration.
The SAML 2.0 configuration will display.
Under Configure using, select Metadata file.
In Okta
Log in to your Okta account.
Navigate to Applications.
Click Create App Integration.
The pre-configured Aha! SAML integration uses email addresses for the NameID, which is not a best practice. We recommend following the steps in this article instead.
Select SAML 2.0.
Click Next. The Create SAML Integration builder will open.
For the General Settings tab:
Name your application. Click Next.
For the Configure SAML tab:
Single sign-on URL: Copy this URL from the SAML consumer URL field on your Aha! account SAML configuration page. The URL should be the URL for your Aha! account, followed by
/auth/saml/callback. E.g.https://accountname.aha.io/auth/saml/callback.If it is not already checked, check the box to Use this for Recipient URL and Destination URL.
Back in your Aha! account SSO configuration, copy the SAML entity ID.
Audience URI: Paste your copied SAML entity ID here.
Name ID format: Unspecified.
Application username: Custom.
Custom rule:
user.getInternalProperty('id'). This custom rule tells Okta to create a persistent unique ID for every new user. If you have already added users to this application, you will need to update them.You must use a unique identifier so that your Aha! account can maintain a mapping between the user record in your Aha! account and within your identity provider. This ensures that any changes to the email address within the identity provider will be transparently reflected in your Aha! account.
Update application username on: Create and update.
Attribute Statements:
Attribute:
FirstName| Value:user.firstNameAttribute:
LastName| Value:user.lastNameAttribute:
EmailAddress| Value:user.emailNote: These attributes are case sensitive. Make sure you copy them in exactly.
At the bottom of the page, click Next.
For the Feedback tab:
Answer the question. Click Next.
Back in your Aha! account
Before you leave Okta, click View SAML setup instructions on the right side of the page. A new browser tab will open showing you everything you need to configure Okta in your Aha! account.
Under Optional, copy the IDP metadata XML.
Open a new file in a plaintext text editor like Notepad (PC) or TextEdit (Mac).
Paste in the IDP metadata XML you copied from Okta.
Save your file. This is now the Metadata file that you need on the Aha! side.
In your Aha! account SSO configuration page:
Metadata file: Select Metadata file.
Click Choose file. Choose the metadata file you just created.
Scroll down and click Enable.
Congratulations! You have successfully configured Okta SSO.
Assign users to your Okta application
In your Okta application configuration, navigate to the Assignments tab.
Click the Assign dropdown, then click Assign to people or Assign to groups.
If you chose to Assign to people, select from the existing users and click Assign to assign a user to the Okta application's people.
If you chose to Assign to groups, select the appropriate group(s), then click Done.
The Username modal will appear, along with a unique persistent ID for this user.
This is an important step, since it indicates that you applied the Custom rule to use
user.getInternalProperty('id')correctly. You must use a unique identifier so that Aha! can maintain a mapping between the user record in Aha! and within your identity provider. This ensures that any changes to the email address within the identity provider will be transparently reflected in your Aha! account.Click Save and go back to accept the user ID.
Click Done when you have finished assigning users.
Update existing users
The Custom rule you added in the initial configuration will ensure that newly assigned users will have the unique identifiers that your Aha! account requires. If you added users before you created the Custom rule you will need to update them to apply that rule to them.
On the Sign-on tab, scroll down to the Credentials details section.
Update application username on should be set to Create and update.
Click Update now.
All your existing users will now have unique identifiers.
Test the configuration
In an incognito or private browser window, navigate to your Aha! account.
The Okta SSO login page will load.
Input your credentials.
Click Sign in.
If configured correctly, you should now be logged in to your Aha! account.
Configure custom attributes
This is an optional step but a useful one. You can provision your Aha! users with user and hierarchy permissions. This makes it easier for new users to engage with your Aha! account and saves you time managing users individually.
Okta will allow you to configure custom attributes in two places. We recommend configuring these at the Attribute statements level if you are not using Groups in Okta.
ProductPrefix
The ProductPrefix attribute grants a user access to specific Aha! workspaces, workspace lines, or teams.
You can find a list of workspace prefixes by navigating to:
Aha! Roadmaps, Aha! Ideas, Aha! Whiteboards, and Aha! Knowledge: Settings ⚙️ Account Workspaces
Aha! Develop: Settings ⚙️ Account Teams
You will need to be an administrator with customization permissions to access these pages.
The workspace or team you select with ProductPrefix is added to the user only at the time that they are first provisioned. It will not update if you change this attribute later. This attribute is very handy for giving new users a default workspace or team when they first join your account. For advanced hierarchy permissions, navigate to:
Settings ⚙️ Account Users
You will need to be an administrator with billing permissions to do this.
If you set the ProductPrefix attribute, you also need to set the ProductRole attribute.
To do this:
In Okta, select your Application.
From that Application configuration, select the Configure SAML tab.
Scroll down to Attribute statements. Click Add another.
Attribute:
ProductPrefix| Value: [your workspace or workspace line prefix]
ProductRole
The ProductRole attribute works in conjunction with the ProductPrefix attribute and allows you to specify which level of access a user should have.
ProductPrefix is only used when a user is initially provisioned. Values match with Aha! user permissions and must be one of the following:
product_owner
contributor
reviewer
viewer
none
To do this:
In Okta, select your Application.
From that Application configuration, select the Configure SAML tab.
Scroll down to Attribute statements. Click Add another.
Attribute:
ProductRole| Value: [the product role you have selected from the list above]
New user experience
Users logging in to your Aha! account with Okta SSO are separate accounts from those who log in with an email and password. If an email and password user exists who has a matching email address to an Okta SSO user, that user will be automatically converted to use Okta SSO. Otherwise, a new user will be automatically provisioned.
Auto-provisioned users fall under the same seat restrictions as any other user. Attempts to log in may fail if you have no seats available in your Aha! account.
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.
