Configuring single sign-on using OpenID Connect (OIDC)

This version of documentation is no longer updated. For the latest information, see the following links:
- Continuous Delivery (CD) documentation
- Support Cycle-2 (SC-2) documentation

Using OIDC, you can configure single sign-on (SSO) between your product and supported providers.

You can configure SCIM API for Users and Groups after you successfully authenticate with OIDC when just-in-time (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:

• Verify the identity of the users.
• Get the basic profile information about the users.

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

• You can configure SSO with OIDC support by using the identity provider (IdP) V3 APIs. For more information, see IdP V3 APIs.

• Currently, OIDC is the only supported protocol with the IdP V3 version.

• To verify whether you have OIDC support or not, see Getting the list of registered OIDC clients by query.

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.

Procedure

Complete the following steps to configure SSO with OIDC:

• Configuring OIDC at IdP end
• Configuring OIDC at RP end

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 grant access to capabilities within an IBM Cloud Pak. 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

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

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

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

Note: You can add more attributes to token_attribute_mappings. These values are later available as more claims in jwt idToken. The names of the attributes can consist of alphanumerics. Special characters or spaces are not allowed. For example, "additionalAttribute" : "attribute_value". When JIT is enabled, the additional token claims are available for the SCIM user API for all types of OIDC and SAML with okta and azuread type.

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

1. Click Create.

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

Note: You can add more attributes to token_attribute_mappings. These values are later available as more claims in jwt idToken. The names of the attributes can consist of alphanumerics. Special characters or spaces are not allowed. For example, "additionalAttribute" : "attribute_value".

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 access to capabilities within an IBM Cloud Pak

For more information, see Granting access to capabilities within an IBM Cloud Pak.

Configuring OIDC with a SCIM server dependency

From IBM Cloud Pak® foundational services v4.12, you can configure OIDC with the SCIM server backend so that users and groups of the SCIM registry can log in with OIDC authentication. When you create a new OIDC connection with UI, enable the This is a SCIM compliant identity provider option.

Prerequisites

• The backend SCIM server must support OIDC authentication with the client_credentials grantType.
• For the SCIM server configuration, the Scim base path, Token URL, Client ID, and Client Secret values are mandatory.

Procedure

Choose one of the following methods to configure OIDC with a SCIM server dependency:

• For more information about the API, see Configuring OIDC with SCIM server dependency.
• Configure OIDC with a SCIM server dependency by using the console. For more information, see the following section.

Configuring OIDC with a SCIM server dependency by using the console

1. Log on to the cp-console as an administrator. To get the cp-console URL, username, and 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 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. Enable the This is a SCIM compliant identity provider toggle option.
4. Enter the required values for the parameters in the Connection details, Token attribute mapping, and Site settings sections.

Note: You can add additional attributes to token_attribute_mappings. These values are later available as additional claims in jwt idToken. The names of the attributes can consist of alphanumerics. Special characters or spaces are not allowed. For example, "additionalAttribute" : "attribute_value".

Note: JIT is enabled by default when you configure OIDC by using the console. If you enable the Use With SCIM compliant identity provider toggle option, the JIT is disabled.

1. Click Create.
2. The SCIM configuration tab is enabled when you choose to configure OIDC with the SCIM compliant identity provider dependency. Fill the following fields in the SCIM configuration tab:
   • For Scim base path, enter the path where Identity Management (IM) calls the SCIM resources, such as https://bedrock-iam.verify.ibm.com/v2.0/.
   • For Grant type, enter client_credentials. The default supported value is grantType.
   • The Token URL is the OIDC token URL that IM uses to get the accessToken, such as https://bedrock-iam.verify.ibm.com/v1.0/endpoint/default/token.
   • For Client ID, enter the client ID for the backend OIDC SCIM server.
   • For Client secret, enter the client secret for the backend OIDC SCIM server.

3. Configure SCIM attribute mapping for the User attribute and Group attribute resources. By default, these fields are predefined with the principalName attribute. Modify the values based on the SCIM IdP configuration.

   Note: SCIM attribute mapping is customizable. Other than the standard string attributes, it supports complex attributes as the mapping value that uses the name.givenName dot notation. It also supports multivalued attributes as the mapping value that uses the emails.value dot notation where the primary value is returned if present. Otherwise, the first value is returned.