Table of contents

Integrating with Cloud Platform Common Services

IBM® Cloud Platform Common Services are optional, foundational services that can be shared by multiple products that are installed on the same Red Hat® OpenShift® cluster.

What are common services?

The common services help you manage and administer IBM software on your cluster. For example, the Cloud Platform Common Services include services such as the License Service and the Identity and Access Management Service.

A common service is installed once and is used by any applications that can integrate with the service. For example, you install IBM Cloud Pak for Data and another IBM Cloud Pak on your Red Hat OpenShift cluster. If both platforms support the License Service, you can install one instance of the License Service and both platforms will use that instance of the License Service.

Supported common services

Cloud Pak for Data integrates with the following Cloud Platform Common Services:
Service About this service Why should I install this service? Supported on
License Service Measure your Virtual Processor Core (VPC) usage data so that you can stay within your license terms.
Supported version
1.2.3 or later
Learn more
See the License Service documentation in the IBM Cloud Platform Common Services Knowledge Center
Install this service if you want to measure your actual VPC usage against your license terms.
  • Red Hat OpenShift Version 3.11
  • Red Hat OpenShift Version 4.5
IAM Service The Identity and Access Management Service (IAM Service) enables you to create a single point of entry for access management and single sign-on (SSO).
Supported version
3.x
Learn more
See the IAM Service documentation in the IBM Cloud Platform Common Services Knowledge Center
Install this service if you plan to install multiple applications that support the IAM Service on your cluster.

Cloud Pak for Data has its own identity and access management implementation, so this service is unnecessary if you don't have other applications that support the IAM Service on your cluster.

  • Red Hat OpenShift Version 4.5

Installing the common services

Remember: If you already installed the Cloud Platform Common Services on your cluster, you do not need to install them again.

Cloud Pak for Data includes entitlement to the Cloud Platform Common Services.

Follow the appropriate documentation for installing the common services on your Red Hat OpenShift cluster:

Environment Obtaining the Cloud Platform Common Services Documentation
Red Hat OpenShift Version 3.11 You can download the Cloud Platform Common Services from IBM Passport Advantage®. Download the correct package for your license:
  • IBM Cloud Pak for Data Enterprise Edition - Common Services (CC649EN)
  • IBM Cloud Pak for Data Standard Edition - Common Services (CC64FEN)
See the following documentation in the IBM Cloud Platform Common Services Knowledge Center:
Red Hat OpenShift Version 4.5 When you follow the IBM Cloud Platform Common Services installation instructions, you create the Operand Deployment Lifecycle Manager Operator, which enables you to pull the Cloud Platform Common Services from https://quay.io. See the following documentation in the IBM Cloud Platform Common Services Knowledge Center:

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:

  1. Log in to your Red Hat OpenShift cluster as a project administrator:
    oc login OpenShift_URL:port
  2. 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.
  3. Create the custom resource definition file:
    oc create -f cpd-oidc-client.yaml
  4. 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:433/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

  1. 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.

  2. 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.
  3. 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.

  4. Run the following command to delete the Cloud Pak for Data usermgmt pods:
    oc delete pods -l component=usermgmt

Accessing the common services

Ready to use the common services? See the following topics in the Cloud Platform Common Services documentation: