Set up SSO authentication (on-premises)

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

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 Identity Provider (IdP), which is an online service that authenticates users using security tokens.

It is essential that the ALM Octane SP can identify users uniquely when communicating with the 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

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 Import IdP users for SSO authentication into a workspace (on-premises).

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

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

For details, see Set up SSO authentication (on-premises).

About identifying users

For identification, the ALM Octane SP uses the sso.saml.mapping.username setting in the octane.yml 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 octane.yml SAML Response Description
'{$id}'

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

ALM Octane identifies users by mapping the ALM Octane username to the NameID in the SAML subject.

This is the default.

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

For details, see Map IdP attributes.

Tip: Other octane.yml settings that you can define for mapping purposes include: sso.saml.mapping.uuid, sso.saml.mapping.lastName, sso.saml.mapping.firstName, sso.saml.mapping.fullName, and sso.saml.mapping.mail. For details, see the information about configuring additional ALM Octane SP settings in the installation help for Windows or Linux.

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

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.

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 SiteAdministratorUser setting in the setup.xml 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 octane.yml 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.yml file using the authenticationType 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.
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 octane.yml file, see the ALM Octane Installation Help:       Linux       Windows

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 Linux settings or Windows settings.

    Tip: During the authentication process, the ALM Octane SP sends a SAML request that contains the NameIDPolicy. The NameIDPolicy specifies constraints on the name identifier that represents the requested subject. By default, the requested NameIDPolicy is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. This value can be changed by setting the sso.login.saml2.subject.format setting in the octane.yml file. For details, see the description of the sso.login.saml2.subject.format setting in the octane.yml file under Linux settings or Windows settings.

  • Share ALM Octane’s metadata with the IdP

    To obtain ALM Octane’s metadata, navigate 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.

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 Friendly Name Description
User name username

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 sso.saml.mapping.uuid setting in the octane.yml 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 sso.saml.mapping.mail setting in the octane.yml file.

Full name fullName

The full name of the user if it is different from the firstName and the lastName 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 sso.saml.mapping.fullName setting in the octane.yml 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 sso.saml.mapping.lastName setting in the octane.yml 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 sso.saml.mapping.firstName setting in the octane.yml 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.

For details, see Set up SSO authentication (on-premises).

Test SSO authentication

To log in to ALM Octane using SSO, navigate 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 Import IdP users for SSO authentication into a workspace (on-premises).

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

Back to top

See also: