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.

Configuration required for OKTA integration by using SAML SSO and SCIM

See the following notes:

• Use the following process until an IBM-specific application is published in the Okta Integration Network (OIN) catalog.
• You can create a free Okta dev org by signing up on the OKTA Dev portal. Both personal and official accounts are accepted. Once you create a dev account, you can log in to the dev account to get the main Okta dashboard.

See the following prerequisites:

• You must have a valid active OKTA account and org.
• The cp-console route must be displayed with the trusted certificate.
• The cp-console route must be publicly accessible over an internet unless Okta is deployed in a private tenant.

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.

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

• Configure Cloud Pak as SAML service provider (SP) at OKTA
• Configure OKTA as SAML IdP at Cloud Pak
• Configure SCIM integration with Cloud Pak SCIM Server

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.

   • Single sign-on URL: Get ACS URL from the Liberty SAML metadata. For example, https://cpconsole/ibm/saml20/defaultSP/acs. To get the cpconsoleroute, see Getting host details.

   • Audience URI (SP Entity ID): Get Entity ID from Liberty SAML metadata. For example, https://cpconsole/ibm/saml20/defaultSP. To get the cpconsoleroute, see Getting host details.

   • Name ID format: EmailAddress

   • Application Username: Okta username

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:

• Register Okta as SAML IdP
• Register Okta to Liberty oauthClient while returning the client credentials.

See the following prerequisites:

• Download the idp-metadata-xml from Okta.
• Encode the idp-metadata-xml content as base64. For example, cat idp-metadata-xml |base64.
• You need to pass the redirect_uri for OKTA oauth client creation along with IdP V3 registration.

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:

• https://system-admin.okta.com/admin/app/cpc/${appName}/oauth/callback
• https://system-admin.okta-emea.com/admin/app/cpc/${appName}/oauth/callback
• https://system-admin.oktapreview.com/admin/app/cpc/${appName}/oauth/callback

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.

   

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

   

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

Member of the group can log in to the Platform UI 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.

   

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
       

       

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.