IBM Cloud Pak foundational services JIT support for SCIM OKTA and Azure Active Directory

You can configure just-in-time (JIT) with Security Assertion Markup Language (SAML) only for OKTA and Azure AD identity providers (IdPs). JIT supports both user and group attributes. You can also use System for Cross-domain Identity Management (SCIM) APIs with attribute mappings. You must correctly configure these attributes at the IdP and service provider (SP). For the attribute-mapping values for IdP and SP, see SAML attribute mappings of IdP and SP.

When you enable JIT, you can use SCIM operations to search users and groups after the user logs in at least once by using SAML IdP. You can then enable their access to the IBM Cloud Pak console.

To enable the access for users and groups before you enable JIT, see Granting access to capabilities within an IBM Cloud Pak.

Configure SAML at IdP and SP ends:

Configuring SAML at IdP end
Configuring SAML at SP end

Configuring SAML at IdP end

If you are using the OKTA template application to configure SAML, see Configure Cloud Pak as SAML SP at OKTA. You can provide the attribute mappings in the Attribute Statements (optional) section in the application.

Important: Even though the section name indicates (optional), you must provide at least one SAML attribute. Otherwise, the SAML configuration fails.

Configure the SAML IdP attributes such as Name, Name format, and Value at IdP.

Note: The SAML IdP attributes are the user-defined values. You can update these values based on your requirements.

The following table is an example for SAML IdP attributes:

Table 1. Example of SAML IdP attributes
Name	Name format	Value
uid	Basic	user.email
firstName	Basic	user.firstName
lastName	Basic	user.lastName
emailAddress	Basic	user.email
groups	Basic	Matches regex

Configuring SAML at SP end

To register OKTA as SAML IdP, you can either use the console or use the IdP V3 APIs. For more information, see Registering the SAML clients using IdP V3.

Note: It is not necessary to specify redirect_url for SAML with OKTA or Azure AD types when JIT is enabled.

IAM supports the following SAML SP attributes for user and group entities:

Table 2. IAM-supported SAML SP attributes
Name	Description
sub	Unique ID
given_name	First name of the user
family_name	Family name of the user
groups	Group name of the user
email	Email ID of the user

The values of the SAML SP attributes must be the same as the user-defined values for SAML IdP attributes.

The following table includes the mapping of the SAML attributes of IdP and SP:

Table 3. SAML attribute mappings of IdP and SP
SAML SP attribute	SAML IdP attribute	Description
sub	uid	Unique ID
given_name	firstName	First name of the user
family_name	lastName	Family name of the user
groups	groups	Group name of the user
email	emailAddress	Email ID of the user

Note: Table 3. SAML attribute mappings of IdP and SP includes the attribute mapping based on Example of SAML IdP attributes and IAM-supported SAML SP attributes tables.

See the following prerequisites:

Download the IdP metadata-xml file from the OKTA-SAML integration application. For more information, see IBM Cloud Pak SCIM Okta integration. You can save the file as idp-metadata-xml.xml.

Encode the IdP metadata-xml file content as base64. See the following example:

 cat idp-metadata-xml.xml | base64 --decode

Following is a sample payload of IdP V3 registration for OKTA with JIT enabled. The example payload is based on attributes from Example of SAML IdP attributes:

 {
     "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"
         },
         "idp_metadata": "base64 idp metadata"
     },
     "jit": true,
     "scim_config": {
       "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",
           "id": "displayName"
          }
        }
      }
    }

Ensure that the values of token_attribute_mappings such as sub, given_name, family_name, groups, and email are same as the SAML IdP attributes that are configured at Attribute Statements (optional) section in OKTA IdP.

Note: It is mandatory to specify the principalName for user and groups.
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 matching attributes that are configured at OKTA IdP.

If you do not specify the values for scim_config.scim_attribute_mappings, IAM defaults to the following SCIM attribute mappings for users and groups:
- SCIM attribute mappings for user:
```
{
   "id": "sub",
   "userName": "sub",
   "principalName": "sub",
   "displayName": "firstName",
   "emails": [
       {
       "value": "email",
       "type": "primary"
       }],
   "familyName": "lastName",
   "givenName": "firstName",
   "externalId": "sub"
}
```
- SCIM attribute mappings for groups:
```
{
   "id" : "_id",
   "displayName" : "_id",
   "groupName" : "_id",
   "principalName" : "_id",
}
```
  Restriction: Ensure that you manually remove the user or group from your IBM Cloud Pak when you remove the user or group from OKTA.