Configuring single sign-on

Important: IBM Cloud Pak® for Data Version 4.8 will reach end of support (EOS) on 31 July, 2025. For more information, see the Discontinuance of service announcement for IBM Cloud Pak for Data Version 4.X.

Upgrade to IBM Software Hub Version 5.1 before IBM Cloud Pak for Data Version 4.8 reaches end of support. For more information, see Upgrading from IBM Cloud Pak for Data Version 4.8 to IBM Software Hub Version 5.1.

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

Important: This method for configuring SSO is applicable only if Cloud Pak for Data is not configured to use the Identity Management Service (Identity Management Service).

If Cloud Pak for Data is configured to use the Identity Management Service, see the following topics in the IBM Cloud Pak foundational services documentation:

Configuring single sign-on using SAML
Configuring single sign-on using OpenID Connect

For information about which version of IBM Cloud Pak foundational services is installed on your cluster, see Operator and operand versions.

Who needs to complete this task?

To complete this task, you must have one of the following roles:

Cluster administrator
Instance administrator

When do you need to complete this task?

Complete this task if you want to use SAML for SSO to the web client.

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

Before you begin

Best practice: You can run many of the commands in this task exactly as written if you set up environment variables for your installation. For instructions, see Setting up installation environment variables.

Ensure that you source the environment variables before you run the commands in this task.

You must have an existing SAML SSO identity provider (IdP).

Work with your IdP administrator to review this task and gather the information required to connect to your IdP.

Procedure

Log in to Red Hat® OpenShift® Container Platform as a user with sufficient permissions to complete the task.
```
${OC_LOGIN}
```

Create a file named saml-configmap.yaml with the following format:

apiVersion: v1
kind: ConfigMap
metadata:
  name: saml-configmap
data:
  samlConfig.json: |
    {
        "entryPoint": "<URL-of-the-login-page-for-IdP>",
        "fieldToAuthenticate": "<parameter-used-to-authenticate>",
        "spCert": "<private-key-for-signing-requests-to-the-IdP>",
        "signatureAlgorithm": "<signature-algorithm>",
        "idpCert": "<certificate-used-to-verify-responses-from-IdP>",
        "issuer": "<name-to-use-to-register-the-platform-with-the-IdP>",
        "identifierFormat": "<format-of-requests-sent-to-IdP>",
        "callbackUrl": "<URL-to-redirect-to-after-successful-sign-in>",
        "disableRequestedAuthnContext": false
    }

Edit the values of the following parameters.

The samlConfig.json section includes all required and optional parameters. If you don't plan to use an optional parameter in the samlConfig.json, remove the parameter.

Parameter	Description
entryPoint	The URL of the login page for your IdP. Status Required. Syntax `"entryPoint": "<URL-of-the-login-page-for-IdP>"` Default value No default. Valid values A URL in standard JSON string format.
fieldToAuthenticate	The name of the parameter you use to authenticate with the IdP, such as: `emailAddress` `username` Status Required. Syntax `"fieldToAuthenticate": "<parameter-used-to-authenticate>"` Default value No default. Valid values A parameter name in standard JSON string format. If you plan to use LDAP and SAML SSO, ensure that you use the same attribute to identify users. This parameter must have the same value as the User search field in your LDAP configuration.
spCert	The private key used to sign SAML requests that are sent to the IdP. Important: The certificate that corresponds to this key must be set in your IdP when you register Cloud Pak for Data with the IdP so that the SAML requests can be verified by your IdP. Status Required only if your SAML server requires requests to be signed with a private key. Syntax `"spCert": "<private-key-for-signing-requests-to-the-IdP>"` Default value No default. Valid values The key must use the Public-Key Cryptography Standards (PKCS) #8 format. Remove the `"BEGIN PRIVATE KEY"` and `"END PRIVATE KEY"` lines from the key and provide the private key as a single line in standard JSON string format.
signatureAlgorithm	The signature algorithm that is used to sign requests. Status Required only if you specify the `spCert` parameter. Syntax `"signatureAlgorithm": "<signature-algorithm>"` Default value `sha1` If you do not specify this parameter, the default value is used. Valid values `sha1` `sha256` `sha512`
idpCert	The certificate provided by the IdP to verify SAML responses from the IdP. Status Required. Syntax `"idpCert": "<certificate-used-to-verify-responses-from-IdP>"` Default value No default. Valid values Remove the `"BEGIN CERTIFICATE"` and `"END CERTIFICATE"` lines from the certificate and provide the certificate as a single line in standard JSON string format.
issuer	The unique identifier that you used to register this instance of Cloud Pak for Data with your IdP. Status Required. Syntax `"issuer": "<name-to-use-to-register-the-platform-with-the-IdP>"` Default value No default. Valid values The unique identifier that is registered with your IdP in standard JSON string format.
identifierFormat	The format of requests from Cloud Pak for Data to the IdP. The format must be supported by the IdP. Status Optional. Syntax `"identifierFormat": "<format-of-requests-sent-to-IdP>"` Default value `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` If you do not specify this parameter, the default value is used. Valid values A format that is supported by the IdP. Specify the format as a standard JSON string.
callbackUrl	The URL to redirect users to after they successfully authenticate using SSO. Important: The URL must be registered in the SAML IdP. Status Required. Syntax `"callbackUrl": "<URL-to-redirect-to-after-successful-sign-in>"` Default value No default. Valid values A URL in standard JSON string format. Use the format `https://<cpd-route>/auth/login/sso/callback`. Replace `<cpd-route>` with the route to the Cloud Pak for Data web client. Tip: If you don't know the route to the web client, run: `oc get route cpd \ -n=${PROJECT_CPD_INST_OPERANDS} \ -o jsonpath='{.spec.host}'; echo`
disableRequestedAuthnContext	Specify whether to include the `authnContext` in the SAML request. Restriction: This parameter applies only to Active Directory Federation Services. Status Optional. This parameter applies only to Active Directory Federation Services. Syntax `"disableRequestedAuthnContext": true\|false` Default value `false` If you do not specify this parameter, the default value is used. Valid values `false` The `authnContext` is included in the SAML request, so the IdP uses the `['urn:oasis:names:tc:SAML:2.0:ac:classes:Password']` method for authentication. `true` The `authnContext` is not included in the SAML request, and the IdP determines the method for authentication.

Apply the contents of the saml-configmap.yaml file:

oc apply -f saml-configmap.yaml \
--namespace=${PROJECT_CPD_INST_OPERANDS}

Run the following command to restart the usermgmt pods:
```
oc delete pods -l component=usermgmt \
--namespace=${PROJECT_CPD_INST_OPERANDS}
```
Wait for the usermgmt pods to be Running.

What to do next

Wait for the usermgmt pods to restart before you attempt to log in to the web client. 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 an administrator with the Manage users permission.
Add users with their SAML IDs. For details, see Managing users.

Disabling SAML

Procedure

To disable SAML:

Delete the saml-configmap ConfigMap:

oc delete configmap saml-configmap \
--namespace=${PROJECT_CPD_INST_OPERANDS}

Run the following command to restart the usermgmt pods:

oc delete pods -l component=usermgmt \
 -namespace=${PROJECT_CPD_INST_OPERANDS}