IBM Cloud Pak SCIM Okta integration

You can use SCIM for OKTA-IM integration to manage your IBM Cloud Pak® users and groups. The OKTA-IM integration also helps in managing the authentication and authorization of 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 employees' access to any application or device. Okta is a cloud-based, SaaS-delivered Identity Management (IM) service that provides enterprise-grade identity lifecycle management capabilities to the developers and organizations.

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

Configuration required for OKTA integration by using SAML SSO and SCIM

See the following notes:

See the following prerequisites:

Follow these steps to create an application:

  1. Create an Okta Org, if you don't have one. And, deploy the foundational services version 4.x.
  2. Create a SAML app and configure the app at Okta. For more information, see Configure Cloud Pak as SAML service provider (SP) at OKTA.
  3. Register Okta SAML IdP at your Cloud Pak. For more information, see Configure OKTA as SAML IdP at Cloud Pak.
  4. Create a SCIM app. Configure the app at Okta. For more information, see Configure SCIM integration with Cloud Pak SCIM Server.
  5. Provision SCIM for Okta users and groups. For more information, see Manage users and Manage groups.
  6. Log in or onboard to the Cloud Pak.

The image displays Okta Cloud Pak integration responsibilities

Primarily, the following main configurations are required to get OKTA-SCIM integration to work with your Cloud Pak along with SAML SSO.

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

Configure Cloud Pak as SAML service provider (SP) at OKTA

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

Steps

  1. Log in to the OKTA org. You see the Okta dashboard.
  2. From the navigation menu, click Applications > Applications. You see the Applications page.
  3. Click Create App Integration.
  4. Select SAML 2.0.
  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 Cloud Pak. Important: Even though the section name indicates (optional), you must provide at least one SAML attribute. Otherwise, the SAML configuration fails.

    Following are 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 following are 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 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. The following is an example mapping of the use of default attribute 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 reconfirm whether the SP metadata is configured correctly.

  11. Click Next and select an option to specify whether you are a customer or partner.
  12. Click Finish. You see the Sign on tab page.
  13. In the SAML Setup section, click View SAML setup instructions. You then see a page with instructions to configure SAML with your application.
  14. From the Optional section, copy the IdP metadata and save it to a file named idp-metadata-xml.xml.

After you copy the IdP metadata, assign the SAML application to the user or group who need to log in at the Cloud Pak end.

Note: This is a mandatory procedure for the user to be able to log in.

  1. From the navigation menu, click Applications > Applications. You see the Applications page.
  2. Select the application and users or groups that you want to assign to the application.

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 Cloud Pak

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 by 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 is used for configuring SCIM server Oauth authentication from Okta.

Note: Provide the redirect_uri for oauthClient registration.

Upon successful registration, you 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 must modify the value, not the key, based on the Okta SAML attribute configuration. For more information about attributes, see Step 9 in Configure Cloud Pak as SAML service provider (SP) at OKTA.

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

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

To get the Oauth client credentials:

  1. Log in to the OpenShift Container Platform by using oc CLI.

  2. Run the following commands:

      oc get secrets/okta-oidcclient-secret --template={{.data.CLIENT_ID} | base64 --decode
    
      oc get secrets/okta-oidcclient-secret --template={{.data.CLIENT_SECRET}} | base64 --decode
    

Once the registration is done, the SAML configuration can be validated by login through the cp-console directly. The default role is 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 for the users and groups, then complete the steps that are mentioned in Configure SCIM integration with Cloud Pak SCIM server before you proceed further.

To log in to the 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 was provisioned from OKTA to IM SCIMServer. For more information, see steps that are mentioned in Configure SCIM integration with Cloud Pak SCIM server.

    Add users

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

    Cloud Pak console login

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

Onboarded to CPD console from IM ScimServer

Member of the group can log in to the Platform UI console.

Member of groups in CPD console

Configure SCIM integration with Cloud Pak SCIM server

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

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:

      • Log in to the OpenShift Container Platform cluster by 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 the same as the value retrieved from OAuth Bearer token in Step 9 in Configure SCIM integration with Cloud Pak SCIM server.

    • Create a 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.