Set up SSO authentication

This topic describes how to set up on-premises SSO authentication for connecting to ALM Octane.

Note: SAML2 is supported both as a Service Provider for user authentication for federated customers, and as an Identity Provider for supporting SAML requests from other products SPs.

Overview

This topic describes how SSO access to ALM Octane can be authorized in a federated environment. This way, users can use single sign-on for logging into ALM Octane as they do with other SSO applications at the site.

To facilitate single sign-on, the ALM Octane service provider (SP) sends an authentication request to the IdP, which is an online service that authenticates users using security tokens.

It is essential that the ALM Octane service provider (SP) can identify users uniquely when communicating with the Identity Provider (IdP). This is a two-step process.

  1. Authorization. When a user logs in, ALM Octane attempts to locate a matching user in the IdP. For details, see About authorizing users.

  2. Identification. After a user is authorized to log in, ALM Octane identifies which user it is. For details, see About identifying users.

Service providers and protocols

The following providers and protocols are used:

  • ALM Octane has its own built-in service provider (SP) for this purpose.

  • ALM Octane's SSO integration uses the SAML2 protocol for authentication with identity providers (IdPs).

  • ALM Octane uses the OAuth2 protocol for creating access tokens and validating them.

About authorizing users

When a user logs in, ALM Octane attempts to locate a matching user in the IdP.

Scenario Description and result
A matching user exists

ALM Octane checks by uuid, and then by name. If either of these is located successfully, the user is authorized.

If the details of the user do not match, the details are updated in ALM Octane and the user is authorized.

No matching user exists

The user is not authorized and cannot log in.

Users can be imported from the IdP into ALM Octane using a CSV file. After the import, the user can log in.

For details on importing, see Users.

Example: Assume the following users are defined in the IdP and the ALM Octane SP:

Identity Provider (IdP) ALM Octane Service Provider (SP)
UUID Name UUID Name
100 Carlos 100 Carlos
200 Sally 400 Sally
300 Lee 300 Svetlana
    900 George

  • A user named Carlos with uuid 100 attempts to log in.

    Carlos is authorized.

  • A user named Svetlana with uuid 300 attempts to log in.

    The user is authorized. The name in ALM Octane is updated to Lee.

  • A user named Sally with uuid 400 attempts to log in.

    Sally is authorized. The uuid in ALM Octane is updated to 200.

  • A user named George with uuid 900 attempts to log in.

    Authorization fails.

About identifying users

For identification, the ALM Octane SP uses the mapping. user-name setting in the sso.conf file to determine how to map the ALM Octane username attributes to the corresponding IdP attribute after receiving the SAML response from the IdP. The mapping is based on the following: 

Setting in sso.conf SAML Response Description
'{$id}'

<saml2:NameID> attribute, in the <saml2:Subject>

ALM Octane identifies users by mapping the ALM Octane user-name to the NameID in the SAML subject.

This is the default.

user-name The FriendlyName username in the <saml2:Attribute> in the <saml2:AttributeStatement> ALM Octane identifies users by mapping the ALM Octane user-name to the username attribute in the SAML attribute statement.

For details, see Map IdP attributes.

Tip: Other sso.conf settings that you can define for mapping purposes include: mapping uuid, mapping last-name, mapping first-name, mapping full-name, and mapping-mail. For details, see Modify site settings.

Handling existing internal users

Existing internal users defined in ALM Octane from before switching to SSO authentication already have passwords. These passwords are not overridden when the user is mapped to IdP users. However, the users cannot use these original ALM Octane passwords to log into ALM Octane once configured for SSO, even when directly navigating to the ALM Octane login page. They are defined, but the SSO passwords are the only ones in use.

For details, see Import users .

Back to top

Prerequisites

If you are using SSL with a self-signed or internal certificate, add the certificate to the CA store of the JVM runtime used to run ALM Octane for authentication to succeed.

Back to top

Configure ALM Octane and its SP

Configure ALM Octane and its service provider (SP) for SSO integration.

Verify that the initial admin is available in the IdP

The first user created in ALM Octane has superuser permissions and is allowed to perform any action in the system. In effect, the initial user is a site admin, a space admin, and a workspace admin for all default spaces.

This user is defined using the site-administrator > name setting in the octane.conf file.

Make sure that this admin already exists in the IdP.

Later, you can import additional IdP users. For details, see Import users .

Enable the ALM Octane SP

Modify the sso.conf file to configure the ALM Octane SP.

For these settings to take affect, make sure to set the authentication type to sso in this octane.conf file using the authentication-type setting.

Not all settings are required. Make sure to comment out unnecessary settings using the hash (#) at the beginning of a line.

These available settings include: 

Keystore settings

Include settings that provide the SP with the certificates needed to sign and encrypt authentication messages.

Note: If you are using pkcs12, you must use the same password for both the keystore and the key(s). This is a Java limitation.
OAuth settings For configuring internal OAuth authentication details.
Logging settings For changing the SP's logging level.
SAML metadata settings For establishing trust.
Redirect URI settings Which contain the allowed addresses for redirection. This is used to validate that an authenticated user is not redirected to an incorrect place.

For details on the settings to add to the sso.conf file, see Modify site settings.

Restart ALM Octane.

Back to top

Establish SAML trust between the ALM Octane's SP and the IdP

Establishing trust between the ALM Octane service provider (SP) and the IdP requires sharing metadata between the providers.

  • Share the IdP's metadata with ALM Octane

    While enabling the SP, the IdP’s metadata was already shared.

    The metadata can be supplied with a URL or by a file. For details, see Modify site settings.

  • Share ALM Octane’s metadata with the IdP

    To obtain ALM Octane’s metadata, go to:

    <protocol>://<host>:<port>/osp/a/au/auth/saml2/sp-metadata

    The metadata is available only after the ALM Octane server starts. For details, see Enable the ALM Octane SP.

    Any additional IdP configuration is not covered here. See the documentation for the IdP. Generally, however, depending on your individual IdP, you either provide this URL in the IdP’s configuration screens, or save the XML and import it into the IdP. This configures the ALM Octane SP as a client for your IdP.

Back to top

Map IdP attributes

Map the user attributes that are returned by the IdP in a SAML assertion to the equivalent ALM Octane attributes. There are two ways to define user attributes by SAML - either using Attribute Name, or using Attribute FriendlyName, as described in the examples below.

The attributes are case-sensitive.

The SAML response must be signed. Encryption is optional.

Note: ALM Octane overrides the built-in attributes with the ones supplied by the IdP, keeping them up-to-date with your IdP definitions.

ALM Octane Attribute IdP Attribute Description
User name username

This mapping is mandatory. The SSO functionality will not work without the username attribute mapping.

If set to '{$id}', the ALM Octane username is mapped to the NameID in the SAML subject.

If set to username, the ALM Octane username is mapped to the NameID in the SAML AttributeStatement section.

The value may be changed to the name of any other attribute sent in the SAML response.
UUID uuid

The uuid of the user.

If the IdP sends updated information in the SAML assertion, the updates override existing information in ALM Octane.

If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping uuid setting in the sso.conf file.
Email mail

The email of the user.

If the IdP sends updated information in the SAML assertion, the updates override existing information in ALM Octane.

If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping mail setting in the sso.conf file.

Full name fullName

The full name of the user if it is different from the first-name and the last-name together.

If the IdP sends updated information in the SAML assertion, the updates override existing information in ALM Octane.

If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping full-name setting in the sso.conf file.

Last name lastName

The last name of the user. 

If the IdP sends updated information in the SAML assertion, the updates override existing information in ALM Octane.

If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping last-name setting in the sso.conf file.

First name firstName

The first name of the user. 

If the IdP sends updated information in the SAML assertion, the updates override existing information in ALM Octane.

If the Friendly Name for this attribute is different in the IdP, you can specify the correct Friendly Name using the optional mapping first-name setting in the sso.conf file.

Tip: Mapping by uuid is not required, but recommended.

To facilitate automatic synchronization of user details from the IdP to ALM Octane, the uuid (the user identifier, similar to the user name) should be unique and stable. This means the attribute should not be something that is likely to change, such as email.

(Using the uuid as the user identifier allows you to change the user name, if necessary.)

If the uuid is not provided for mapping, ALM Octane tries to synchronize user details based on the mapped userName or the subject in the SAML response. However, if this value is later changed on the IdP side, ALM Octane will not be able to identify the user.

Here is a sample of SAML using Attribute Name:

 <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name">
        <AttributeValue>Christopher</AttributeValue>
  </Attribute>

If you are using Attribute Name, the sso.conf mapping should look like this (for example):

mapping user-name: 'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'

Here is a sample of SAML using Attribute FriendlyName:

<saml:Attribute FriendlyName="username"
                      Name="username"
                      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                             xsi:type="xs:string">liat.vilner@mail.com</saml:AttributeValue>
      </saml:Attribute>

If you are using Attribute FriendlyName, the sso.conf mapping should look like this (for example):

mapping user-name: username

Back to top

Test SSO authentication

Test authentication for the ALM Octane UI and APIs:

To log in to ALM Octane using SSO, go to ALM Octane’s URL. You should be redirected to your IdP’s login screen.

Log in with the ALM Octane admin credentials.

You are redirected to ALM Octane and you can now use the application.

Back to top

Import users

Import users and assign their permissions in the ALM Octane Settings area.

For details on importing users, see Users.

Once imported into ALM Octane, these users can log in with SSO.

Back to top

See also: