Setting up SSO Authentication (for ALM 15.00)

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

For details about how to set up SSO authentication in ALM 15.0.1, see Setting up SSO Authentication.

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.

How ALM supports SSO

ALM supports SSO via SAML 2.0 and acts as a service provider (SP) for SSO. You must implement a federation service to act as an identity provider (IdP) with federation protocol of SAML 2.0.

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 Identity Key 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 auto user-provisioning is enabled, ALM will run the auto user-provisioning process to create a matching user in ALM. For details, see Auto user-provisioning configurations.

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 (* Required) 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.

    *Enable Secure Communication

    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
    Enable Secure Reverse Proxy Whether or not the reverse proxy uses HTTPS protocol (TLS)
  4. Click Save to save the settings.
  5. Click General Settings > SAML2 Certificate to provide the certificate.

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

    To provide 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.

      Make sure the certificate in the keystore file contains both the private key and the public key.

      The keystore types that ALM supports are: JKS, JCEKS, and PKCS12. This requires that the keystore file you are about to upload should use one of the following extension names:

      • For the JKS keystore type: .jks or .ks
      • For the JCEKS keystore type: .jce
      • For the PKCS12 keystore type: .p12 or .pfx

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

    How to update the certificate?

    1. Delete the current certificate from the directory {ALM Deploy Directory}\ALM\repository\sa\DomsInfo\osp\basic.pfx.

      You can also

    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". You can add other IdPs after you successfully validate the alm IdP and enable SSO.

Note: When you add IdPs, the IdP ID should not be named "local".

To add and configure the alm IdP:

  1. In the left pane of the SSO Configuration Tool page, click the alm tab.
  2. Provide the following information.

    Field (*Required) Description

    Auto user-provisioning configurations

    SAML Field Mapped with Default ALM Username

    If ALM fails to find the only one matching ALM user for an IdP user based on the Identity key and IdP ID, this option controls the following:

    • whether or not to enable auto user-provisioning to create a matching user in ALM for the IdP user.
    • if auto user-provisioning is enable to create a user, then which attribute ALM will use as the default username when creating the user.

    OFF: Disable auto user-provisioning to create users.

    IdentityKey: When creating new users, ALM will use the IdentityKey value as the new ALM username.

    ALMUsername: When creating new users, ALM will use the ALMUsername value as the new ALM username.

    ALMEmail: When creating new users, ALM will use the ALMEmail value as the new ALM username.

    Default ALM Username Editable

    Whether or not the new ALM user can change its default username during user creation.

    Its value is disregarded if the option Attribute Mapped to ALM Username is set to OFF.

    Share IdP metadata with ALM SP

    IdP Metadata

    Base64-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

    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.

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

Configuration details vary from different IdPs. Generally, to configure your IdP, you should complete the following tasks:

  1. Create a client that uses SAML2 as the client protocol.
  2. Obtain ALM SP metadata and share it with the 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 configurations, see the documentations for the IdP.

  3. Create mappers to map the user attributes that are returned by the IdP in SAML assertions to the equivalent ALM attributes.

    Make sure you map the IdP attribute that can uniquely identify IdP users to the ALM attribute IdentityKey.

    ALM requires that NameID format should be emailAddress.

    If you map an ALM attribute to a different IdP attribute than what you map it to in the SSO configuration tool (as in Setting up SSO Authentication (for ALM 15.00)), the mapping in the SSO configuration tool prevails. For example, if the ALM attribute ALMDescription is mapped to Field A in the SSO configuration tool, ALM will use the value of Field A in the SAML assertions to update the ALM attribute ALMDescription.

    The attributes are case-sensitive. The SAML response must be signed.

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 users with ALM users

IdP users are mapped to ALM users by two attributes: Identity Provider Name and Identity Key.

ALM attribute Mapped to IdP attribute
Identity Provider Name The IdP name that is configured in the ALM SSO Configuration Tool, such as the default IdP name "alm".
Identity Key The IdP attribute that an IdP user can be uniquely identified. For example, username, user ID, and user email.

You can map IdP users with ALM users individually or in batches. The first IdP user to be mapped with an ALM user should be an Site Administrator user.

Method Details
Map users individually

You can use this method only after SSO is enabled.

To map an IdP user with an ALM user,

  1. Open the user details of the ALM user from Site Administration > Site Users tab.
  2. Update the attributes: Identity Provider Name and Identity Key with the corresponding user information of the IdP user.

For details, see Updating User Details.

Map users in batches by using Site Administration REST API

You can use this method regardless of whether SSO is enabled.

Set the attributes: idp-name and identity-key for the site users.

For details, see Site Administration REST API Reference: Site Users > Update a site user.

Note: 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 for an IdP, 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 name, and click Validate in the bottom to start validation.
  2. Your IdP login page opens. Enter your IdP username and password.
  3. The login page closes if you pass the validation. And a pass indicator is displayed in the front of the IdP name.

    If you fail the validation, a failure indicator is displayed.

  4. After you pass the SSO validation, 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