In March 2024, Microsoft renamed Azure Active Directory (Azure AD) as Entra ID.
You can use Microsoft Entra ID as an identity provider for your Aha! account based on SAML 2.0. You will need to be an in your Aha! account and an administrator in Entra ID to configure SSO.
Click any of the following links to skip ahead:
In Entra ID
Log in to Entra ID. If you have not already done so, select the Entra ID service from the left sidebar.
Click Enterprise applications.
Select All applications from the Application type dropdown.
-
If you do not see Aha! as one of your available applications, you may need to add it. Click New application.
Scroll or search for the Aha! application, then select it.
Click Create.
In the getting started form, Name your application, then move on to the SAML SSO configuration quick start guide.
Otherwise, on the Aha! application integration page, find the Manage section and select Single sign-on.
On the Select a Single sign-on method page, select SAML.
On the Set up Single Sign-On with SAML page, click the pencil icon for Basic SAML Configuration to edit the settings.
-
On the Basic SAML Configuration section, perform the following steps:
In the Sign on URL text box, type a URL using the following pattern:
https://<customdomain>.aha.io/session/newIn the Identifier (Entity ID) text box, type a URL using the following pattern:
https://<customdomain>.aha.io
On the Set up Single Sign-On with SAML page, in the SAML Signing Certificate section, find Federation Metadata XML and select Download to download the certificate and save it on your computer.
On the Set up Aha! section, copy the appropriate URL(s) based on your requirement.
Under Attributes & Claims, the default value for the Unique User Identifier will not work. Instead of user.userprincipalname, please use user.employeeID or user.objectID. The attributes available will depend on your Entra ID account configuration.
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. Change Settings using to Metadata File.
Upload the Federation Metadata XML that your downloaded from Azure AD.
Enter the remaining fields following the SAML 2.0 configuration instructions.
User attributes
The SAML identity provider must be configured to provide four attributes:
EmailAddress
FirstName
LastName
NameID
The NameID attribute must be included in the subject. Your Aha! account uses it to uniquely identify the user (separately from their email address). We recommend using a persistent, unique identifier in this field, rather than the user's email address. 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.
Each user in your Aha! account needs to have a unique NameID. This value must be unique — an email addresses CANNOT be used as a NameID , or else your single sign-on configuration will error.
Your Aha! account will use these attributes to properly identify the user and automatically provision users. You can also configure your provider to include two additional optional attributes:
ProductRole
ProductPrefix
By default, users are provisioned with no access or any assigned role. Therefore, an administrator in your Aha! account will need to set the roles for all users. The exception to this is when the administrator is setting up custom attributes to provision specific users to specific roles and/or permissions, such as when using ProductPrefix and ProductRole.
EmailAddress
Every user in your Aha! account is required to have a valid email address, even when using SSO. Since the identity provider is responsible for managing user information, it must send the user's email address to your Aha! account in its assertion. Identity providers use different naming conventions, so your Aha! account will look for an email address in the following attributes sequentially:
EmailAddress
email
Email
mail
emailAddress
User.email
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
-
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
This attribute is supported for older versions of Azure. It is not recommended.
FirstName
Just like email addresses, identity providers may send the first name in several common fields. To provide out-of-the-box compatibility with most identity providers, your Aha! account will try to find the first name in the following attributes:
FirstName
first_name
firstname
firstName
User.FirstName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
LastName
Just like email addresses, identity providers may send the last name in several common fields. To provide out-of-the-box compatibility with most identity providers, your Aha! account will try to find the last name in the following attributes:
LastName
last_name
lastname
lastName
User.LastName
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
NameID
Each user in your Aha! account needs to have a unique NameID. This value must be unique — an email addresses cannot be used as a NameID. This ensures that any changes to a user's email address can be reflected in 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.
To do this:
Go to the enterprise application in Entra ID.
Select Single Sign-On where SAML should be configured.
Edit attributes and claims. Add one or two new claims.
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, Aha! Ideas, Aha! Whiteboards, and Aha! Knowledge: Settings ⚙️→ Account → Workspaces
Aha! Develop: Settings ⚙️→ Account → Teams
You will need to be an 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, and 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 to do this.
If you set the ProductPrefix attribute, you also need to set the ProductRole attribute.
To do this in Entra ID:
Name the claim ProductPrefix.
Expand the Claim conditions section.
Select User Type as Any.
Select the Entra ID Group to which you want to assign access to this ProductPrefix.
Set the Source as Attribute.
-
Under Value, enter the appropriate Aha! workspace, workspace line, or team Prefix.
Although this appears to be a dropdown to select a value from, you will need to manually enter a prefix here. ProductPrefix is the short code prefix of the hierarchy element, not the element's full name. The prefix is used to code records in that workspace, line, or team. For example, a workspace named Mobile might have a ProductPrefix MBL.
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 in Entra ID:
Name the claim ProductRole.
Expand the Claim conditions section.
Select User Type as Any.
Select the Entra ID Group to which you want to assign access to this ProductRole.
Set the Source as Attribute.
Set the Value to the appropriate user permission role.
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.