Step 1: Configure ALM as SP

Prerequisite: Step 0: Preparation.

This step is to configure ALM as SP in the SSO Configuration Tool. 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. In Site Administration, click Tools > SSO configuration.

  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 to ALM locally when ALM runs in the SSO mode.

    • No. When ALM runs in the SSO mode, ALM does not support local authentication. Only users with real IdP IDs can access ALM.

    • Yes. When ALM runs in the SSO mode, ALM also supports local authentication. Both users with real IdP IDs and local users can access ALM.

    For details about configuring user's IdP ID and Identity Key, see Update user details.

    The General Settings > My Profile tab provides a shortcut to configure your IdP ID and Identity Key. See Set your 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 is the port number of the ALM Server.
    • If the reverse proxy is used, it is 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 a reverse proxy. If yes, you should also specify the 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.

Back to top

Upload SAML certificate

The SAML certificate is used to encrypt and decrypt the SAML requests and responses between ALM and IdPs. You can provide the certificate either by uploading the keystore file or by entering the certificate information manually. After uploading the certificate, you can view its details and upload a different certificate.

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

Upload a keystore file

To provide your certificate by uploading a keystore file:

  1. Click General Settings > SSO Certificate.
  2. In the Certificate Submission Type filed, select Upload Keystore File.

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

  4. Enter the keystore and certificate passwords.
  5. Enter the alias of the certificate that is used in the keystore file.
  6. Click Submit.

Enter certificate information manually

To provide your certificate by entering the certificate information manually:

  1. Click General Settings > SSO Certificate.
  2. In the Certificate Submission Type filed, select Manually Enter.
  3. Enter the keystore and certificate passwords, certificate chain, and private key.
  4. Click Submit.

Upload a different 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.

Back to top

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

The available options include:

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

As a 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.
Identity Key

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

Back to top

FAQ

Q: How to create a SAML certificate for ALM?

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.

Q: How to get SSO logs?

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.

Back to top

Next steps: