Single sign-on: SAML 2.0

Single Sign-On -- known as SSO -- allows users of your Aha! account to log in using your existing SAML-enabled ID provider, such as Active Directory, OneLogin, PingIdentity, Okta and many more. This means that users don't have to keep track of yet another email and password. It also makes provisioning new users a breeze. For accounts that already have local users, you can switch them to SAML or keep them the same. See the end of this note for help. 

How SAML works

SAML (Security Assertion Markup Language) is a standard protocol that gives identity providers (IdP) a secure way to let a service provider (SP) such as Aha! know who a user is. It does this by sending Aha! a cryptographically signed XML document confirming users' identities, along with some basic user information.

Once configured, users can authenticate with the following process:

  1. The user navigates to your Aha! account (e.g. https://myaccount.aha.io/)
  2. Aha! presents the user with an additional login option ("Login with {name of your provider}")
  3. When clicked, the user's browser will be redirected to the identity providers
  4. The identity provider authenticates the user
  5. Once authenticated, the browser is redirected to Aha! with a SAML assertion
  6. Aha! verifies the SAML assertion and provisions new users
  7. User is granted access to Aha!
  8. User is redirected to original link (if prior authentication was required)

Configuring Single Sign-On with SAML

To get started, go to Settings -> Account -> Profile and click "Enable SSO". This will display the SSO settings where you can give your SSO provider a name (required) and add details of your identity provider.

Aha! supports the SAML 2.0 standard, which provides a few ways to streamline configuration. Although each identity provider will have different interfaces and nuances, most provide configuration metadata as a URL or downloadable file. Since each identity provider is unique, we will only cover using Aha! with a generic SAML identity provider in this article.

Changing SAML 2.0 SSO Identity Provider

Switching identity providers in your SAML 2.0 SSO implementation will first force disabling the current provider before switching to another helping to avoid SSO identify provider conversion issues. 

Metadata URL

The first -- and easiest -- way to configure SSO is to use a link to your identity provider's metadata file if they provide one. Simply select, "Metadata URL," enter the URL, and click, "Update." Aha! will download the configuration file, parse it, and configure everything.

Metadata File

Some identity providers require you to download the metadata file instead of giving you a link. In that case, select "Metadata File," choose the file you downloaded from your identity provider, and click "Update." This sends the file to Aha! where it is parsed and the crucial information is extracted.

It is important to note that Aha! does not save the metadata file. If you must make any configuration changes, you will need to upload the file again or make changes using the "Manual Settings."

Manual Settings

Sometimes, you just need a little more control. That's where the "Manual Settings" option comes in. Only two things are needed for SAML to work -- the SSO Endpoint and certificate fingerprint. The SSO Endpoint tells Aha! where to find the identity provider. The certificate fingerprint lets us verify that we are talking to the correct identity provider. Multiple IDP certificate fingerprints can be provided which helps compatibility with Microsoft ADFS which often uses multiple signing certificates. 

Some identity providers will give you a certificate, but not a certificate fingerprint. If this is the case, you can usually inspect the certificate on your local machine to get the fingerprint. Aha! expects the fingerprint to be a SHA-1 of the certificate in the format "F4:DC:06:92:D4:FC:40:DF:FD:A6:53:78:32:AA:52:39:3E:AA:6E:54".

User Attributes

One reason SAML 2.0 has become so popular is its flexibility when sending extra information to the service provider. When an identity provider sends an assertion, it includes attributes describing the user. These attributes allow Aha! to properly identify the user, and automatically provision users.

The NameID attribute must be included in the subject and it is used by Aha! 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. If a unique identifier is used then changes in the user's email address in the directory server will be transparently reflected in Aha!

Note: By default, users are provisioned with no access or any assigned role.  Therefore, the Aha! admin will need to set the roles for all users.  The exception to this is when the admin is setting up custom attributes to provision specific users to specific roles and/or products within Aha!  See ProductPrefix and Product Role below.

EmailAddress

Every user on Aha! 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 Aha! in its assertion. Identity providers use different naming conventions, so Aha! 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

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, Aha! 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

Aha! looks for the last name in the following attributes:

  • LastName
  • last_name
  • lastname
  • lastName
  • User.LastName
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

ProductPrefix (optional)

If your identity provider supports custom attributes, you can set the ProductPrefix attribute to automatically grant access to a specific product or product line. This can be set to any valid product prefix on your account, and requires that you also set the ProductRole attribute (see below). The product is only added at provision time, and doesn't update if changed. It is very handy for giving new users a default product. For advanced product permissions, you will want to manage users directly in Aha!

ProductRole (optional)

The ProductRole attribute works in conjunction with the ProductPrefix attribute, and allows you to specify which level of access a user should have. Just like ProductPrefix, this is only used when a user is initially provisioned. Values match with roles in Aha! and must be one of the following:

  • product_owner
  • contributor
  • reviewer
  • viewer
  • none

When users exist in Aha! before you implement SSO

You can have a mix of SAML and password users in the same account. The first time a password user logs in with SAML, their account will be converted to use SAML automatically. Subsequently, the user will not be able to log in using their password again. This is so that if the user account is disabled via SAML, they will not be able to bypass that and log in with their password.

It is possible for Aha! Administrators to manually convert users back to using a password in Settings -> Account -> Users. All history for the user will be maintained during this process.

There is one exception to this process. If the user belongs to multiple Aha! accounts (which is not common), then they cannot use SSO (this is to prevent SSO in one account from being used to attack another account). In this case, when the user logs in with SAML, a *new* user will be created. Accordingly, permissions and history will not be inherited.

When users exist in the Ideas Portal before you implement SSO

When a user authenticates to the Ideas portal, they will be presented with the option to authenticate to the portal via SSO only. If they are already logged in to the SSO provider, they will automatically be logged in to your portal without any additional actions.

  • Public portal: Once SSO is configured, users will be prompted to log in before posting or voting ideas. Anyone can view ideas, regardless of whether they are logged in.
  • Private portal: In order to access the portal, users will be prompted to log in via SSO. If SSO is configured, any user with the SSO account will be able to access the Ideas portal, regardless of email domain.

Note: When an Ideas Portal user tries to login using SSO for the first time it will convert the email address account to SSO, and keep their idea submissions intact.

 

Was this article helpful?
3 out of 3 found this helpful
Have more questions? Submit a request

Roadmap software to manage your products.
Finally, connect strategy to execution.

Powered by Zendesk