Configuring single sign-on using OpenID Connect (OIDC)

Using OIDC, you can configure single sign-on (SSO) between your product and supported providers. You can configure OIDC with just-in-time (JIT) provision only.

You can configure SCIM API for Users and Groups after you successfully authenticate with OIDC when JIT is enabled.

OIDC is an authentication protocol layer that is built on the OAuth 2.0 protocol. It allows the third-party applications to:

The following steps represent the flow that happens during SSO configuration by using OIDC:

  1. A user attempts to access a service in your product through a web browser.

  2. Your product verifies whether an authentication token is present.

  3. If no authentication token is present, your product redirects the request for authentication to the third-party authorization server of the user.

  4. The authorization server presents a login page to the user.

  5. If the user logs in successfully, the authorization server redirects the user, along with the OIDC response, to your product.

  6. Your product generates an authentication token and grants access to the service that the user requested.

Note: You can use PKCE with OIDC for protection from authorization code interception attacks for OAuth 2.0 public clients. For more information, see PKCE support for OpenID Connect clients Opens in a new tab. The IM service enables PKCE by default. If your OIDC provider configures PKCE, you can use it for authentication in the IM login flow. If the OIDC provider does not configure PKCE, it does not impact the IM login flow.

Configuring SSO in your product by using OIDC

See the following notes:

Before you begin

Log in to any of the following platforms by using the provided IdP links and register yourself in the application. During registration, use application URL as cp-console URL and redirect URL as https://<cp-console-url>/ibm/api/social-login/redirect/<name of the oidc>. Once you are registered, you can get the unique client ID, client secret and discovery_url endpoint. Currently, only these platforms are verified to register the OIDC by using the IdP V3 API.

Verified platforms to register OIDC provider using IdP V3
Platform IdP link
IBM Security Verify (ISV) https://www.ibm.com/docs/en/erqa?topic=using-security-verify-as-oidc-provider
Note: Whenever you perform the attributes mapping through the OIDC provider in the ISV application, enable the Send all known user attributes in the ID token option. And, ISV groups must not contain spaces.
Google Cloud Platform https://cloud.google.com/identity-platform/docs/web/google
Microsoft https://cloud.google.com/identity-platform/docs/web/microsoft
Okta https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm

Procedure

Complete the following steps to configure SSO with OIDC:

Configuring OIDC at IdP end

To configure SSO, complete the following sequence of steps:

  1. Register the OIDC clients. For more information, see Registering the OIDC clients.

  2. Get the list of registered OIDC clients. For more information, see Getting the list of registered OIDC clients.

    If you need to delete the registration of the client, see Deleting the registration of the client.

  3. Open the Cloud Pak home page to verify whether the OIDC is successfully configured.

    Note: After the OIDC is successfully configured, you can log in to the cp-console. However, to log in to the Cloud Pak Platform and to get the OIDC successfully configured, first you need to onboard the OIDC users into the Cloud Pak Platform. Then, the OIDC users are able to log in to the Cloud Pak Platform.

  4. To authenticate, click the corresponding OIDC link in the Cloud Pak home page.

Configuring OIDC at RP end

You can configure OIDC at Relying Party (RP) end with the Platform-UI or API.

Configuring OIDC at RP with Platform-UI

  1. Log on to the cp-console as an administrator.

    To get the cp-console URL, username, password, complete the following steps:

    1. Log on to the console as an administrator.
    2. Go to Networking > Routes.
    3. Set the project to the namespace where you deployed the foundational services.
    4. Find the cp-console route and click the URL in the Location section.
    5. Log on to the cp-console with the username and password. To get the username and password, go to Workloads > Secrets and search for platform-auth-idp-credentials. You can copy the admin_username and admin_password from the Data section and log on to the cp-console.

  2. Click New Connection and Select OIDC as the protocol type. The New OIDC Connection page is displayed.

  3. Enter the required values for the parameters in the Connection details, Token attribute mapping, and Site settings sections.

Table 1. Connection details parameters
Parameter Description
Name The name of the OIDC connection.
Description (optional) Description of the OIDC connection.
Use in conjunction with an existing ldap For OIDC with LDAP dependency, enable Use in conjunction with an existing ldap toggle option. From the Specify LDAP Connection drop-down list, choose the existing LDAP to integrate.
Table 2. Token attribute mapping parameters
Parameter Default Value Description
Sub sub The subject of the ID token. The default value for OIDC configuration is sub. You can manually override the default value based on your requirements.
Given name firstName The first name of the user.
Family name lastName The last name of the user.
Groups blueGroups The groups parameter is used to associate a Client session with a set of Authorization Roles.
Email emailAddress The email address of the user.
Unique security name (optional) uniqueSecurityName A unique security name is used to identify the subject.
Preferred username (optional) preferred_username The preferred username of the user
Display name (optional) displayName The display name of the user.
Table 3. Site settings parameters
Parameter Description
Well-known URI The URL includes the configuration information for the identity provider such as authorization endpoint, token endpoint, and other details that are required to interact with the identity provider.
Client ID The unique identifier that is assigned to your application to find your application when you request or refresh the access tokens.
Client secret The unique key to authenticate your application.

Note: JIT is enabled by default when you configure OIDC using console. If you enable the Use in conjunction with an existing ldap toggle option, the JIT is disabled.

  1. Click Create.

Configuring OIDC at RP with API

Run the following curl command:

  curl --insecure POST 'https://cp-console.apps.vij-soc.cp.fyre.ibm.com/idprovider/v3/auth/idsource/'
  --header "Authorization: Bearer $ACCESS_TOKEN"
  --header 'Content-Type: application/json'
  --data-raw
  {
      "name": "oidctestbh",
      "protocol": "oidc",
      "type": "default",
      "description": "sample oidc payload",
      "enabled": true,
      "idp_config": {
          "client_id": "<client_id>",
          "client_secret": "<client_secret>",
          "discovery_url": "<well Known URI>",
          "token_attribute_mappings": {
              "sub": "sub",
              "subject": "sub",
              "email": "emailAddress",
              "groups": "blueGroups",
              "given_name": "firstName",
              "displayName": "displayName",
              "family_name": "lastName",
              "preferred_username": "preferred_username",
              "uniqueSecurityName": "uniqueSecurityName"
          }
      },
      "jit": true,
      "scim_config": {
          "scim_attribute_mappings": {
              "user": {
                  "principalName": "firstName",
                  "userName": "uid",
                  "displayName": "firstName",
                  "emails": [
                      {
                          "value": "emailAddress",
                          "type": "primary"
                      }
                  ]
              },
              "group": {
                  "principalName": "displayName",
                  "created": "meta.created",
                  "lastModified": "meta.lastModified"
              }
          }
      }
  }

The default value for sub parameter in the token_attribute_mappings is sub. If you update the default value, you need to specify the sub and subject attributes in token_attribute_mappings to use the custom value in the sub attribute. If you do not specify subject attribute, the default value of the sub attribute is used for the OIDC configuration.

The scim_attribute_mappings is an optional attribute. If you specify the values for scim_config.scim_attribute_mappings, ensure that the values are the same as the token_attribute_mappings attribute that is configured at OIDC IdP end as OIDC token claims.

If you do not specify the values for scim_config.scim_attribute_mappings, IM uses the following default SCIM attribute mappings for user and group:

  "user": {
                  "principalName": "firstName",
                  "userName": "uid",
                  "displayName": "firstName",
                  "emails": [
                      {
                          "value": "emailAddress",
                          "type": "primary"
                      }
                  ]
              },

  "group": {
                  "principalName": "displayName",
                  "created": "meta.created",
                  "lastModified": "meta.lastModified"
              }

Note: Ensure that you manually remove the user or group from the database when you remove the user or group from OIDC IdP.

Granting an admin role to Cloud Pak Platform

Before you begin, onboard OIDC users into the Cloud Pak Platform.

Important: If you configure multiple authentication types (SAML, LDAP, and OIDC) in your cluster, and onboard same users to all the authentication types, the users might not be able to log in the first time by using OIDC. They might be able to log in the second time. To overcome the limitation, onboard users by following the instructions in Integrating IBM Cloud Pak SAML with Azure Active Directory.

Now, complete the following steps to grant an Admin role for Cloud Pak Platform. The procedure is based on the APIs.

  1. Configure environmental variables:

    1. Obtain an IM access token for the default admin user. For more information, see Preparing to run API commands.

    2. Set the HOST environment variable. To get the host value, run the following command:

      oc get route -n <your-foundational-services-namespace>

      Set the HOST to the cp-console route. For example, export HOST=<cp-console>.

    3. Set CPHOST to the cpd route with corresponding ibm-nginx-svc service name. For example, CPHOST=cpd-cp4i.apps.bunny.cp.abc.ibm.com.

  2. Get the IBM Cloud Pak access token for the admin user.

    curl -ki -X GET 'https://'$CPHOST'/v1/preauth/validateAuth' --header 'username: cpadmin' --header "iam-token: $TOKEN"

    Note: The default username for the new cluster installation is cpadmin. If you upgrade the existing cluster, the default username is admin.

  3. Create a user group with the role that you want to assign to the user.

    curl -k -s  -X POST 'https://'$CPHOST'/usermgmt/v2/groups' \
--header 'Content-Type: application/json'   \
--header 'Accept: application/json'   \
--header "Authorization: Bearer $CPTOKEN" \
-d
'{"name": "isv group",
"description": "Group default ISV group",
"role_identifiers": ["zen_user_role"]
}'

    Note: To create an admin group, in "role_identifiers", specify the “zen_administrator_role”.

    Verify whether the group is listed, and get the group ID:

    curl -k -s  -X GET 'https://'$CPHOST'/usermgmt/v2/groups' \
--header 'Content-Type: application/json'   \
--header 'Accept: application/json'   \
--header "Authorization: Bearer $CPTOKEN"

  4. Add the isv group or users into the user groups:

    • To add the isv group, run the following command:

      curl -k -s  -X POST 'https://'$CPHOST'/usermgmt/v2/groups/<group_ID>/members' \
--header 'Content-Type: application/json'   \
--header 'Accept: application/json'   \
--header "Authorization: Bearer $CPTOKEN" \
-d
'{
"ldap_groups": ["admin"]
}'

      In the command, the group_ID is the isv group ID that you got in the previous step.

    • For OIDC with AzureAD, you need to specify sub and subject attributes in token_attribute_mappings to update the default values of the sub attribute with the user principal name of the AzureAD user. Run the following command to directly onboard the users to the user groups:

      curl -k -X POST 'https://'$CPHOST'/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H "Authorization: Bearer $CPTOKEN" -d '[
  {
    "sub": "upn@tenantid.onmicrosoft.com"
    "displayName": "upn ibm",
    "email": "upn@ibmdummy.com",
    "username": "upn@tenantid.onmicrosoft.com",
    "user_roles": ["zen_administrator_role"],
    "subject": "upn@tenantid.onmicrosoft.com"
  }
]'

      Replace upn and tenantid with the user principal name and tenant ID of the AzureAD user.

      The value of the subject attribute can be the same as the sub attribute. If you do not specify subject attribute, the default value of the sub attribute is used for the OIDC configuration to onboard the users.

    • If you set the sub attribute with email of the user, you can directly onboard the user to the user groups with the following command:

      curl -k -X POST 'https://'$CPHOST'/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H "Authorization: Bearer $CPTOKEN" -d '[
  {
    "displayName": "user",
    "email": "user@gmail.com",
    "username": "user@gmail.com",
    "user_roles": ["zen_administrator_role"]
  }
]'

      You need to update the values of the parameters in the command based on your requirements.

    • To add the multiple users, run the following command:

      curl -k -X POST 'https://<cp_host>/usermgmt/v1/user/bulk' -H 'Content-Type: application/json' -H "Authorization: Bearer <cp_token>" -d '[
  {
    "displayName": "icpuser1@user1gmail.onmicrosoft.com",
    "email": "icpuser1@user1gmail.onmicrosoft.com",
    "username": "icpuser1@user1gmail.onmicrosoft.com",
    "user_roles": ["zen_administrator_role"]
  },
  {
    "displayName": "testuser1@user1gmail.onmicrosoft.com",
    "email": "testuser1@user1gmail.onmicrosoft.com",
    "username": "testuser1@user1gmail.onmicrosoft.com",
    "user_roles": ["zen_administrator_role"]
  }
]'

      You need to update the values of the parameters in the command based on your requirements.

      The configuration is complete.

  5. Verify whether the user who is a member of the isv group can log in to Cloud Pak Platform with proper permissions. To verify, open the Cloud Pak Platform in your browser by using the URL of $CPHOST.