Authors : Nusaiba K K and Dhanesh M 

Configuring IBM Cloud Pak for Business Automation with Okta external Identity Provider (IdP)

Identity and access management are critical components of any enterprise deployment. When working with IBM Cloud Pak for Business Automation (CP4BA), integrating with a trusted identity provider like Okta allows organizations to centralize authentication and enhance security across applications.

In this guide, we’ll walk you through the process of integrating Okta with IBM CP4BA using Identity Management (IM) provided by the Cloud Pak foundational services.

Why Integrate Okta with CP4BA?

Okta provides a robust, enterprise-grade identity solution that simplifies authentication while enforcing strong security practices. Integrating Okta with CP4BA ensures:

• Centralized user and group management.

• Secure, standards-based authentication using OIDC or SAML.

Improved compliance and audit readiness.

Known Limitations of Okta :

Here is the reference to the known limitations of Okta external IdP : IBM Docs

Prerequisites

Before you start, ensure the following requirements are met:

• Cluster Access
  You must have access to your ROKS cluster with appropriate administrative privileges.
• Storage Configuration
  You must have a valid block storage class available in the cluster. You can verify this by running:

  oc get sc
  

• Okta Setup
  You need an Okta Developer Account or an enterprise Okta environment with administrative rights to configure an OIDC application.

---

Follow the steps below in order to configure Okta as the Identity Provider for IBM Cloud Pak for Business Automation.

Step 1: Run the Cluster Admin Setup Script

The first step in integrating Okta with CP4BA is to set up the operators in your OpenShift cluster. This ensures that all required services for Cloud Pak and Identity Management are available.

1.1 Clone the cert-kubernetes repository

Start by cloning the cert-kubernetes repository (25.0.0 build is taken as an example), which contains the scripts for setting up cluster administrators:

git clone -b 25.0.0 https://github.com/ibm-cert-kubernetes.git
cd cert-kubernetes/scripts/

1.2 Run the Cluster Admin Setup Script

Execute the script to configure the cluster with the necessary permissions and foundational services:

./cp4a-clusteradmin-setup.sh

---

1.3 Verify Operator Installation

Once the script completes, verify that all operators are installed successfully. You can monitor their status using the following command:

oc get csv -n <operator-namespace>

Replace <operator-namespace> with the namespace where your operators are deployed (e.g., openshift-operators or your custom namespace).

Tip: Wait until all operators show a status of Succeeded before moving on to the next step.

Step 2: Create Cloud Pak Foundational Services Resources

In this step, we create the Common Services (CS) resources required to configure Identity Management (IM) with Okta. This involves creating a configuration file and applying it to your OpenShift cluster.

---

2.1 Create the cs.yaml Configuration File

Create a file named cs.yaml and add the following content. Update the placeholders (<<...>>) with values specific to your environment:

apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  namespace: <<operator-namespace>>
  name: common-service
spec:
  license:
    accept: true 
  operatorNamespace: <<operator-namespace>>
  servicesNamespace: <<services-namespace>>
  size: starterset
  storageClass: <<block storage class in CP4BA CR>>
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: iaf-system-automationui-aui-zen-ss-issuer # fixed name
  namespace: <<services-namespace>>
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: iaf-system-automationui-aui-zen-ca # fixed name
  namespace: <<services-namespace>>
spec:
  commonName: IBM Automation Foundation CA
  duration: 2160h0m0s
  isCA: true
  issuerRef:
    kind: Issuer
    name: iaf-system-automationui-aui-zen-ss-issuer
  renewBefore: 720h0m0s
  secretName: iaf-system-automationui-aui-zen-ca # fixed value
  usages:
    - cert sign
    - signing
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: iaf-system-automationui-aui-zen-issuer # fixed name
  namespace: <<services-namespace>>
spec:
  ca:
    secretName: iaf-system-automationui-aui-zen-ca
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: iaf-system-automationui-aui-zen-cert # fixed name
  namespace: <<services-namespace>>
spec:
  commonName: cpd
  dnsNames:
    - cpd
    - cpd.{{ meta.namespace }} 
    - cpd.{{ meta.namespace }}.svc
    - <<sc_zen.zen_custom_route.route_host in cp4ba CR (default: cpd-<services-namespace>.<cluster_hostname_suffix>)>>
  duration: 2160h0m0s
  issuerRef:
    kind: Issuer
    name: iaf-system-automationui-aui-zen-issuer
  renewBefore: 720h0m0s
  secretName: iaf-system-automationui-aui-zen-cert # fixed value
  usages:
    - key encipherment
    - server auth
    - digital signature

---

Key Points to Note

• operatorNamespace → Namespace where the operators are installed.

• servicesNamespace → Namespace where services (operands/components) are deployed.

• storageClass → Use a valid block storage class. You can check available classes using:

  oc get sc

• <<sc_zen.zen_custom_route.route_host in cp4ba CR (default: cpd-<services-namespace>.<cluster_hostname_suffix>)>> this should be the cpd-route.

  To get <cpd-route>, run:

  oc get routes -n <namespace>

• For storage classes, IBM recommends using retain-gold classes, such as:

  • ibmc-block-retain-gold for block storage class and 

  • ibmc-file-retain-gold for file storage class

---

2.2 Apply the cs.yaml File

Run the following command to apply the resources:

oc apply -f cs.yaml

If Separation of Duties (SoD) is enabled:

• The Common Services CR (cs.yaml) must be created in the operatorNamespace.

• In other cases, use the servicesNamespace.

---

2.3 Verify the Certificate Secret

Ensure that the iaf-system-automationui-aui-zen-cert secret exists in the cluster:

oc get secret iaf-system-automationui-aui-zen-cert -o yaml

If SoD is enabled:

• The secret must be in the servicesNamespace.

• Switch to that namespace before running the command.

---

2.4 Update OperandRequest.yaml and ZenService.yaml

Use the output from the previous command to update OperandRequest.yaml and ZenService.yaml, replacing placeholders with your cluster values.

After creating the cs.yaml configuration and verifying the certificate secret, the next step is to configure the OperandRequest and ZenService resources.

---

2.4.1 Create OperandRequest.yaml

Create a file named OperandRequest.yaml with the following content. Replace all placeholders (<<...>>) with your cluster-specific values:

kind: Secret
apiVersion: v1
metadata:
  name: external-tls-secret # fixed name
  namespace: <<namespace>>
data:
  ca.crt: <<ca.crt from secret iaf-system-automationui-aui-zen-cert>>
  cert.crt: <<tls.crt from secret iaf-system-automationui-aui-zen-cert>>
  cert.key: <<tls.key from secret iaf-system-automationui-aui-zen-cert>>
type: Opaque
---
apiVersion: operator.ibm.com/v1alpha1
kind: OperandRequest
metadata:
  namespace: <<namespace>>
  name: iaf-system-common-service
spec:
  requests:
  - operands:
      - name: ibm-platformui-operator
      - name: ibm-im-operator
    registry: common-service
    registryNamespace: "ibm-common-services"  # fixed value

---

2.4.2 Create ZenService.yaml

Create another file named ZenService.yaml:

apiVersion: zen.cpd.ibm.com/v1
kind: ZenService
metadata:
  namespace: <<namespace>>
  name: iaf-zen-cpdservice
spec:
  iamIntegration: true
  scaleConfig: starterset
  zenCustomRoute:
    route_host: <<sc_zen.zen_custom_route.route_host in CP4BA CR (default: cpd-<namespace>.<cluster_hostname_suffix>)>>
    route_reencrypt: true
    route_secret: iaf-system-automationui-aui-zen-cert
  fileStorageClass: <<faster storage class in CP4BA CR>>
  blockStorageClass: <<block storage class in CP4BA CR>>

---

2.4.3 Apply the Configurations

First, apply the OperandRequest:

oc apply -f OperandRequest.yaml

Wait for the common services pods to be ready, then apply the ZenService:

oc apply -f ZenService.yaml

---

2.4.4 Verify Zen Service Status

The Zen and IM services can take 30 minutes or more to be ready. Check the status using:

oc get ZenService

The output should show:

NAME                   STATUS
iaf-zen-cpdservice     Completed

Proceed to the next step only when the ZenService status is Completed.

---

Step 3: Complete Okta Configuration with IM Service

In this step, you integrate Okta as the Identity Provider (IdP) in the IM service.

Configuring Okta Integration with IBM Cloud Pak for Business Automation Using SAML SSO and SCIM

IBM Cloud Pak for Business Automation (CP4BA) supports Okta integration for authentication and user provisioning through SAML 2.0 (for Single Sign-On) and SCIM (for automated user provisioning). This guide walks you through the complete step-by-step process of configuring Okta as an Identity Provider (IdP) for CP4BA.

---

Step 3.1: Set Up Okta Developer Account

1. Visit the Okta Developer Portal.

2. Sign up.

3. Confirm your email and log in to your Okta Developer Console.

4. You will be redirected to the Okta Dashboard, where you can manage:

   • Users

   • Applications

   • API Integrations

Create Users & Groups:

• Create users and assign them to appropriate groups.

• Activate each user by setting a password.

• These users are used later to authenticate against IBM Cloud Pak Identity Management (IM).

---

Step 3.2: Create a SAML Application in Okta

3.2.1 Create a New Application Integration

• Navigate to Applications

• Click Create App Integration.

• Select SAML 2.0 as the sign-in method and click Next.

---

Step 3.3: Configure SAML Settings in Okta

Define the Application Settings

• • App name: Enter a descriptive name (e.g., Cloud Pak SAML SSO).

  • Click Next to move to the SAML configuration form.

Basic SAML Configuration

• Single sign-on URL (ACS URL):
  https://<cp-console-route>/ibm/saml20/defaultSP/acs

• Audience URI (SP Entity ID):
  https://<cp-console-route>/ibm/saml20/defaultSP

• Name ID Format:
  EmailAddress

• Application Username:
  Okta username

• Default Relay State:

  EmailAddress

• Update application username on:

  Create and update



To get <cp-console-route>, run:

oc get routes -n <namespace>

---

Attribute Statements (Required)

Group Attribute

---

Example Token Attribute Mapping in CP4BA

"token_attribute_mappings": {
  "sub": "uid",
  "given_name": "firstName",
  "family_name": "lastName",
  "groups": "groups",
  "email": "emailAddress",
  "first_name": "firstName",
  "last_name": "lastName"
}

---

Preview and Verify

• Click Preview the SAML Assertion in Okta to ensure mappings match CP4BA expectations.

• Click Finish to complete app setup.

---

Step 3.4: Download Okta IdP Metadata

• Go to the Sign On tab of the new SAML app.

• Click View SAML setup instructions.

• Download the Identity Provider metadata XML.

• Save it as:
  idp-metadata-xml.xml

---

Step 3.5: Register Okta as IdP in CP4BA

To register Okta with CP4BA you need:

• Bearer Token from the IM service

• Base64 encoded IdP metadata

---

3.5.1 Get IM Service Credentials

From the OpenShift console:

• Search for the secret:
  ibm-iam-bindinfo-platform-auth-idp-credentials

• Copy:

  • username

  • password

---

3.5.2 Get Identity Token

Run:

curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
-d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&scope=openid" \
https://<cpconsole-route>/idprovider/v1/auth/identitytoken --insecure

---

3.5.3 Encode IdP Metadata

Run:

cat idp-metadata-xml.xml | base64

Remove whitespaces.

---

3.5.4 Register Okta IdP

Run the below command:

curl --location --request POST 'https://<YOUR-CP-CONSOLE-ROUTE>/idprovider/v3/auth/idsource' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "OKTASAML",
  "description": "OKTASAML",
  "protocol": "saml",
  "type": "okta",
  "idp_config": {
    "token_attribute_mappings": {
      "sub": "uid",
      "given_name": "firstName",
      "family_name": "lastName",
      "groups": "groups",
      "email": "emailAddress",
      "first_name": "firstName",
      "last_name": "lastName"
    },
    "idp_metadata": "<PASTE_YOUR_BASE64_ENCODED_METADATA_HERE>"
  },
  "jit": false,
  "scim_config": {
    "redirect_url": [
      "https://system-admin.okta.com/admin/app/cpc/<YOUR_OKTA_APP_NAME>/oauth/callback"
    ],
    "scim_attribute_mappings": {
      "user": {
        "principalName": "userName",
        "name": {
          "givenName": "givenName",
          "familyName": "familyName"
        },
        "displayName": "displayName",
        "emails": [
          {
            "value": "emails",
            "type": "home"
          }
        ],
        "id": "id",
        "userName": "userName"
      },
      "group": {
        "principalName": "displayName",
        "displayName": "displayName",
        "id": "displayName"
      }
    }
  }
}'

Output:

{
  "status": "success",
  "message": "Identity provider {OKTASAML} is successfully registered with unique identifier : defaultSP , client created with clientId: <client_id> , client secret: <client_secret>"
}

---

Step 3.6: Create a test User via SCIM

3.6.1 Get SCIM Credentials

From OpenShift secrets:
platform-auth-scim-credentials 

---

3.6.2 Get SCIM API Token

Run:

curl -k -X POST \
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
-d "grant_type=password&username=<scimadmin-username>&password=<PASSWORD>&scope=openid" \
https://<cp-console-url>/idprovider/v1/auth/identitytoken --insecure

---

3.6.3 Create User

Run the below command to create the test user :

curl --insecure --location --request POST 'https://<cp-console-url>/idmgmt/identity/api/v1/scim/users' \
--header 'Authorization: Bearer <your-token-here>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "test",
  "name": {
    "givenName": "test",
    "familyName": "test"
  },
  "emails": [
    {
      "primary": true,
      "value": "test@ibm.com",
      "type": "work"
    }
  ],
  "displayName": "test",
  "externalId": "test",
  "groups": [],
  "active": true
}'

Verify the successful creation of the test user by executing the following :

GET https://<cp-console-url>/idmgmt/identity/api/v1/scim/users

Run the below command to get the cp-console-url :

oc get routes -n <namespace> | grep cp-console

3.7 Assign a Group to the Project in Okta

1. Navigate to your Okta project , example project used here is : Cloud Pak SAML SSO

2. Go to Assignments → Groups.

3. Select a previously created group (e.g., oktatestgroup) and click Save.

---

Step 4 : Integrating Okta SCIM 2.0 with IBM Cloud Pak Console for User and Group Provisioning

Managing user identities and groups across enterprise platforms can be a challenge. With Okta SCIM 2.0 integration, you can automate user and group provisioning for IBM Cloud Pak (CP) Console(or zen), ensuring seamless identity management and reducing manual work.

This blog guides you through the steps to setup Okta SCIM integration using the IBM Cloud Pak console (cp-console).

---

4.1 Why SCIM Integration with Okta?

SCIM (System for Cross-domain Identity Management) is an open standard for automating user provisioning across platforms. By integrating Okta SCIM 2.0 with CP4BA, you can:

• Automatically create users in CP Console when they are added in Okta.
• Keep user attributes updated across systems.
• Automatically deactivate users in CP Console when they are removed from Okta.
• Increased security and lesser administrative overhead

---

4.2 Add the SCIM 2.0 App in Okta

1. In Okta, go to Applications → Browse App Catalog.

2. Search for SCIM 2.0.

3. Select SCIM 2.0 Test App (Bearer Token).

4. Click Add and complete the setup using default values.

---

4.3 Configure API Integration

1. Go to the newly created SCIM 2.0 app → Provisioning tab.

2. Click Configure API Integration.

3. Enable “Enable API Integration”.

4. Enter the following details:

SCIM 2.0 Base URL:

https://<your-cp-console-url>/idmgmt/identity/api/v1/scim

1. Bearer Token: Token retrieved from step 3.6.2 (Get SCIM API Token)

   • Run the below command to get the cp-console-url :

     oc get routes -n <namespace> | grep cp-console

2. Click Test API Credentials → Ensure the test is successful.

3. Click Save.

---

4.4 Enable User Provisioning Features

1. Under To App → Edit, enable:

   • Create Users

   • Update User Attributes

   • Deactivate Users

2. Click Save.

---

4.5 Assign the Group to the SCIM App

1. In the Assignments tab of the SCIM app, assign the test group (e.g., oktatestgroup).

2. Keep default values and click Save.

---

4.6 Validate Users

Send the following request to confirm users are synced from Okta to CP4BA:

GET https://<cp-console-url>/idmgmt/identity/api/v1/scim/users
Authorization: Bearer <token>

Bearer Token: Token retrieved from step 3.6.2 (Get SCIM API Token)

You should see both manually created users and those synced from Okta.

Sample Response:

{
  "totalResults": 4,
  "Resources": [
    { "userName": "testadminuser@test.com", "displayName": "testadmin user" },
    { "userName": "oktaadmin@test.com", "displayName": "okta admin1" }
  ]
}

---

4.7 Sync and Validate Groups from Okta

1. In Okta, go to the Push Groups tab of the SCIM app.

2. Click Push Groups → Find Groups by Name.

3. Search for your group (e.g., oktatestgroup) and click Save.

---

4.8 Validate Group Assignments

Send the following request to confirm groups are synced from Okta to CP4BA:

GET https://<cp-console-url>/idmgmt/identity/api/v1/scim/groups
Authorization: Bearer <token>

Sample Response:

{
  "displayName": "oktatestgroup",
  "members": [
    { "display": "testadminuser@test.com" },
    { "display": "oktaadmin@test.com" }
  ],
  "realmName": "OKTASAML"
}

---

Final Outcome

You have successfully:

• Integrated Okta SCIM 2.0 with CP4BA.
• Enabled automatic user and group provisioning.
• Verified that users and groups from Okta are synced with CP4BA.

Okta SAML + SCIM Integration Completed!

Now Okta is fully integrated with IBM Cloud Pak for Business Automation using SAML SSO and SCIM provisioning.

Step 5 : Configure and Test Enterprise SAML Login on OpenShift

Integrating Enterprise SAML with OpenShift  ensures a secure, centralized authentication experience using your identity provider (e.g., Okta). Follow this step-by-step guide to validate the Enterprise SAML login.

---

Step 5.1: Retrieve OCP Credentials

• Log in to your OpenShift Container Platform (OCP).
• Copy credentials from the following secret:

  Secret Name: ibm-iam-bindinfo-platform-auth-idp-credentials

• Run the below oc command to extract the username and password:

  oc get secret ibm-iam-bindinfo-platform-auth-idp-credentials -n <namespace> -o jsonpath='{.data.username}' | base64 -d

---

Step 5.2: Login to Zen

1. Navigate to your cpd route(zen-route) under Networking → Routes in OpenShift.
2. Log in using the extracted credentials from step 5.1.

---

Step 5.3: Add a New User

1. In the platform UI or Zen service, go to:
   Administration → Access Control → Add User.

2. Add the Okta user that was provisioned from your IdP.

3. Click Next.

4. Assign the following roles:

   • Admin

   • User

5. Click Add.

---

Step 5.4: Create a Group and Link to Identity Provider

1. Navigate to:
   Administration → Access Control → Create Group.

2. Set:

   • Group Name: Provide a name to identify your group

3. In the Identity Provider Groups section:

   • Type the group name (e.g., oktatestgroup) and select it from the list(Select the Okta group that was pushed from your IdP).

4. Assign roles:

   • Admin

   • User

5. Click Next, then Create.

---

Step 5.5: Test Enterprise SAML Login

1. Log out of your current session.

2. On the login page, select Enterprise SAML login.
3. Use the Okta user credentials to log in.

Output

If the configuration is completed successfully, the Okta user should be able to log in via SAML authentication with the appropriate assigned roles.

---

Step 6 : Installing the CP4BA deployment with Okta (an external IdP) integration

When integrating Okta as an external Identity Provider (IDP) for IBM Cloud Pak for Business Automation (CP4BA), the deployment process slightly differs from the standard LDAP-based configuration. This guide walks you through the exact steps.

---

Step 6.1 : Run the Prerequisites Script in Property Mode

1. Update the property files as follows:

cp4ba_LDAP.Property

• No LDAP configurations are required.

• No LDAP certificates are needed, since authentication is handled by the external IDP.

cp4ba_user_profile.Property

• Update the username and password with an active Okta user and its corresponding password.

• Set the group name to the Okta group that has:

  • Been pushed to Identity Management (IM).

  • Onboarded to Zen services.

• All other configurations remain the same as a standard LDAP-based deployment (refer to IBM Docs).

---

Step 6.2 : Run the Prerequisites Script in Generate Mode

• This step creates the required secrets and databases.

---

Step 6.3 : Run the Prerequisites Script in Validate Mode

• If validation is successful, proceed to the next step(LDAP validation fails and is expected)

• If validation fails (except LDAP validation), review and correct the property files.

---

Step 6.4 : Run the Deployment Script to Generate the CR File

• Open the CR file to make the following changes:

  1. The ldap_configuration section should be removed if present.
  2. Set the shared_configuration.sc_skip_ldap_config parameter to true.
  3. Set the sc_content_initialization parameter to true and also define the initialize_configuration section in the CR for the operator to use the parameters.
  4. Add YAML to configure IM with Okta .

     To configure OKTA, add the following YAML at the same level as the shared_configuration section.

  
  idp_iam_configuration:
    - idp_allow_email_or_upn_short_names: true 
      idp_id: OKTASAML
      idp_type: okta
  

• Ensure that the idp_id value matches your IDP Provider name in IM.

• idp_allow_email_or_upn_short_names  This is an Optional field and the default value is true

---

Step 6.5 : Proceed with Deployment

• Complete the deployment as usual.

• All other configurations remain the same as a standard LDAP-based deployment (refer to IBM Docs).

---

Post-Deployment

Once configured, users should be able to log in to CP4BA components using Enterprise SAML authentication method.

Credits:

We would like to extend my sincere thanks to the reviewers Adam Davis, Todd Deen, Anisha Suresh, Dheeraj Kumar Krishan and Justin Wang for their valuable feedback and support throughout the development of this blog.