8.5 Validate the OCI IAM Configuration

Before you configure the database, confirm that the application registrations, scopes, custom claim rule, and user assignments you configured in OCI IAM are working as expected.

Validation consists of obtaining two tokens from OCI IAM and inspecting their claims:

• Database-access token: Issued to the application through the client credentials grant.
• End-user token: Issued to the test user through the authorization code grant.

To complete this task, you need the following:

• Command-line environment with curl installed.
• Client ID and client secret for the database registration, identity domain URL, and database-access scope. See Register the Database in OCI IAM.
• Client ID and client secret for the application, application scope, and redirect URL. See Register the Application in OCI IAM.
• User name and password of a test user assigned to at least one group. See Create Users and Assign Groups in OCI IAM.
• JWT debugger, such as a command-line JWT decoder or a trusted web-based debugger, for inspecting token claims.

1. Request a database-access token through the client credentials grant.
   Run the following command, substituting values as described below:

   curl -i \
     -H "Authorization: Basic <encoded_app_credentials>" \
     -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
     --request POST https://<domain_url>/oauth2/v1/token \
     -d "grant_type=client_credentials&scope=<database_scope>"
   

   The following list describes each placeholder:

   • <encoded_app_credentials>: Base64 encoding of the application's client ID and client secret joined by a colon (CLIENT_ID:CLIENT_SECRET). On Linux or macOS, generate the value as follows:

     echo -n "<CLIENT_ID>:<CLIENT_SECRET>" | base64

   • <domain_url>: Identity domain URL. For example, idcs-<unique_id>.identity.oraclecloud.com:443.
   • <database_scope>: Database application registration's primary audience concatenated with its scope name. For example, if the primary audience is OracleDB and the scope is DB_ACCESS_SCOPE, use OracleDBDB_ACCESS_SCOPE.
   A successful response returns HTTP 200 with a JSON body containing an access_token field. Decode the token and verify the following claims in its payload:

   • aud: Matches the database application's primary audience (for example, OracleDB).
   • scope: Contains the database access scope (for example, OracleDBDB_ACCESS_SCOPE).
   • sub or client_id: Matches the client ID of the application.

   If the request returns HTTP 401, verify the application's client ID and secret. If the request returns HTTP 400 with invalid_scope, verify that you added the database scope to the application's Resources section. See Register the Application in OCI IAM.

2. Request an end-user token through the authorization code grant.
   1. Obtain an authorization code.
      Paste the following URL into a browser and sign in as the test user:

      https://<domain_url>/oauth2/v1/authorize?client_id=<app_client_id>&response_type=code&redirect_uri=<url_encoded_redirect_url>&scope=<application_scope>

      The following list describes each placeholder:

      • <domain_url>: Same identity domain URL used in the database-access token request.
      • <app_client_id>: Client ID of the application.
      • <url_encoded_redirect_url>: URL-encoded form of the registered redirect URL. For example, https://hcm.example.com/oauth2/callback becomes https%3A%2F%2Fhcm.example.com%2Foauth2%2Fcallback.
      • <application_scope>: Application's scope (primary audience concatenated with scope name). For example, OracleConfidentialClientAPP_ACCESS_SCOPE.
      After sign-in, the browser redirects to the registered redirect URL, with an authorization code appended as a query parameter (for example, ?code=<authorization_code>). Copy the authorization code value.
   2. Exchange the authorization code for an end-user token.
      Run the following command:

      curl -i \
        -H "Authorization: Basic <encoded_app_credentials>" \
        -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
        --request POST https://<domain_url>/oauth2/v1/token \
        -d "grant_type=authorization_code&code=<authorization_code>"
      

      The following list describes each placeholder:

      • <encoded_app_credentials>: Same Base64-encoded credentials used in the database-access token request.
      • <domain_url>: Same identity domain URL used in the database-access token request.
      • <authorization_code>: Authorization code from the redirect URL in the previous task.
      A successful response returns HTTP 200 with a JSON body containing an access_token. Decode the token and verify the following claims in its payload:

      • aud: Matches the application's primary audience (for example, OracleConfidentialClient).
      • scope: Contains the application scope (for example, OracleConfidentialClientAPP_ACCESS_SCOPE).
      • group: Contains the display names of the groups the test user is assigned.
      The token also includes subject and user identity claims (for example, sub and user.name) that identify the test user.
      If the group claim is missing from the token, revisit Configure Custom Claims for Group Information in OCI IAM and confirm that the REST API call returned HTTP 201 and that the custom claim's name field is group. If the group claim is present but does not list the expected groups, verify the test user's group memberships and whether the test user is assigned to the application. See Create Users and Assign Groups in OCI IAM.

Alternative: Obtain an end-user token using the Resource Owner Password Credentials grant

For non-production validation, you can skip the browser sign-in by requesting an end-user token through the Resource Owner Password Credentials (ROPC) grant. This approach is suitable only for automated testing in non-production environments.

To use the ROPC grant, first select the Resource owner grant type on the application registration in Register the Application in OCI IAM, then run:

curl -i \
  -H "Authorization: Basic <encoded_app_credentials>" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --request POST https://<domain_url>/oauth2/v1/token \
  -d "grant_type=password&username=<username>&password=<password>&scope=<application_scope>"

The following list describes each placeholder:

• <encoded_app_credentials>: Same Base64-encoded credentials used in the database-access token request.
• <domain_url>: Same identity domain URL used in the database-access token request.
• <username> and <password>: Credentials of the test user created in Create Users and Assign Groups in OCI IAM.
• <application_scope>: Same application scope used in the authorization code request.

Decode the returned token and verify the same claims as in the authorization code grant.

Successful completion of both token requests confirms that OCI IAM is configured correctly for Oracle Deep Data Security. The group claim verified in the end-user token is what Oracle AI Database reads at runtime to activate the corresponding data roles.

You can now proceed to configure Oracle AI Database to accept and validate these tokens.