8.3 Configure Custom Claims for Group Information in OCI IAM

In OCI IAM, you must create a custom claim rule to populate a user's group memberships into a group claim in an access token. The Oracle AI Database reads this claim to activate the corresponding data roles.

The OCI Console does not provide a user interface for managing custom claims on tokens. You can create and manage custom claims only through the REST API. See Managing Custom Claims in the OCI IAM documentation.

To complete this task, you need the following:

• A user account with the Identity Domain Administrator role in the target identity domain.
• A command-line environment with curl installed, such as OCI Cloud Shell, a local terminal, or Windows Subsystem for Linux (WSL).

1. Obtain a personal access token with identity domain administrator privileges.
   You need an access token to authenticate the REST API call. OCI IAM allows identity domain administrators to generate a short-lived personal access token through the OCI Console.
   1. In the OCI Console, click your Profile icon (in the top-right corner of the Console header), then click your user name.
   2. Click the Tokens and keys tab.
   3. Under My access tokens, locate the row labeled Invokes identity domain APIs and click Download token.
   4. In the Generate personal access token dialog box:
      • From the Select app role drop-down menu, select Identity Domain Administrator.
      • Set the Token expires in mins field to a value appropriate for completing this task (for example, 5).
      • Click Download token.
   5. Open the downloaded token file and copy the token value. This is a time-limited bearer token that you use in the next step.
2. Run the custom claim REST API command.
   Run the following curl command, replacing <domain_url> with your identity domain URL (recorded in Register the Database in OCI IAM) and <access_token> with the personal access token you downloaded in step 1 above.

   curl -X POST https://<domain_url>/admin/v1/CustomClaims \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/scim+json" \
     -d '{
       "schemas": [
         "urn:ietf:params:scim:schemas:oracle:idcs:CustomClaim"
       ],
       "name": "group",
       "value": "$user.groups.*.display",
       "expression": true,
       "mode": "always",
       "tokenType": "AT",
       "allScopes": true
     }'
   

   The following list describes each parameter in the request body:

   • "name": The claim name to add to the access token. The database reads this specific claim.
   • "value": The dynamic expression that resolves to the display names of the user's groups.
   • "expression": The flag indicating if the value is a dynamic expression or a static string. Set to true to indicate a dynamic expression.
   • "mode": The inclusion mode. Set to always to include the claim in every access token.
   • "tokenType": The token type to which the claim is added. Set to AT to add the claim to access tokens only. Use BOTH to include identity tokens as well.
   • "allScopes": The scope filter. Set to true to include the claim regardless of the requested scope.
3. Verify the response.
   A successful request returns an HTTP 201 Created status code and a JSON response body. Verify that the response includes the following key fields:

   • "name": "group"
   • "value": "$user.groups.*.display"
   • An "id" field containing a unique identifier for the custom claim (for example, "60b9904b5895431e90f2b60a7edeb28e"). Record this identifier in case you need to modify or delete the claim later.

   If you receive an HTTP 401 Unauthorized error, verify that the personal access token has not expired and that you copied the full token value. If you receive an HTTP 403 Forbidden error, confirm that your user account has the Identity Domain Administrator role.

A custom claim rule is now active on the identity domain. From this point forward, every access token issued by this domain includes a group claim containing the display names of the authenticated user’s group memberships.