Setting up SSO Authentication

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

Note: For CAC (Common Access Card) and SiteMinder, see the ALM External Authentication Configuration Guide.

Overview

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

To facilitate single sign-on, the ALM 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 service provider (SP) can identify users uniquely when communicating with the Identity Provider (IdP).

About authorizing users

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

Scenario Description and result
A matching user exists ALM checks by IdentityKey and IdP ID. If both of these are located to one user, the user is authorized.
No matching user exists

The user is not authorized and cannot log in.

If user auto-provisioning is enabled, the auto-provisioning page will open for the user to create a matching ALM user by using the default username as specified in (Optional) Configure user auto-provisioning.

Back to top

Prerequisite

You already obtain a certificate (or a keystore file to store the certificate) that is used for ALM SP to sign SAML 2 and OAuth token.

The keystore file will be uploaded to SSO Configuration Tool.

Make sure the https certificate for the ALM Server, reverse proxy, or IdP is added to the Trusted store of the JVM runtime that is used to run ALM for authentication to succeed.

If ALM is deployed in a cluster environment, the SSO authentication requires that the system time on all ALM nodes and on users' IdP servers are synchronized as closely as possible. The systems on these servers can be configured to use a network time synchronization protocol such as the Network Time Protocol (NTP). If the time on any ALM node is different from the time on the IdP server, the authentication fails.

Back to top

Configure ALM SP

  1. Log in to ALM Site Administration.
  2. Click Tools > SSO configuration to open SSO Configuration Tool.

  3. Click General Settings > Properties and provide the following information.

    Field Description
    OAuth Client Secret The secret used by ALM service provider (SP) to generate access token.
    Communication FQDN ALM Server FQDN (fully qualified domain name) If a Web Server/Reverse Proxy is used in front of ALM Server, it should be the Web Server FQDN.
    Communication Port

    ALM Server port number If a Web Server/Reverse Proxy is used, it should be the Web Server port number.

    The port may be rewritten. You can check with your Network Team to get the port.

    Secure Communication Enabled?

    Whether or not the ALM Server uses HTTPS protocol (TLS)

    If a Web Server/Reverse Proxy is used, it should be whether or not the Web Server uses HTTPS protocol (TLS).The protocol may be rewritten. You can check with your Network Team.

    Use Reverse Proxy Whether or not to use reverse proxy If yes, you should also specify reverse proxy port.
    Reverse Proxy Port Port number of reverse proxy
    Secure Reverse Proxy Enabled? Whether or not the reverse proxy uses HTTPS protocol (TLS)
  4. Click Save to save the settings.
  5. Click General Settings > SAML2 Certificate to configure the certificate.

    You can configure the certificate either by uploading the keystore file or by entering the certificate information manually.

    To configure your certificate by uploading a keystore file
    1. In the Certificate Submission Type filed, select Upload Keystore File.
    2. In the Choose File to Upload field, select the keystore file that contains the certificate.
    3. Enter the keystore and certificate passwords.
    4. Enter the alias of the certificate that is used in the keystore file.
    5. Click Submit.
    To configure your certificate by entering certificate information manually
    1. In the Certificate Submission Type filed, select Manually Enter.
    2. Enter the keystore and certificate passwords, certificate chain, and private key.
    3. Click Submit.

    What if you want to update certificate?

    1. Delete the current certificate that is stored in the directory {ALM Deploy Directory}\ALM\repository\sa\DomsInfo\osp\basic.pfx.
    2. Refresh the current page.
    3. Re-submit certificate information as described in step 5.
    4. Restart ALM Server. If ALM is in a cluster environment, restart each node.
    5. If you have shared ALM SP metadata with your IdP, you should obtain the updated SP metadata and share it with IdP again. See Configure IdP.

Back to top

Add IdP

You should start with adding the default IdP named "alm". The configuration includes user auto-provisioning settings and IdP metadata settings. Here is a summary of the configuration:

  1. Click alm.
  2. (Optional) Configure user auto-provisioning.
  3. Share IdP metadata with ALM SP.
  4. Click Save to save IdP configurations.
  5. Click Add New IdP to add other IdPs.

    You can add other IdPs only after you successfully validate alm IdP and enable SSO.

    See Validate and enable SSO authentication.

(Optional) Configure user auto-provisioning

If a user exists in your IdP but does not exist in ALM, user auto-provisioning creates an ALM account for the user by using the mapped SAML field.

The following settings are to enable user auto-provisioning.

  1. Click the IdP ID, for example, alm.

  2. In the SAML Field Mapped with Default ALM Username field, select a field whose value would be used as default ALM username during auto-provisioning.

    • IdentityKey: If you select IdentityKey, the SAML token must include the “IdentityKey” attribute. And this field is always required regardless of how you configure user auto-provisioning.

    • ALMUsername: If you select ALMUsername, the SAML token must include the “ALMUsername” and “IdentityKey” attributes.

    • ALMEmail: If you select ALMEmail, the SAML token must include the “ALMEmail” and “IdentityKey” attributes.

    • OFF: If you select OFF, you disable user auto-provisioning.
  3. In the Default ALM Username Editable? field, decide whether or not users can change their default ALM usernames during auto-provisioning.
  4. Click Save.

Share IdP metadata with ALM SP

The IdP metadata can be supplied with a URL or XML text.

  • IdP Metadata URL: The IdP’s URL for publishing IdP metadata.

    Choose this if the IdP metadata URL can be accessed by the ALM server.

  • IdP Metadata: Base 64 encoded XML of the SAML metadata descriptor from the IdP.

    This should be used if the IdP metadata URL cannot be accessed from the ALM server.

Back to top

Deploy SSO components

Run the following script as administrator to deploy SSO components:

  • For Windows: {ALM Installation Directory}\ALM\run_osp_deploy.bat
  • For Linux: {ALM Installation Directory}\run_osp_deploy.sh

You will be asked to restart ALM service during deployment. Stop the ALM service to continue the deployment process and restart the ALM Service after successful deployment. If you do not stop ALM Service, the process is aborted.

If you make any change to ALM SP settings, edit, add, or remove an IdP, you should run the script again.

If ALM is in a cluster environment, run the script in each node.

Back to top

Configure IdP

IdP configurations depend on your individual IdP. Generally, to configure your IdP, you should complete the following tasks:

  1. Obtain ALM SP metadata and share it with your IdP.

    1. Obtain SP metadata from the directory http(s)://{server}:{port}/osp/a/alm/auth/saml2/sp-metadata.
    2. Save the data as XML file.
    3. The SP metadata will be used in IdP configuration to build trust between SP and the IdP. For additional IdP configuration, see the documentations for the IdP.

  2. Map IdP attributes.

    Map the user attributes that are returned by the IdP in a SAML assertion to the equivalent ALM attribute.

    The attributes are case-sensitive.

    The SAML response must be signed.

    When you configure the SAML response of ALM on IdP, do not set SAML assertion encryption to "ON" because it is not supported in ALM 15.

    ALM Attribute

    IdP Friendly Name

    Description

    IdentityKey

    IdentityKey

    The ALM IdentityKey is mapped to the IdentityKey in the SAML token in order to identify the user.

    Here is a sample SAML response.

    <samlp:Response>
    	<saml:Assertion>
    ...
    ...
    ...
    		<saml:Subject>
    			<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">sa@yopmail.com
                           </saml:NameID>
    			<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    				<saml:SubjectConfirmationData 
    					InResponseTo="idhSHtlcKqu3Xn8CpOIRc658-cnAI" 
    					NotOnOrAfter="2019-04-30T09:11:36.887Z" 
    					Recipient="https://shcappsvm76.hpeswlab.net:9443/osp/a/alm/auth/saml2/
                                               spassertion_consumer"/>
    			</saml:SubjectConfirmation>
    		</saml:Subject>
    		<saml:Conditions NotBefore="2019-04-30T08:51:36.887Z" NotOnOrAfter="2019-04-30T08:52:36.887Z">
    			<saml:AudienceRestriction>
    				<saml:Audience>https://shcappsvm76.hpeswlab.net:9443/osp/a/alm/auth/saml2/metadata
                                   </saml:Audience>
    			</saml:AudienceRestriction>
    		</saml:Conditions>
    		<saml:AuthnStatement 
    			AuthnInstant="2019-04-30T08:51:38.887Z" 
    			SessionIndex="5e968b7c-c2ad-41e6-81fb-3feb38644bcf::dfb1c06f-89e1-42ca-a6b0-f3ff41bb2fbd">
    			<saml:AuthnContext>
    				<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
                                   </saml:AuthnContextClassRef>
    			</saml:AuthnContext>
    		</saml:AuthnStatement>
    		<saml:AttributeStatement>
    			<saml:Attribute 
    				Friendly="IdentityKey" Name="IdentityKey" 
    				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">**
                                  </saml:AttributeValue>
    			</saml:Attribute>
    		</saml:AttributeStatement>
    	</saml:Assertion>
    </samlp:Response>

Back to top

Map IdP user with ALM user

Use Site Administration REST APIs to map IdP user with ALM user. For details, see Site Administration REST API Reference.

The first IdP user to be mapped with an ALM user should be an Site Administrator user.

If you do not map an IdP user with an ALM user, ALM assumes the IdP user does not have a matching user in ALM. For information about how the user logs in ALM, see SSO Access to ALM

Back to top

Validate and enable SSO authentication

Before validating SSO, make sure at least one ALM user with the Site Administrator role is already mapped to an IdP user. Otherwise, no user can configure ALM as Site Administrator.

Note: Before the validation, you should also add the ALM and IdP URLs into the IE trusted URLs.

  1. In the SSO Configuration Tool, click the IdP, and click Validate to start validation.
  2. Your IdP login page opens. Enter your IdP username and password.
  3. The login page closes if you pass the SSO authentication. And a pass indicator is displayed beside the IdP name.

    If you fail the SSO authentication, a failure indicator is displayed.

  4. After you pass the SSO authentication, click Enable SSO.

    Once SSO authentication is enabled, it cannot be disabled.

Back to top

SSO Access to ALM

Once SSO is enabled, SSO authentication is required when accessing almost all ALM resources.

The following flow illustrates how ALM handles SSO login.

Special case

If you have multiple IdPs configured and auto-provisioning is enabled in a specific IdP, a user, who does not have a matching user in ALM and wants to access ALM, should directly access the IdP through the following URL: http(s)://{server}:{port}/qcbin?idpId={idp id}

Back to top