Step 1: Configure ALM as SP

Prerequisite: you already complete Step 0: Preparation.

This step is to configure ALM as SP in the SSO Configuration Tool. It involves the following tasks.

  1. Provide ALM server general information
  2. Upload SAML certificate
  3. Set your profile

Note: After completing this step, you should be able to find the SP configuration file in the ALM repository: {ALM repository}\sa\DomsInfo\osp\basic.properties.

Provide ALM server general information

  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
    *Enable Local Authentication

    This option controls whether or not the users that are configured as ALM local users can log in ALM locally when ALM runs in the SSO mode.

    • No: ALM does not support local authentication when it runs in the SSO mode.

      When ALM runs in the SSO mode, only the users with real IdP IDs can access ALM.

    • Yes: ALM also supports local authentication when it runs in the SSO mode.

      When ALM runs in the SSO mode, in addition to the users with real IdP IDs, the users whose IdP IDs are set to "local" can also access ALM.

    For details about configuring user's IdP ID and Identity Key, see Managing ALM Users.

    The SSO Configuration Tool provides you a shortcut to configure your IdP ID and Identity Key. Go to General Settings > My Profile.
    *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
    • If the reverse proxy is not used, it's the port number of the ALM Server.
    • If the reverse proxy is used, it's the port number that is used in the HTTP request header. You can find the port number in the server log. For details about how to see SSO logs, see FAQ.
    *Enable Secure Communication
    • Yes: Select Yes if the schema value in the HTTP request header starts with "https".
    • No: Select No if the schema value in the HTTP request header starts with "http".
    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 the reverse proxy
    Enable Secure Reverse Proxy
    • Yes: Select Yes if the reverse proxy enables secure communication.
    • No: Select No if the reverse proxy doesn't enable secure communication.
  4. Click Save to save the settings.

Upload SAML certificate

The SAML certificate is used to encrypt and decrypt the SAML requests and responses between ALM and IdPs.

For details about how to create an SAML certificate for ALM, see FAQ.

Click General Settings > SSO 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 manage the certificate

After uploading the certificate, you can view its details and upload a different certificate.

The SSO Certificate tab displays the alias and expiration date of the certificate. To view more details, click the View Certificate link.

To upload a different certificate:

  1. Click the Delete Certificate link in the SSO Certificate tab to delete the current certificate.

    You can also delete the current certificate from the directory {ALM Deploy Directory}\ALM\repository\sa\DomsInfo\osp\basic.pfx.

  2. Refresh the current page.
  3. Upload the new certificate.
  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 Step 2: Configure Default IdP.

Set your profile

The General Settings > My Profile tab provides you shortcut to specify your IdP name and Identity key. They are used to map an IdP user.

To set your profile, complete the following fields and click Save.

Field Description
IdP

As Site Administrator, if you are going to enable SSO, do either of the following:

  • If you are already mapped to an IdP user, set your IdP to the IdP name where the mapped IdP user belongs.
  • If you are not mapped to an IdP user yet, select "local" and enable local authentication.

Otherwise, you cannot access ALM and probably no user can access ALM after you enable SSO. For details, see Enable SSO without validating IdP.

Here are the descriptions of the available options:

  • (empty): Users that already exist in ALM before enabling SSO have empty IdP and empty Identity Key. Such users cannot access ALM after SSO is enabled. Do not set your IdP to "empty" during SSO configuration.
  • local: Users with IdP set to "local" are local ALM users. Only when local authentication is enabled, such users can locally access ALM after SSO is enabled. For local authentication settings, see *Enable Local Authentication.
  • <Real IdP IDs>: Users mapped to IdP users have real IdPs.
Identity Key

When user's IdP is configured as 'local', the Identity Key can be empty. When user's IdP is configured as real IdPs, the Identity Key should be set as the unique value to identify the user.

FAQ

A: Generally we suggest you get the SAML certificate from an authorized organization so that you can get a safer certificate. But if your organization doesn’t require very high security policies, you can create an SAML certificate by yourself.

To generate a self-signed SSL certificate using the keytool command on Windows, Mac, or Linux:

  1. Open a command prompt or terminal and run this command:

    keytool -genkey -keyalg RSA -alias <alias> -keystore selfsigned.jks -validity <days> -keysize 2048

    where <alias> indicates the name for the certificate; <days> indicates the number of days for which the certificate will be valid.

  2. Enter a password for the keystore file. Note down this password as you need it when configuring the server.

  3. When prompted for the first name and last name, enter the domain name of the server. For example, myserver or myserver.mycompany.com.

  4. Enter the other details, such as Organizational Unit, Organization, City, State, and Country.

  5. Confirm that the information entered is correct.

  6. When prompted with "Enter key" password for <tomcat>, press Enter to use the same password as the keystore file password.

  7. Run this command to verify the content of the keystore file:

    keytool -list -v -keystore selfsigned.jks

  8. When prompted, enter the keystore file password.

The certificate you generate is named as selfsigned.jks. Do not modify its extension name. Verify that the "Owner" and "Issuer" are the same. Keep the alias, key password and keystore file password in your secure place because you will need them in the SSO Configuration Tool for uploading or deleting the certificate.

A:

  1. Open the SP configuration file in the ALM repository: {ALM repository}\sa\DomsInfo\osp\basic.properties.
  2. Set "logging.level=ALL".

  3. Restart ALM and login ALM again.

  4. Check the directory of java.io.tmpdir in the server log. All the osp-* files in that directory are SSO log files.

Next steps: