End-User Security Context Issues

Troubleshoot issues with establishing end-user security contexts.

Topics:

• End-User Security Context Not Attached to Session

• Invalid Database-Access Token

• Data Role in the Database Is Not Mapped to IAM Application Role

• Data Role Granted to an Application Is Not Enabled

• ORA-00406 Error When Querying End-User Context

End-User Security Context Not Attached to Session

If the database session does not reflect the end user’s identity, the end-user security context may not have been established.

Issue description

The following query returns an empty JSON object ({}) instead of the expected end-user identity (the upn claim for Entra ID tokens, the sub claim for OCI IAM tokens, or the claim specified by username_claim for the configurable OAuth 2.0 provider):

SELECT ORA_END_USER_CONTEXT.username FROM dual;

Probable causes

• A valid end-user security context has not been established. The session operates under standard database privileges and bypasses Oracle Deep Data Security (Deep Sec) enforcement.

• For direct logon with external end users (OCI IAM or Microsoft Entra ID), the same end user is enabled for both Deep Sec direct logon and database global-user authentication. This happens when the user falls under a data-role mapping (the MAPPED TO clause of a data role) and also under a database global-user mapping (an IDENTIFIED GLOBALLY AS clause that resolves to a database schema). In this situation, global-user authentication takes precedence. The session connects as the database global user, runs with that schema’s privileges, and an end-user security context is not established.

Resolution procedures

1. Review the database and application configuration. See Configure the Database.

2. For IAM direct logon scenarios, check whether the affected end user is also mapped to a database global user through an IDENTIFIED GLOBALLY AS clause. If so, remove or alter that mapping so the end user is governed by Deep Sec alone, then start a new session and confirm that ORA_END_USER_CONTEXT.username returns the expected end-user identity.

3. If the issue persists, enable diagnostic tracing and examine the trace output. See Enable Diagnostic Tracing.

Invalid Database-Access Token

If the database rejects a database-access token during security context payload attachment, the token’s audience claim may not match the database’s identity provider configuration.

Issue description

When the application attempts to attach an end-user security context payload to the database session, the database raises the following error:

Invalid database-access token in the end-user security context: Failed to verify claims

Probable cause

The audience claim in the database-access token does not match the corresponding field in the database’s identity provider configuration.

Resolution procedure

1. Decode the database-access token (for example, using a JSON Web Token (JWT) decoder) and inspect the audience (aud) claim.

2. For Entra ID v1 tokens, verify that the token’s aud claim matches the application_id_uri field in the database’s IDENTITY_PROVIDER_CONFIG. For v2 tokens, verify that it matches the app_id field.

3. For OCI IAM identity domain tokens:

   • Confirm that a credential named OCI_IAM_DOMAIN_DB_CRED$ has been created using the DBMS_CREDENTIAL.CREATE_CREDENTIAL procedure.

   • Confirm that the app_id field in IDENTITY_PROVIDER_OAUTH_CONFIG matches the token’s resource_app_id claim.

   • Confirm that the domain_url in IDENTITY_PROVIDER_OAUTH_CONFIG matches the token’s tenant_iss claim.

4. For the configurable OAuth 2.0 provider, verify that the database-access token’s aud claim matches audience in IDENTITY_PROVIDER_CONFIG. If aud is an array, at least one value must match.

5. Correct any mismatched configuration values in the database’s identity provider settings, and retry the setEndUserSecurityContext call from the application.

Data Role in the Database Is Not Mapped to IAM Application Role

If an IAM application role present in the access token does not activate the expected data role in an end-user security context, the role mapping in the database may be missing or incorrectly formatted.

Issue description

The IAM access token contains a valid application role, but after the application calls setEndUserSecurityContext, the corresponding data role does not appear in the V$END_USER_DATA_ROLE view. Consequently, the end user does not have the expected data access privileges.

Probable cause

There is no data role in the database that is mapped to the application role in the IAM token.

Note: The database does not raise an error when a role mapping is missing. Instead, it silently ignores the unmapped role and logs a warning in the database trace file (if tracing is enabled).

Resolution procedure

1. Decode the access token to identify the exact application roles present in the token’s claims.

2. Query the DBA_DATA_ROLES view for the data role that was expected to be enabled, and check its MAPPED_TO value.

3. Depending on your token provider, ensure the MAPPED_TO string matches the correct format.

   • For Microsoft Entra ID tokens, the mapping must use one of the following formats:

     'AZURE_APP=<access_token_aud_claim>:AZURE_ROLE=<azure_role>'

     or

     'AZURE_ROLE=<azure_role>'

     Context: The database first checks for the AZURE_APP prefix. If it is not present, it defaults to checking AZURE_ROLE. The optional AZURE_APP prefix uses the token’s audience claim to distinguish between identically named application roles defined in different application registrations.

   • For Oracle Cloud Infrastructure (OCI) IAM tokens, the mapping must use the following format:

     'IAM_OAUTH_GROUP=<oci_iam_group_name>'

     Context: In an OCI IAM identity domain use case, an application identifier prefix is not needed because the group is shared across applications within the same domain, and the database can only configure a single domain.

   • For the configurable OAuth 2.0 provider, use ROLE=<realm_role_name>. Verify that the realm role appears in the top-level array claim specified by roles_claim in IDENTITY_PROVIDER_CONFIG. The default claim name is roles.

4. Alter the data role definition to correct any missing or mismatched MAPPED_TO values.

5. Establish a new session (or detach and re-attach the end-user security context) and query V$END_USER_DATA_ROLE to verify that the data role is now active.

Data Role Granted to an Application Is Not Enabled

If a data role granted to an application does not take effect after the end-user security context is established, the application identity mapping or the default enablement setting on the role grant may be incorrect.

Issue description

A data role granted to an application does not appear in the V$END_USER_DATA_ROLE view after the end-user security context is established. End users connecting through the application do not inherit the data role’s privileges.

Probable causes

• The application name in the database is mapped to an incorrect IAM client ID.

• The data role granted to the application is not configured to be enabled by default.

Resolution procedure

1. Decode the database-access token to locate the application identity claim. The specific claim depends on your token type:

   • Entra ID v1 tokens: Look for the appid claim.

   • Entra ID v2 tokens: Look for the azp claim.

   • OCI IAM client credentials tokens: Look for the client_id claim.

   • Configurable OAuth 2.0 provider: Look for the claim specified by application_id_claim in IDENTITY_PROVIDER_CONFIG.

2. Query the DBA_APPLICATION_IDENTITIES view to inspect the MAPPED_TO column for the row corresponding to your application.

3. Validate and correct the mapping format based on your token provider.

   • For Entra ID tokens (v1 and v2), verify the mapping matches the following format, where <ENTRA_ID_APP_ID> is the value of the appid or azp claim:

     'AZURE_CLIENT_ID=<ENTRA_ID_APP_ID>'
     Example: 'AZURE_CLIENT_ID=2edc9c9f-8e1e-4ade-8a4a-cc286ed1b899'

   • For OCI IAM tokens, verify the mapping matches the following format, where <OCI_IAM_CLIENT_ID> is the value of the client_id claim:

     'IAM_OAUTH_CLIENT_ID=<OCI_IAM_CLIENT_ID>'
     Example: 'IAM_OAUTH_CLIENT_ID=e83a43ac80d94637bb1958b06929ac32'

   • For the configurable OAuth 2.0 provider, verify that the mapping uses CLIENT_ID=<client_id>, where <client_id> is the application’s client identifier found in step 1.

     CLIENT_ID=ords_client

4. Alter the application identity definition to correct any misconfigurations in the MAPPED_TO value.

5. Verify the data role grant configuration. Ensure the data role granted to the application is enabled by default. If it is not enabled by default, you must either alter the role grant to enable it or explicitly pass it in the EndUserSecurityContext payload’s optional data roles list.

6. Establish a new session (or detach and re-attach the end-user security context) and query V$END_USER_DATA_ROLE to verify the data role is now enabled.

ORA-00406 Error When Querying End-User Context

If querying ORA_END_USER_CONTEXT raises a COMPATIBLE parameter error, the database instance may be running at a compatibility level that does not support this feature.

Issue description

After an end-user security context has been established, running the following query raises an error:

SQL> SELECT ORA_END_USER_CONTEXT.username FROM dual;
ERROR at line 1:
ORA-00406: COMPATIBLE parameter needs to be 20.0 or greater

Probable cause

The database instance’s COMPATIBLE initialization parameter is set to a value lower than 20.0.

Resolution procedure

1. Check the current value of the COMPATIBLE initialization parameter:

   SHOW PARAMETER compatible;

2. If the value is below 20.0, update the initialization parameter to 20.0 or higher. Consult the Oracle AI Database Upgrade Guide for the procedure to modify this parameter.