Configuring single sign-on using OpenID Connect (OIDC)

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.

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

   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.

   Table 4. 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. Unreserved characters that are defined in RFC3986, including alphanumeric, hyphen (-), period (.), underscore (_), and tilde (~) characters, can be included in this parameter. For more information, see Unreserved Characters .

   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.
4. 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"
          }