Integrating with the IBM Cloud Pak foundational services Identity and Access Management Service

To use the IBM Cloud Pak® foundational services Identity and Access Management Service (IAM Service) for access management and single sign-on (SSO), you must register Cloud Pak for Data with the IAM Service and configure Cloud Pak for Data to use the IAM Service.

Before you begin

You must install the IAM Service. For details, see Installing the IBM Cloud Pak foundational services.

Registering Cloud Pak for Data with the IAM Service

By default, Cloud Pak for Data is configured to use its own user management service. If you installed the IAM Service on your cluster and you want to use the IAM Service for authentication, you must register Cloud Pak for Data with the IAM Service.

Cloud Pak for Data uses a custom resource definition (CRD) for OpenID Connect (OIDC) registration as described in Automated client registration method 3 in the IAM Service documentation.

Procedure

To register Cloud Pak for Data with the IAM Service:

Create a custom resource definition YAML file for Cloud Pak for Data. Name the file cpd-oidc-client.yaml:

apiVersion: oidc.security.ibm.com/v1
kind: Client
metadata:
  name: cpd-client
  namespace: common-services-project
spec:
  secret: cpd-oidcclient-secret
  oidcLibertyClient:
    post_logout_redirect_uris:
    - https://Cloud-Pak-for-Data-route/auth/doLogout
    redirect_uris:
    - https://Cloud-Pak-for-Data-route/auth/login/oidc/callback    
    trusted_uri_prefixes:
    - https://Cloud-Pak-for-Data-route

Replace the following values:

Variable	Replace with
`common-services-project`	The Red Hat OpenShift project where the common services are deployed.
`Cloud-Pak-for-Data-route`	The route to your Cloud Pak for Data deployment.

Create the custom resource definition file:
```
oc create -f cpd-oidc-client.yaml
```
Confirm that Cloud Pak for Data was successfully registered with the IAM Service:
```
oc get Client cpd-client -n common-services-project
```
Replace the common-services-project variable with the same value you specified in the YAML file.

After you register Cloud Pak for Data with the IAM Service, you must configure Cloud Pak for Data to use the IAM Service instead of the default user management service.

Configuring Cloud Pak for Data to use the IAM Service

After you register Cloud Pak for Data with the IAM Service, you must create a file called Cloud Pak for Data oidcConfig.json and disable the Cloud Pak for Data user management service.

Before you begin

Gather the following information so that you can easily create the oidcConfig.json file:

Parameter	Description and value
authorizationUrl	The URL of the IAM authorization service. The URL has the format: `https://common-services-route/idprovider/v1/auth/authorize` To get the route to the common services, run the following command: `oc -n common-services-project get route cp-console -o yaml` Replace `common-services-project` with the Red Hat OpenShift project where the common services are deployed. The route is in the `spec.host` section of the output. My value:
tokenUrl	The URL of the IAM token service. The URL has the format: `https://common-services-route/idprovider/v1/auth/token` Replace the `common-services-route` variable with the value that you used for the previous parameter. My value:
fieldToAuthenticate	The name of the field used to identify users. The default value is `id`
clientID	The ID that is generated when you register your client. To get the ID, run the following command: `oc extract secret/cpd-oidcclient-secret -n common-services-project --to=-` If you specified a different name for secret, replace `cpd-oidcclient-secret` with the value that you used. Look for the `CLIENT_ID` in the output. My value:
clientSecret	The secret that is associated the client ID. The secret is returned when you run the `oc get secret` command in the preceding row. Look for the `CLIENT_SECRET` in the output. My value:
issuer	The OIDC authentication URL. The default value is `https://127.0.0.1:443/idauth/oidc/endpoint/OP`. However, the URL might be customized. For details, see the section Customizing the authentication URL in Authentication onboarding and single sign-on. My value:
callbackUrl	The route back to the Cloud Pak for Data auth handler. Users are redirected to this URL after they are authenticated by the IAM Service. The URL has the format: `https://Cloud-Pak-for-Data-route/auth/login/oidc/callback` Replace the `Cloud-Pak-for-Data-route` variable with the route to your Cloud Pak for Data deployment. My value:
addCACert	A boolean parameter that indicates whether the IAM Service is configured to use authentication certificates. The value depends on your configuration: The default value is `false`. If you configured the IAM Service to use authentication certificates, the value is `true`.
CACertPathList	The locations to import the certificates to. This parameter must be specified if addCACert is set to `true`. /user-home/_global_/config/oidc/ca.crt user-home/_global_/config/oidc/tls.crt

Procedure

If you configured the IAM Service to use authentication certificates:
1. Extract the IAM Service certificate files by running the following command:
```
oc extract secret/platform-auth-secret -n common-services-project --to=-
```
  Replace common-services-project with the Red Hat OpenShift project where the common services are deployed.
2. Import the ca.crt file to Cloud Pak for Data by running the following command:
```
oc cp ca.crt $(oc get pod -n Project_name -l component=usermgmt | tail -1 | cut -f1 -d\ ):/user-home/_global_/config/oidc/
```
  Replace Project_name with the Red Hat OpenShift project where Cloud Pak for Data is deployed.
3. Import the tls.crt file to Cloud Pak for Data by running the following command:
```
oc cp tls.crt $(oc get pod -n Project_name -l component=usermgmt | tail -1 | cut -f1 -d\ ):/user-home/_global_/config/oidc/
```
  Replace Project_name with the Red Hat OpenShift project where Cloud Pak for Data is deployed.

Create the oidcConfig.json file. Specify the appropriate values for your environment:

{
  "issuer": "my_issuer_value",
  "authorizationUrl": "my_authorizationURL_value",
  "tokenUrl": "my_tokenUrl_value",
  "clientID": "my_clientID_value",
  "clientSecret": "my_clientSecret_value",
  "callbackUrl": "my_callbackUrl_value",
  "fieldToAuthenticate": "id",
  "addCACert": true,
  "CACertPathList":
    [
      "/user-home/_global_/config/oidc/ca.crt",
      "/user-home/_global_/config/oidc/tls.crt"
    ]
}

Remember: If you did not configure the IAM Service to use authentication certificates, set addCACert to false and remove the CACertPathList parameter.

Import the oidcConfig.json file to Cloud Pak for Data:
```
oc cp oidcConfig.json $(oc get pod -n Project_name -l component=usermgmt | tail -1 | cut -f1 -d\ ):/user-home/_global_/config/oidc/
```
Replace Project_name with the Red Hat OpenShift project where Cloud Pak for Data is deployed.
Run the following command to delete the Cloud Pak for Data usermgmt pods:
```
oc delete pods -l component=usermgmt
```