Step 6: Validate IdP

This step is to validate an IdP. ALM provides you with different methods to verify the IdP configuration and the communication between ALM as SP and the IdP. The "alm" IdP should be the first to validate before you enable SSO.

Prerequisites

Complete the following before you validate the IdP.

  • At least one ALM user with the Site Administrator role is already mapped to an IdP user or set as a local user. Otherwise, no user can configure ALM as Site Administrator.

  • Add the ALM and IdP URLs into the IE trusted URLs.

Back to top

Validate IdP in SSO Configuration Tool

You use this method for non-SaaS environments only. For SaaS environments, you can only use this method: Send validation URL to IdP users for validation.

To validate an IdP in SSO Configuration Tool:

  1. In the SSO Configuration Tool, click the IdP name, and click Validate at the bottom to start validation.
  2. In your IdP login page, enter your IdP username and password.

  3. If yo pass the validation, the login page closes 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 validation, click Enable SSO.

    After the SSO authentication is enabled, it cannot be disabled.

Back to top

Send validation URL to IdP users for validation

In addition to validating an IdP in the SSO configuration Tool, you can also copy the validation URL and send it to IdP users to let them validate the IdP.

Note: In SaaS environment, you can only send the validation URL to IdP users for SSO validation.

To validate an IdP by sending the validation URL:

  1. Click the IdP name, and click Copy Validation URL at the bottom.
  2. In the Copy Validation URL window, click the copy link icon ().

  3. Send the link to IdP users.

    When the IdP users open the link, they will be redirected to the IdP login page. After entering the IdP username and password, they will be redirected to a page that tells whether or not the validation succeed, and if not, what the reasons are.

    If email notification is enabled, the specified site admin users will receive emails about who accessed the SSO validation URL. For details, see Step 6: Validate IdP.

Back to top

Enable SSO without validating IdP

If you enabled local authentication, you can enable SSO directly without validating the IdP.

Before you directly enable SSO, we recommend you do either of the following:

  • Set your IdP ID to "local" if you are not mapped to an IdP user yet.
  • Set your IdP ID to a real IdP name if you are already mapped to an IdP user.

Otherwise, after you enable SSO, no one is able to access ALM if SSO fails to work and if none of the other site administrator users have set their IdP IDs to "local" or real IdP names.

Back to top

FAQ

Q: When I try to validate the IdP in the SSO Configuration Tool, I get the "SP metadata is not available or the URL inside SP metadata is not correct" error or the 401 error.

A: To troubleshoot this error, do the following:

  1. In the {IdP name}.properties file, retrieve the osp.api.url parameter.

    The file is located in the {ALM repository folder}\sa\DomsInfo\osp\ dirctory.

    For example, for the default alm IdP, open the {ALM repository folder}\sa\DomsInfo\osp\alm.properties file to retrieve the osp.api.url parameter.

  2. Run the following command to ping the osp.api.url on every ALM node:

    ping {osp.api.url}

  3. Verify the ping output:

    • If the ping command fails to obtain the URL and returns an network issue, request assistance from the network team for further diagnosis.

    • If the network team fails to provide workable solutions, try the following workaround:

      1. In the {IdP name}.properties file, change the osp.api.url parameter to the local address of the ALM server. For example, osp.api.url= http\://localhost\:{http port number}/osp/a/{IdP name}

        To obtain the http port number, in the {ALM deployment folder}\server\conf\jetty.xml file, check the <Set name="port"<property name="jetty.port" default=....></set> line.

        Note: Make sure the HTTP communication is enabled in the jetty.xml file and ALM is actively listening on this port.

      2. Restart the ALM service on every ALM node.

Q: When I validated the IdP "alm" in the SSO Configuration Tool, the web browser redirected me to the IdP but reported an error as follows. Why?

A： Root cause: Wrong SP metadata URL was registered in the IdP, so the IdP cannot recognize the SAML request sent from ALM.

Solution: Make sure the correct SP metadata can be loaded from ALM. And ALM should be registered as SP in the IdP correctly before you validate the IdP. After the SP metadata is registered in the IdP, when validating the IdP, you will be redirected to the IdP login page correctly.

Q: Why did I fail to validate the IdP even when the IdP returned SAML response to ALM successfully?

A: Root cause: the SAML response assertions did not contain the required assertion of "IdentityKey".

Solution: If the IdP returned SAML response, it means the trust between the IdP and ALM has been established successfully. The only problem is that the IdP user cannot be validated by ALM. ALM users and IdP user are mapped using the IdentiyKey values. If the IdP does not provide the IdentityKey value the SAML response, ALM cannot map the IdP user to any ALM user, and thus validation fails.

To solve the issue, in IdP, map IdentityKey as the SAML attribute with an IdP attribute that can uniquely identify the IdP user.

Q: How can I know the trust between IdP and ALM is established successfully?

A: In the web browser, type the ALM SP URL like this: {ALM host:port}/osp/a/alm/auth/app/. If it redirects you to the IdP login page, and if after authentication it redirects you back to the SP page without error, it means SP has received SAML response from the IdP: the trust between IdP and ALM is established successfully.

Back to top

Next steps: