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 and Access Management (IAM) 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 IAM solution provider.

With SAML support, you can connect to any compatible SAML IdP (Identity Provider). The following are some IAM 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 while configuring SAML, check with the administrator whether the the SAML is enabled for the Cloud Pak at the Identity Provider.

Prerequisites

You must configure a fully qualified domain name (FQDN) for accessing your cluster.

Configuring SSO

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

To verify if you have Idp registration or not, see Get IdP registration by query.

To configure SSO, complete the following sequence of steps:

  1. Enable SAML.
  2. Export the metadata of your product to your enterprise SAML server. After you complete this task, a metadata file is downloaded.
  3. Import the metadata sent by your enterprise SAML server.
  4. Verify whether SAML was successfully configured.

  5. Optional: Connect with an LDAP server and import users who might use the SSO request. For more information, see Configuring LDAP connection.

    Note:

    • You can also connect your product with the same LDAP server that your enterprise SAML server uses for authentication.
    • If you are connecting LDAP using SAML, see SAML with LDAP dependency registration. As per 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.

  6. 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 using the IdP APIs. If you are manually registering the SAML with SCIM enabled IdP, see SAML with SCIM dependency registration. As per 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.

  7. If you are using SAML without LDAP dependency or SCIM enabled Idp, you can register the Idp by using SAML registration without any dependency. As per 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.

You can use the application programming interface (API) or the command line interface (CLI) for configuring SSO in your product.

Configuring SSO by using the APIs

For configuring SSO by using the APIs, see Single sign-on APIs.

Configuring SSO by using the CLI

Prerequisites

Install the IBM Cloud Pak CLI (cloudctl) tool.

Following commands are available to configure and manage SSO in your cluster:

Enable SAML

Enable SSO.

cloudctl iam saml-enable
Export metadata file

When you run the command, a metadata file is downloaded from your product and saved with the file name that you specify. You upload this file to your enterprise SAML server.

cloudctl iam saml-export-metadata --file <file_name>.xml

A sample metadata file resembles the following code:

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" \
entityID="https://travistest.rtp.raleigh.ibm.com:8443/ibm/saml20/defaultSP"><md:SPSSODescriptor AuthnRequestsSigned="true" \
WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> \
<md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data> \
<ds:X509Certificate>MIID9zCCAd8CCQDIJbZgmPut9DANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzERMA8GA1UE
.
.
btEmEMpzbGQy8Lb190tLeLZNW2zrBWbRmxzShn9ekS58aEbeD6PBTzWsKXsgYhZWWXw=</ds:X509Certificate> \
</ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:KeyDescriptor use="encryption"> \
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data> \
<ds:X509Certificate>MIID9zCCAd8CCQDIJbZgmPut9DANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzERMA8GA1UE
.
.
btEmEMpzbGQy8Lb190tLeLZNW2zrBWbRmxzShn9ekS58aEbeD6PBTzWsKXsgYhZWWXw=</ds:X509Certificate></ds:X509Data> \
</ds:KeyInfo></md:KeyDescriptor><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" \
Location="https://travistest.rtp.raleigh.ibm.com:8443/ibm/saml20/defaultSP/slo"/><md:AssertionConsumerService \
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" \
Location="https://travistest.rtp.raleigh.ibm.com:8443/ibm/saml20/defaultSP/acs" index="0" isDefault="true"/>\
</md:SPSSODescriptor></md:EntityDescriptor>
Import metadata file

When you run the command, you upload the metadata file that you received from your enterprise SAML server to your product.

cloudctl iam saml-upload-metadata --file <file_name>.xml

A sample metadata file resembles the following code:

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIDhTCCAm2gAwIBAgIEOxmOOjANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJVUz\
.
.
3YZ25IwGyzN5KK7XR1avMCk9GG0BbpjpqU29Wx3tWpqsh+Kl016Kc=</X509Certificate>
</X509Data>
</KeyInfo>
</md:KeyDescriptor>
<md:KeyDescriptor use="encryption">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>MIIDhTCCAm2gAwIBAgIEOxmOOjANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJVUzELMAkGA\
.
.
GyzN5KK7XR1avMCk9GG0BbpjpqU29Wx3tWpqsh+Kl016Kc=</X509Certificate>
</X509Data>
</KeyInfo>
<md:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
</md:KeyDescriptor>
<md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/soap" index="0" isDefault="true"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/slo"/>
<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/slo"/>
<md:ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/mnids"/>
<md:ManageNameIDService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/mnids"/>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/login"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://w3id.alpha.sso.ibm.com/auth/sps/samlidp2/saml20/login"/>
</md:IDPSSODescriptor>
<md:Organization>
<md:OrganizationName xml:lang="en">IBM</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="en">IBM</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="en"/>
</md:Organization>
<md:ContactPerson contactType="technical">
<md:Company>IBM</md:Company>
<md:GivenName/>
<md:SurName/>
<md:EmailAddress/>
<md:TelephoneNumber/>
</md:ContactPerson>
</md:EntityDescriptor>
Verify SSO configuration status

Verify whether SSO is correctly configured. The command returns true only when SAML is enabled and the metadata file that you received from your enterprise SAML server is uploaded to your product.

cloudctl iam saml-status
Disable SAML

Disable SSO.

cloudctl iam saml-disable