Configuring single sign-on

You can use Security Assertion Markup Language (SAML) for single sign-on (SSO) to the IBM® Cloud Pak for Data web client.

Before you begin

You must have an existing SAML identity provider (IdP). Work with your IdP administrator to gather the following information:

Parameter	Description	Value
entryPoint	The URL of the login page for your identity provider.
fieldToAuthenticate	The name of the parameter you use to authenticate with the identity provider, such as `emailAddress` or `username`. If you plan to use LDAP and SAML, ensure that you use the same attribute to identify users. This parameter should have the same value as the User search field in your LDAP configuration.
spCert	The private key used to sign SAML requests to the identity provider. The certificate corresponding to this key needs to be set when you register Cloud Pak for Data with your identity provider so that the SAML requests can be verified by your identity provider. If you do not specify a certificate, the requests won't be signed.	Remove the "BEGIN PRIVATE KEY" and "END PRIVATE KEY" lines and provide the private key as a single line.
idpCert	The certificate provided by the identity provider to verify SAML responses from the identity provider.	Remove the "BEGIN CERTIFICATE" and "END CERTIFICATE" lines and provide the certificate as a single line.
issuer	The name that you want to use to register Cloud Pak for Data with your identity provider. If you do not specify a value, the default (`ibm_privatecloud`) is used.
identifierFormat	The format of requests from Cloud Pak for Data to the identity provider. The format must be supported by the identity provider. If you do not specify a format, the default format (`urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`) is used
callbackUrl	An approved URL (that you set with the SAML identity provider) to redirect users to after they successfully authenticate using SSO. For example, to redirect successfully authenticated users to the Cloud Pak for Data landing page, you can specify `https://cluster/auth/login/sso/callback`.
disableRequestedAuthnContext	A boolean parameter for AD FS client authentication. If set the true, the authentication context is disabled so that the IDP determines the method of authentication. If you do not specify a value, then the default is false.

About this task

To configure SSO, you must specify information about your Identity Provider in a configuration file. Use the preceding table to gather the required information that you need to supply in the configuration file.

Important: It is strongly recommended that you complete this task before you add users to Cloud Pak for Data. If you have already added users to Cloud Pak for Data you must re-add the users with their SAML ID to enable them to use SSO.

Procedure

Enable SAML by running the following command:

oc exec -it -n namespace \
$(oc get pod -n namespace -l component=usermgmt | tail -1 | cut -f1 -d\ ) \
-- bash -c "vi /user-home/_global_/config/saml/samlConfig.json"

Replace namespace with the namespace where Cloud Pak for Data is deployed.

In the samlConfig.json file, specify the appropriate values for your environment.

{
  "entryPoint": "",
  "fieldToAuthenticate": "",
  "spCert": "",
  "idpCert": "",
  "issuer": "",
  "identifierFormat": "",
  "callbackUrl": ""
}

Save your changes to samlConfig.json.
1. Press Esc.
2. Press :.
3. Enter :x.
4. Press Enter.
Run the following command to delete the usermgmt pods:
```
oc delete pods -l component=usermgmt
```

What to do next

Wait several minutes before you attempt to log in to the web client. The instructions restart the usermgmt pods. If the pods are not running, you will not be able to log in.

If you previously added users to Cloud Pak for Data, you must re-add the users with their SAML ID to enable them to use SSO. To add users:

Go directly to the web client log in page by appending the following path to your Cloud Pak for Data URL: /auth/login/zen-login.html.
Log in to the web client as the admin user or another administrator with user management permissions.
Add users with their SAML IDs. For details, see Managing users.

Disabling SAML

Procedure

Disable SAML by running the following command:

oc exec -it -n namespace \
$(oc get pod -n namespace -l component=usermgmt | tail -1 | cut -f1 -d\ ) \
-- bash -c "rm /user-home/_global_/config/saml/samlConfig.json"

Replace namespace with the namespace where Cloud Pak for Data is deployed.

Run the following command to delete the usermgmt pods:
```
oc delete pods -l component=usermgmt
```