IBM CloudPak SCIM Okta integration

From foundational services version 3.22 and later, CloudPak can use the OKTA-IM integration by using SCIM to manage the users and groups at the CloudPak end. The OKTA-IM integration will also help in managing the authentication and authorization for the resources.

Okta is an enterprise-grade, identity management service that is built for the cloud, however, it is compatible with many on-premises applications. With Okta-IM integration, the organization can manage any employees' access to any application or device. Okta is a cloud-based, SaaS-delivered Identity Management service (IM) service that provides enterprise-grade identity lifecycle management capabilities to the developers and organizations.

The image shows high-level process diagram for OKTA SCIM integration

Configuration required for OKTA integration using SSO/SAML and SCIM

See the following notes:

See the following prerequisites:

Follow the steps in sequence:

  1. Create Okta Org if you have not created the Okta Org. And, deploy the foundational services version 3.22 and later.
  2. Create the SAML app and configure the app at Okta. For more information, see Configure CloudPak as SAML service provider (SP) at OKTA.
  3. Register Okta SAML IdP at CloudPak. For more information, see Configure OKTA as SAML IdP at CloudPak.
  4. Create SCIM App. Configure the app at Okta. For more information, see Configure SCIM integration with CloudPak SCIM Server.
  5. Perform SCIM provisioning for Okta users and groups. For more information, see Manage users and Manage groups.
  6. Login or onboard to the CloudPak.

The image displays Okta Cloudpak integration responsibilities

Primarily, the following main configurations are required to get OKTA SCIM Integration working with CloudPak along with SAML SSO.

Configuring CloudPak as SAML SP at Okta and configuring Okta as SAML IdP at CloudPak are performed to make the e2e SSO work. And, configuring SCIM integration with CloudPak SCIM server is performed to enable SCIM provisioning.

Configure CloudPak as SAML service provider (SP) at OKTA

Before you begin: You must have the SP, CloudPak CommonServices IM liberty SAML metadata. For more information, see SAML metadata export by using samlmetadata API.

Steps

  1. Login to the OKTA org. The Okta dashboard appears.
  2. Go to Applications > Applications. The Applications page appears.

  3. Click Create App Integration.

    The image displays app integration

  4. Select SAML 2.0.

    The image shows SAML window

  5. Click Next.

  6. Provide the App name.
  7. Click Next.

  8. Fill all the required details for the SAML configuration.

  9. Update the Attribute Statements (optional) section. It allows Okta to send the attributes in SAML response to CloudPak.

    The default User attributes:

    • Name: uid, Name format: Basic, Value: user.email
    • Name: firstName, Name format: Basic, Value: user.firstName
    • Name: lastName, Name format: Basic, Value: user.last.Name

    • Name: emailAddress, Name format: Basic, Value: user.email

      The default Group attributes:

    • Name: groups, Name format: Basic, Filter: Equals (it can be adopted based on the groupName), Value: groupName (groupName should be the Okta groupName)

    Note: While registering the Okta IdP, you can use the same default keys of the Name field (uid, firstName, lastName, emailAddress, groups) to specify the values in the token_attribute_mappings section. In case you have customized the attributes keys, use the customized keys only to specify the values in the token_attribute_mappings section. For more information, see SAML attributes statements. For example, if you are using the default attributes keys to specify the values in token_attribute_mappings section:

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

  10. Click Preview the SAML Assertion to re-confirm whether the SP metadata is configured correctly.

  11. Click Next and update the appropriate details.

    The image shows the details page

  12. Click Finish.

  13. Go to Sign on tab and click the link that is associated with View SAML setup instructions option.

    The link shows SAML set Up

  14. Once the link is opened, download the IdP metadata and save as idp-metadata-xml.xml.

  15. Assign the SAML application to the user or group who are required to login at the CloudPak end.

To assign the SAML application to the user or group:

Note: This is a mandatory procedure. Otherwise, the user will not be able to login.

If you want to assign existing LDAP users or group to the App, follow the procedure to first integrate OKTA Agent to LDAP Server. Once it is done, the LDAP entities can be imported to OKTA and used for assignment.

Configure Okta as SAML IdP at CloudPak

Use the IdP V3 API to register OKTA as SAML IdP. For now, the Okta registration is not supported through UI. Therefore, you need to perform the registration using API only. However, the process remains the same. For more information about the IdP v3 usage, see IdP V3 registration with Okta.

With the registration IdP v3 API, the required Oauth client is also created. This Oauth client will be used for configuring SCIM server Oauth authentication from Okta.

Note: Provide the redirect_uri for oauthClient registration.

Upon successful registration, you will get clientId and clientSecret name. From the clientSecret, both the clientId and clientSecret can be retrieved.

To be concluded, the IdP v3 Okta registration does the following:

See the following prerequisites:

Getting the redirect_uri

Based on the environment (a standard org, an EMEA org, and an Okta Preview org), the redirect_uri can be one of the following:

Note: Replace the ${appName} with the variable name for your application instance. If you don't know the variable name for application instance, you can find it as part of the App Embed link from the browser by opening the embed link or you can also check the Name attribute for the application at the /Apps API endpoint.

For example, if the URL embedded link is https://dev-68798908-admin.okta.com/admin/app/dev-68798908_iamsaml_3/instance/0oa6vnyhkm86B4xha5d7/#tab-general, the ${appName} will be dev-68798908_iamsaml_3 and the redirect_uri is, "redirect_uri": [https://system-admin.okta.com/admin/app/cpc/dev-68798908_iamsaml_3/oauth/callback].

Steps

  1. Use the IdP V3 API to register OKTA as SAML IdP.

    The sample for OKTA registration as SAML IdP :

    curl --location --request POST 'https://cpconsoleroute/idprovider/v3/auth/idsource' \
--header 'Authorization: Bearer $accessToken' \
--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": "Base64-encoded-metadata"
   },
   "jit": false,
   "scim_config":{
      "redirect_url": [
        "okta_redirect_url"
      ],
      "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"
            }
          }
   }
 }'

  2. Upon successful registration, you might get the status similar to the following:

     {
    "status": "success",
    "message": "Identity provider {OKTASAML} is successfully registered with unique identifier : defaultSP, oktaclient created with clientId: lgz9i024740cyuc0vl6eh3g7f6mv2b1f , client secret: okta-oidcclient-secret"
 }

    The error message resembles the following:

      401 "error": "Insufficient user permission for role : rolename"
  400 "error": "schema error:schema validation error followed by error"
  400 "error": "duplicate : Idp with protocol=saml is already created"
  500 "error": "Other errors"

    token_attribute_mappings: token_attribute_mappings is a custom mapping that user can provide based on the SAML attribute mapping that is configured at Okta. User should modify the values, not the key, based on the Okta SAML attribute configuration. For more information about attributes, see Step 9 in Configure CloudPak as SAML service provider (SP) at OKTA.

    scim_attribute_mappings: Provide the mapping attributes as in the CURL command. The defined mapping will be used in filter query, creating attributes and the response to be sent.

Note: You can get the client credential details from the secret that has been created. This client credential details are sent back as a response.

To get the Oauth client credentials:

Once the registration is done, the SAML configuration can be validated by login through the cp-console directly. The default role will be Viewer.

For Platform UI SAML login, you need to first complete the OKTA SCIM integration so that the provisioned user or group can be onboarded at Platform UI end. If you have not already completed the SCIM Integration and provisioned required for the users and groups, then complete the steps that are mentioned in Configure SCIM integration with CloudPak SCIM server before you proceed further.

To login Platform UI console, follow these steps:

  1. Onboard the user to Platform UI from the IM Scim Server. For example, test@yahoo.com, a user that has been provisioned from OKTA to IM SCIMServer. For more information, see steps that are mentioned in Configure SCIM integration with CloudPak SCIM server.

    Add users

  2. Once the user is onboarded, login to the Platform UI console with that user.

    CP console login

  3. Similarly, the provisioned group can also onboarded to Platform UI console from the IM ScimServer.

Onboarded to CPD console from IM ScimServer

Member of the groups can login to the Platform UI console.

Member of groups in CPD console

Configure SCIM integration with CloudPak SCIM server

Note: You can follow this configuration process until the IM SCIM App is published to OIN catalog. Later, you can use the proper Oauth configurations with clientID and clientSecret with the IBM Specific Integration App that has been created as a part of IdP V3 registration in Configure Okta as SAML IdP at CloudPak.

Steps

  1. Go to Okta dashboard.
  2. Go to Applications > Applications. The Application page appears.
  3. Select Browse App Catalog. The Browse App Integration Catalog page appears.

  4. In the search tab, type SCIM 2.0 Oauth. Then, select SCIM 2.0 Test App (OAuth Bearer Token) from the displayed options.

    SCIM Integration App

  5. Select Add Integration.

  6. Click Next. Then, click Done. Ignore the SSO configuration part. Leave it as it is.
  7. Go to Provisioning > Integration.
  8. Select Enable API Integration.

  9. Update the following details:

    • SCIM 2.0 Base URL: https://cpconsoleroute/idmgmt/identity/api/v1/scim

      Note: To get cpconsoleroute from cluster, see Getting the host details.

    • OAuth Bearer token: Update the accessToken as Oauth Bearer Token. To get the OAuth Bearer Token from cluster:

      • Login to OpenShift Container Platform cluster using oc CLI.

      • Run the following commands:

        oc get secrets/platform-auth-scim-credentials --template={{.data.scim_admin_password}} | base64 --decode

        curl -k -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -d
"grant_type=password&username=scimadmin&password=passwordfromabove&scope=openid"
https://cpconsoleroute/idprovider/v1/auth/identitytoken --insecure

        Update the SCIM 2.0 Base and OAuth bearer token

  10. Test the API credential.

    See the following notes:

    • It is expected that this validation might fail if you are trying for the first time as the Okta requires at least one user to be returned when the Okta validates the token. Therefore, it is advisable to manually create a user or run the runscope before you test the API credentials.

    • accessToken in the following CURL command is same as the value retrieved from OAuth Bearer token in Step 9 in Configure SCIM integration with CloudPak SCIM server .

    • Create user manually.

       curl --location --request POST 'https://cpconsoleroute/idmgmt/identity/api/v1/scim/users' \
 --header 'Authorization: Bearer ${accessToken}' \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": "Dummy",
   "name":
   {
     "givenName": "Dummy",
     "middleName": "",
     "familyName": "Dummy"
   },
   "emails":
   [{
     "primary": true,
     "value": "Dummy@ibm.com",
     "type": "work"
   }],
     "displayName": "Dummy",
     "externalId": "Dummy",
     "groups": [],
     "active": true
   }'

    • To run the RunScope, see Scope of tests.

  11. Once the token is verified, follow the process to start provisioning for Managing users and Managing groups.

Note: If you want to provision existing LDAP users or groups to the App, follow the procedure to first integrate OKTA Agent to LDAP Server. Once it is done, the LDAP entities can be imported to Okta and used for the assignment.