Enabling Cloud Pak for Data to authenticate users against a custom authentication service

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.

If you have a custom authentication service, you can configure Cloud Pak for Data to authenticate users against the custom authentication service. When you integrate Cloud Pak for Data with the custom authentication service, Cloud Pak for Data can authenticate users who provide a token that is associated with the custom authentication service.

Who needs to complete this task?

To complete this task, you must be either:

A cluster administrator
An instance administrator

When do you need to complete this task?

Complete this task if you want to enable Cloud Pak for Data to authenticate users with a custom authentication service.

Before you begin

Save the CA or self-signed certificate for the custom authentication server to the workstation from which you will complete this task.

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.

About this task

When you integrate Cloud Pak for Data with a custom authentication service, the service does not replace the default method that Cloud Pak for Data uses to authenticate users. Instead, the authentication service is an alternative method to authenticate users who provide a token that is associated with the custom authentication service.

A custom authentication server is an API server. You can write the API server in your preferred language and deploy it in any environment. The API server must conform to the following requirements:

The cluster where Cloud Pak for Data is installed must be able to contact the server where the custom authentication service is running.
The endpoint that you use to authenticate users must meet the following criteria:
- A successful call must return an HTTP 200 code and a JSON response.
- The JSON response for a successful call must return a property that defines the user's username.
  The expected property name is username. If your authentication service returns a different field, you can override the default behavior by adding the customUsernameKey field to the custom-auth-handler-secret secret.

Procedure

Log in to Red Hat® OpenShift® Container Platform as a user with sufficient permissions to complete the task.
```
${OC_LOGIN}
```
Remember: OC_LOGIN is an alias for the oc login command.
Set the following environment variables:
1. Set the CUSTOM_AUTH_HANDLER environment variable to the URL of the authorization endpoint:
```
export CUSTOM_AUTH_HANDLER=<url-of-the-endpoint>
```
2. Set the CUSTOM_AUTH_HEADER environment variable to the header that identifies requests that should be handled by the custom authentication service:
```
export CUSTOM_AUTH_HEADER=<my-custom-auth-header>
```
  Restriction: Do not use Authorization as the header.
3. Set the CUSTOM_AUTH_CERT environment variable to the fully qualified file name of the custom authentication server certificate on your workstation.
```
export CUSTOM_AUTH_CERT=<fully-qualified-file-name-of-the-certificate-file>
```
4. Set the CUSTOM_TOKEN_HEADER environment variable to the header that Cloud Pak for Data should use to pass the token to the custom authentication service.
```
export CUSTOM_TOKEN_HEADER=<header>
```
5. If you set CUSTOM_AUTH_TYPE to Authorization, set the CUSTOM_AUTH_TYPE environment variable to the authentication scheme, such as Bearer or Basic.
```
export CUSTOM_AUTH_TYPE=<authentication-scheme>
```
6. If your authentication service returns a property other than username, set the CUSTOM_AUTH_PROPERTY environment variable to the name of the property returned by your authentication service:
```
export CUSTOM_AUTH_PROPERTY=<property-name>
```

Create a secret named custom-auth-handler-secret that Cloud Pak for Data can use to communicate with the custom authentication service.

Run the appropriate command based on:

The name of the property returned by your authentication service
Whether you set the CUSTOM_AUTH_TYPE environment variable

The authentication service returns a property called username

You set the CUSTOM_AUTH_TYPE environment variable

oc create secret generic custom-auth-handler-secret -n ${PROJECT_CPD_INST_OPERANDS} \
 --from-literal=handler=${CUSTOM_AUTH_HANDLER} \
 --from-literal=header=${CUSTOM_AUTH_HEADER} \
 --from-literal=customTokenHeader=${CUSTOM_TOKEN_HEADER} \
 --from-literal=customTokenAuthType=${CUSTOM_AUTH_TYPE} \
 --from-file=certificate=${CUSTOM_AUTH_CERT}

You did not set the CUSTOM_AUTH_TYPE environment variable

oc create secret generic custom-auth-handler-secret -n ${PROJECT_CPD_INST_OPERANDS} \
 --from-literal=handler=${CUSTOM_AUTH_HANDLER} \
 --from-literal=header=${CUSTOM_AUTH_HEADER} \
 --from-literal=customTokenHeader=${CUSTOM_TOKEN_HEADER} \
 --from-file=certificate=${CUSTOM_AUTH_CERT}

The authentication service returns a different property

You set the CUSTOM_AUTH_TYPE environment variable

oc create secret generic custom-auth-handler-secret -n ${PROJECT_CPD_INST_OPERANDS} \
 --from-literal=handler=${CUSTOM_AUTH_HANDLER} \
 --from-literal=header=${CUSTOM_AUTH_HEADER} \
 --from-literal=customTokenHeader=${CUSTOM_TOKEN_HEADER} \
 --from-literal=customTokenAuthType=${CUSTOM_AUTH_TYPE} \
 --from-file=certificate=${CUSTOM_AUTH_CERT} \
--from-literal=customUsernameKey=${CUSTOM_AUTH_PROPERTY}

You did not set the CUSTOM_AUTH_TYPE environment variable

oc create secret generic custom-auth-handler-secret -n ${PROJECT_CPD_INST_OPERANDS} \
 --from-literal=handler=${CUSTOM_AUTH_HANDLER} \
 --from-literal=header=${CUSTOM_AUTH_HEADER} \
 --from-literal=customTokenHeader=${CUSTOM_TOKEN_HEADER} \
 --from-file=certificate=${CUSTOM_AUTH_CERT} \
--from-literal=customUsernameKey=${CUSTOM_AUTH_PROPERTY}

Ensure that the secret was successfully created:
```
oc get secrets -n ${PROJECT_CPD_INST_OPERANDS} | grep custom-auth
```
If the secret exists, the command will return information about the secret.

Restart the ibm-nginx pods for the changes to take effect:

oc delete pod \
-n=${PROJECT_CPD_INST_OPERANDS} \
-l component=ibm-nginx

Results

If a user exists in both Cloud Pak for Data and the custom authentication service, the user can authenticate to the custom authentication service with the following API call:

GET 'https://${CPD_ROUTE}/api/v1/usermgmt/v1/usermgmt/user/${USER_ID}' \
-H '${CUSTOM_AUTH_HEADER}: ${USER_AUTH_KEY}'

The command will return the user's username from the custom authentication service.

Note: In the preceding API call, the user's authorization key (USER_AUTH_KEY) is known only to the custom authentication service.