IBM CloudPak SCIM Okta integration

From foundational services version 3.22 and later, CloudPak can use the OKTA-IAM integration by using SCIM to manage the users and groups at the CloudPak end. The OKTA-IAM 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-IAM integration, the organization can manage any employees' access to any application or device. Okta is a cloud-based, SaaS-delivered Identity and Access Management service (IAM) service that provides enterprise-grade identity lifecycle management capabilities to the developers and organizations.

Configuration required for OKTA integration using SSO/SAML and SCIM

Note:

• Follow this process until IBM Specific app is published in Okta Integration Network (OIN) catalog.
• You can create free Okta dev org by signing up to OKTA Dev portal. Both personal and official accounts are accepted. Once dev account is created, you can login to the dev account to get the main Okta dashboard.

Prerequisites:

• CloudPak must have foundational services version 3.22 or later.
• You must have a valid active OKTA account and org.
• CP console route must be displayed with the trusted certificate.
• CP console route must be publicly accessible over an internet unless Okta is deployed into private tenant.

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.

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

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

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 IAM liberty SAML metadata. You can use either the cloudctl command or samlmetadata API to get the SAML metadata. For more information, see Export metadata.

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.

   

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) Destination URL

     • 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 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: Matches regex (it can be adopted based on the groupName), Value: .*

   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.

    

12. Click Finish.

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

    

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.

• Go to Applications > Applications.

• In Applications page, select Assign Users to App. Then, select the user or group that you want to assign.

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 CloudPak foundational services version 3.22 IAM 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:

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

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": "PD94bW...3I+Cg==" 
       }, 
       "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:

• Login to the OpenShift Container platform by using oc CLI.

• 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 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 IAM Scim Server. For example, test@yahoo.com, a user that has been provisioned from OKTA to IAM SCIMServer. For more information, see steps that are mentioned in Configure SCIM integration with CloudPak SCIM server.

   

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

   

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

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

IMPORTANT:

• If you delete an Okta username in IAM, that username will not have access to the resources but that username is still displayed in the Access Control list in the Platform UI. The admin user in Platform UI can manually delete the user record from the Access Control list.

• When you delete teh Okta users, they lose access to the resources that they own, such as projects or deployment spaces. Adding a user with the same ID does not give that user access to the resources that are associated with that ID.

• If you update an Okta username in IAM, the old Okta username is still displayed in Access Control page of Platform UI. The admin user in Platform UI can manually delete the outdated user record from the Access Control list, and allow the updated user to enter as a new user record.

Configure SCIM integration with CloudPak SCIM server

Note: You can follow this configuration process until the IAM 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.

   

5. Select Add Integration.

6. Click Next. Then, click Done. Ignore the SSO configuration part. Leave it as it is.

7. Go to Provisioning > To App. In Provisioning to App page, select Enable options for Create users, Update User Attributes and Deactivate Users.

   

8. Click Integration.

9. Select Enable API Integration.

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

        

11. Test the API credential.

    Note:

    • 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 advised 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 10 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.

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