Click any of the following links to skip ahead:

In your Aha! account

  1. Log into your Aha! account and go to Settings ⚙️ Account Security and single sign-on Single sign-on.

  2. Select SAML 2.0 as your Identity provider.

  3. Name your configuration.

  4. The SAML 2.0 configuration will display.

  5. Under Configure using, select Metadata file.

Top

In Okta

  1. Log in to your Okta account.

  2. Navigate to Applications.

  3. Click Create App Integration.
    Note: You should not use the pre-configured Aha! SAML integration on the Okta app catalog. It is currently configured incorrectly and will not work.

  4. Select SAML 2.0.

  5. Click Next. The Create SAML Integration builder will open.

  6. For the General Settings tab:

    1. Name your application. Click Next.

  7. For the Configure SAML tab:

    1. 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.

    2. If it is not already checked, check the box to Use this for Recipient URL and Destination URL.

    3. Back in your Aha! account SSO configuration, copy the SAML entity ID.

    4. Audience URI: Paste your copied SAML entity ID here.

    5. Name ID format: Unspecified.

    6. Application username: Custom.

      1. 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.
        Note: 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.

    7. Update application username on: Create and update.

    8. Attribute Statements:

      1. Attribute: FirstName | Value: user.firstName

      2. Attribute: LastName | Value: user.lastName

      3. Attribute: EmailAddress | Value: user.email
        Note: These attributes are case sensitive. Make sure you copy them in exactly.

    9. At the bottom of the page, click Next.

  8. For the Feedback tab:

    1. Answer the question. Click Next.

Top

Back in your Aha! account

  1. 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.

    1. Under Optional, copy the IDP metadata XML.

  2. Open a new file in a plaintext text editor like Notepad (PC) or TextEdit (Mac).

    1. Paste in the IDP metadata XML you copied from Okta.

    2. Save your file. This is now the Metadata file that you need on the Aha! side.

  3. In your Aha! account SSO configuration page:

    1. Metadata file: Select Metadata file.

    2. Click Choose file. Choose the metadata file you just created.

    3. Scroll down and click Update configurations.

Congratulations! You have successfully configured Okta SSO.

Top

Assign users to your Okta application

  1. In your Okta application configuration, navigate to the Assignments tab.

  2. Click the Assign dropdown, then click Assign to people or Assign to groups.

    1. 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.

    2. If you chose to Assign to groups, select the appropriate group(s), then click Done.

  3. The Username modal will appear, along with a unique persistent ID for this user.
    Note: 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.

  4. Click Save and go back to accept the user ID.

  5. Click Done when you have finished assigning users.

Top

Update existing users

The Custom rule you added in the initial configuration will ensure that newly assigned users will have the unique identifiers that Aha! requires. If you added users before you created the Custom rule you will need to update them to apply that rule to them.

  1. On the Sign-on tab, scroll down to the Credentials details section.

  2. Update application username on should be set to Create and update.

  3. Click Update now.

All your existing users will now have unique identifiers.

Top

Test the configuration

  1. In an incognito or private browser window, navigate to your Aha! account.

  2. The Okta SSO login page will load.

  3. Input your credentials.

  4. Click Sign in.

If configured correctly, you should now be logged in to your Aha! account.

Top

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.

ProductPrefix

The ProductPrefix role 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 and Aha! Ideas: 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.

Note: If you set the ProductPrefix attribute, you also need to set the ProductRole attribute.

To do this:

  1. In Okta, select your Application.

  2. From that Application configuration, select the Configure SAML tab.

  3. Scroll down to Group attribute statements. Click Add another.

    1. Attribute: ProductPrefix | Value: productPrefix

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 permission roles and must be one of the following:

  • product_owner

  • contributor

  • reviewer

  • viewer

  • none

To do this:

  1. In Okta, select your Application.

  2. From that Application configuration, select the Configure SAML tab.

  3. Scroll down to Group attribute statements. Click Add another.

    1. Attribute: ProductRole | Value: productRole

Top

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.

Top

If you get stuck, please reach out to our Product Success team. Our team is made up entirely of product experts and responds fast.

Suite overview
Aha! Roadmaps
    Roadmaps
    Integrations
    Aha! Ideas
    Aha! Develop
    Videos
    Announcements