Configuring single sign-on

Configure single sign-on (SSO) between IBM® Cloud Private 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 IBM Cloud Private 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 IBM Cloud Private through a web browser.
  2. IBM Cloud Private verifies whether an authentication token is present.
  3. If no authentication token is present, IBM Cloud Private redirects the request for authentication to the user's enterprise SAML server.
  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 IBM Cloud Private.
  6. IBM Cloud Private generates an authentication token and grants access to the service that the user requested.

Configuring SSO in IBM Cloud Private

Metadata files are used for communication between your IBM Cloud Private cluster and your enterprise SAML server.

Prerequisites

Configuring SSO

To configure SSO, complete the following sequence of steps:

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

You can use application programming interface (API) or the command line interface (CLI) for configuring SSO in IBM Cloud Private.

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 Private CLI. For more information, see Installing the IBM Cloud Private CLI.

Following commands are available to configure and manage SSO in your IBM Cloud Private cluster.

Enable SAML

Enable SSO.

cloudctl iam saml-enable
Export metadata file

When you run the command, a metadata file is downloaded from IBM Cloud Private 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 IBM Cloud Private.

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 IBM Cloud Private.

cloudctl iam saml-status
Disable SAML

Disable SSO.

cloudctl iam saml-disable