Validate the Microsoft Entra ID Configuration

Before you configure the database, confirm that the application registrations, scopes, client secret, and user and role assignments configured in Microsoft Entra ID are working as expected.

The following procedure validates a two-token configuration by obtaining both tokens from Microsoft Entra ID 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 with Proof Key for Code Exchange (PKCE).

To complete this task, you need the following:

• Command-line environment with curl and openssl installed.

• Application (client) ID, application ID URI, redirect URI, and the client secret value of HCM APP. See Register the Application in Microsoft Entra ID.

• Application ID URI of OracleDB_Resource, and directory (tenant) ID. See Register the Database in Microsoft Entra ID.

• User principal name (UPN) and password of a test user assigned at least one application role. See Create Users and Assign Roles in Microsoft Entra ID.

• JWT debugger, such as a command-line JWT decoder or a trusted web-based debugger, for inspecting token claims.

1. Set up environment variables.

   Create a .env file in your working directory with the following contents. Subsequent steps source variables from this file:

   # Application client ID and secret
   APPLICATION_CLIENT_ID='<application_client_id>'
   APPLICATION_CLIENT_SECRET='<application_client_secret>'
   
   # OAuth 2.0 endpoints
   TOKEN_URI='<token_uri>'
   AUTH_URI='<auth_uri>'
   
   # Scope for database-access token (client credentials flow)
   DB_SCOPE='<db_scope>'
   
   # Scope for end-user token (authorization code flow with PKCE)
   APPLICATION_SCOPE='<application_scope>'
   
   # PKCE values - populated by generate_pkce.sh in step 3.a
   CODE_VERIFIER=''
   CODE_CHALLENGE=''
   
   # Redirect URI registered for HCM APP
   REDIRECT_URI='<redirect_uri>'

   The following list describes each placeholder:

   • <application_client_id>: Application (client) ID of HCM APP.

   • <application_client_secret>: Client secret value of HCM APP.

   • <token_uri>: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token, where <tenant_id> is the directory (tenant) ID.

   • <auth_uri>: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize, with the same <tenant_id> as above.

   • <db_scope>: Application ID URI of OracleDB_Resource, followed by /.default. For example, https://supremo.onmicrosoft.com/fe58fefb-0925-4c8f-9b14-598a0d2f4552/.default.

   • <application_scope>: Application ID URI of HCM APP, followed by /user_access. For example, api://<hcm_app_client_id>/user_access.

   • <redirect_uri>: Redirect URI registered for HCM APP. For example, http://localhost:3000.

   • CODE_VERIFIER and CODE_CHALLENGE: Leave empty. The script in step 3.a populates these.

   Source the .env file into your shell to make the variables available:

   set -a && source .env && set +a

2. Request a database-access token through the client credentials grant.

   Run the following command:

   curl -s -X POST "$TOKEN_URI" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "grant_type=client_credentials" \
     --data-urlencode "client_id=$APPLICATION_CLIENT_ID" \
     --data-urlencode "client_secret=$APPLICATION_CLIENT_SECRET" \
     --data-urlencode "scope=$DB_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 (this section assumes v1 tokens, according to the configuration in Register the Database in Microsoft Entra ID):

   • aud: Matches the application ID URI of OracleDB_Resource.

   • appid: Matches the application (client) ID of HCM APP.

   • iss: The Entra ID issuer URL for your tenant (for example, for v1 tokens: https://sts.windows.net/<tenant_id>/).

   If the request returns HTTP 401 with AADSTS7000215 or a similar invalid client secret error, verify the HCM APP client secret value and its expiration date.

3. Request an end-user token through the authorization code grant with PKCE.

   1. Generate a PKCE verifier and challenge.

      Create the helper script generate_pkce.sh:

      cat > generate_pkce.sh << 'EOF'
      #!/bin/bash
      CODE_VERIFIER=$(openssl rand -base64 64 | tr -d '=+/' | tr -d '\n' | cut -c1-64)
      CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')
      
      # Update .env file in place
      sed -i "s|CODE_VERIFIER=.*|CODE_VERIFIER='$CODE_VERIFIER'|" .env
      sed -i "s|CODE_CHALLENGE=.*|CODE_CHALLENGE='$CODE_CHALLENGE'|" .env
      
      echo "Generated and updated .env:"
      echo "CODE_VERIFIER=$CODE_VERIFIER"
      echo "CODE_CHALLENGE=$CODE_CHALLENGE"
      EOF
      chmod +x generate_pkce.sh

      Run the script and reload the .env file to pick up the generated values:

      ./generate_pkce.sh
      set -a && source .env && set +a

   2. Construct the authorization URL and sign in.

      Use the following command to build the authorization URL and print it to the console:

      AUTH_URL="${AUTH_URI}?client_id=${APPLICATION_CLIENT_ID}"
      AUTH_URL+="&response_type=code&redirect_uri=${REDIRECT_URI}"
      AUTH_URL+="&scope=${APPLICATION_SCOPE}"
      AUTH_URL+="&response_mode=query&prompt=consent"
      AUTH_URL+="&code_challenge=${CODE_CHALLENGE}&code_challenge_method=S256"
      
      echo -e "\nOpen this URL in your browser:\n$AUTH_URL\n"

      Copy the printed URL into a web browser and sign in as the test user. After successful authentication, the browser redirects to the redirect URI with an authorization code, appended as a query parameter. The redirect page typically fails to load; this is expected.

      From the browser’s address bar, copy the authorization code value (everything after code= and before the next &, if any).

   3. Exchange the authorization code for the end-user token.

      Run the following command, replacing <AUTH_CODE_FROM_REDIRECT> with the authorization code copied in the previous step:

      curl -s -X POST "$TOKEN_URI" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        --data-urlencode "grant_type=authorization_code" \
        --data-urlencode "client_id=$APPLICATION_CLIENT_ID" \
        --data-urlencode "client_secret=$APPLICATION_CLIENT_SECRET" \
        --data-urlencode "code=<AUTH_CODE_FROM_REDIRECT>" \
        --data-urlencode "redirect_uri=$REDIRECT_URI" \
        --data-urlencode "code_verifier=$CODE_VERIFIER" \
        --data-urlencode "scope=$APPLICATION_SCOPE"

      After you obtain the end-user token, decode it and verify the following claims in its payload:

      • aud: Matches the application ID URI of HCM APP (for example, api://<hcm_app_client_id>).

      • upn: Matches the user principal name of the test user (for example, marvin@<your-directory>.onmicrosoft.com).

      • roles: An array containing the application role values assigned to the test user (for example, ["MANAGER"]).

      If the roles claim is missing from the token, verify that the test user is assigned to HCM APP with at least one application role. See Create Users and Assign Roles in Microsoft Entra ID. If the roles claim is present but does not include the expected role values, verify the role definitions and confirm that the Value field of each role contains the required value. See Register the Application in Microsoft Entra ID.

Note: If your configuration uses v2 tokens, see Enabling Microsoft Entra ID v2 Access Tokens in Oracle AI Database Security Guide.

Successful completion of both token requests confirms that Entra ID is configured correctly for Oracle Deep Data Security. The roles 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.