Configuring single sign-on

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

Important: This method for configuring SSO is applicable only if IBM Software Hub is not configured to use the Identity Management Service (Identity Management Service).

If IBM Software Hub 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
- Version 4.13
- Version 4.14
Configuring single sign-on using OpenID Connect
- Version 4.13
- Version 4.14

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 IBM Software Hub. If you add users to IBM Software Hub 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 samlConfig.json with the following format:

{
     "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 parameters.

The samlConfig.json file 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 IBM Software Hub 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 IBM Software Hub 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 IBM Software Hub 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 IBM Software Hub 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.

Create a secret named saml-secret:

oc create secret generic saml-secret \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
--from-file=samlConfig.json=samlConfig.json

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 IBM Software Hub, 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 IBM Software Hub 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:

Optional: Back up the saml-secret as samlConfig-backup.json

oc get secret saml-secret \
--namespace=${PROJECT_CPD_INST_OPERANDS} \
-o jsonpath='{.data.samlConfig\.json}' | base64 -d > samlConfig-backup.json

Delete the saml-secret secret:

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

Restart the usermgmt pods:

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