Configuring single sign-on

Configure single sign-on (SSO) between your product and your enterprise identity source.

Security Assertion Markup Language (SAML), an XML-based markup language, is an open standard for exchanging identity, authentication, and authorization information between an identity provider (your enterprise SAML server) and a service provider (your product cluster).

The identity provider issues authentication assertions along with a SAML SSO profile. The service provider receives these assertions and the profile.

The SSO flow can be summarized as follows:

  1. A user attempts to access a service in your product through a web browser.
  2. Your product verifies whether an authentication token is present.
  3. If no authentication token is present, your product redirects the request for authentication to the enterprise SAML server of the user.
  4. The enterprise SAML server presents a login page to the user.
  5. If the user logs in successfully, the SAML server redirects the user, along with the SAML response, to your product.
  6. Your product generates an authentication token and grants access to the service that the user requested.

SSO can be configured with any Identity Management (IM) solution. You must first complete the SSO configuration in your cluster as instructed in Configuring SSO in your product. Then, complete the SSO configuration by following the instructions that are provided by your IM solution provider.

With SAML support, you can connect to any compatible SAML IdP (Identity Provider). The following are some IM solution providers for configuring SSO by using SAML:

Configuring SSO in your product

Metadata files are used for communication between your product and your enterprise SAML server.

Note: If you see the error 404 during SAML configuration, check with the administrator whether SAML is enabled for the Cloud Pak at the Identity Provider.

Before you configure SSO, you must configure a fully qualified domain name (FQDN) for accessing your cluster.

Note: If you are configuring SSO by using SAML, you must manually register the IdP by using Identity provider APIs in the following scenarios:

To verify whether you have an IdP registration, see Get IdP registration by query.

To configure SSO, complete the following sequence of steps:

  1. Configure SAML and import metadata that is sent by your enterprise SAML server by using IdP V3 APIs.
  2. Export the metadata of your product to your enterprise SAML server. After you complete this task, a metadata file is downloaded. For more information, see SAML metadata export by using samlmetadata API.
  3. Verify whether SAML was successfully configured.
  4. Optional: Connect with an LDAP server and import users who might use the SSO request. For more information, see Configuring LDAP connection.
    See the following notes:
     - You can also connect your product with the same LDAP server that your enterprise SAML server uses for authentication.
     - If you are connecting LDAP by using SAML, see [SAML with LDAP dependency registration](apis/idp_api.html#saml2-ldap). Based on your requirement, you can update the values of the schema elements, `name`, `description`, `scim_base_path`, `token_attribute_mappings`, and `saml_ldap`. To understand the use of schema elements, see [Different schema elements](apis/idp_api.html#schema-elements).  
  5. Optional: You can directly connect with the SAML IdP if it is SCIM-enabled. SCIM is supported to connect with the registered IdP and import the users by using the IdP APIs. If you are manually registering SAML with SCIM-enabled IdP, see SAML with SCIM dependency registration. Based on your requirement, you can update the values of the schema elements, name, description, idp_type, scim_base_path,token_attribute_mappings, scim_attribute_mappings, and config. To understand the use of schema elements, see Different schema elements.
  6. If you are using SAML without LDAP dependency or SCIM-enabled IdP, you can register the IdP by using SAML registration without any dependency. Based on your requirement, you can update the values of schema elements, name, description, and token_attribute_mappings. To understand the use of schema elements, see Different schema elements.