Understand Authentication Flow and Prerequisites

Review the authentication concepts and gather the necessary credentials before modifying your application configuration.

Authentication flow

For the application to successfully construct and propagate the end-user security context payload to the database, you must register your application as a confidential client in an IAM system. In the two-token flow, the application acquires and manages the following tokens to build the end-user security context payload:

• End-user token: An OAuth 2.0 access token generated when the end user logs in through the browser. This token establishes the user’s identity and role claims (app roles in Microsoft Entra ID or group memberships in OCI IAM).

• Database-access token: An OAuth 2.0 token the application obtains to authorize itself to access the database resource. This is acquired through the on-behalf-of (OBO) flow or the client credentials flow.

In this flow, the application includes both tokens in the end-user security context payload. The database-access token authorizes database access, and the end-user token supplies the end-user identity and role claims used to enforce data security.

The following table summarizes both the tokens, the claims they carry, and how these tokens are used in Oracle Deep Data Security (Deep Sec). For single-token flows, see About the End-User Security Context.

Token	Who gets it	Key claims	Who validates it	Used to
End-user token	End user, after authenticating with the IAM.	End-user identity: upn (Entra ID v1/v2), sub (OCI IAM), or the claim specified by username_claim (configurable OAuth 2.0) Unique user identifier: The claim specified by unique_id_claim, defaulting to sub (configurable OAuth 2.0) Application roles: roles (Entra ID v1/v2), group (OCI IAM), or the top-level array claim specified by roles_claim, defaulting to roles (configurable OAuth 2.0) Application/Client ID: appid (Entra ID v1) or azp (Entra ID v2), or client_id (OCI IAM)	Database, while establishing the end-user security context. The token signature is verified against the IAM’s public signing key.	Identify the end user (through ORA_END_USER_CONTEXT.username) and activate the data roles corresponding to the roles or group claim values. Additionally, application/client ID claims are used along with roles claim to map to application-specific data roles if such data roles are present.
Database-access token	Application, through OBO or client credentials grant.	Audience: aud (Entra ID v1/v2 and configurable OAuth 2.0), or resource_app_id and tenant_iss (OCI IAM) Application/Client ID: appid (Entra ID v1) or azp (Entra ID v2), client_id (OCI IAM), or the claim specified by application_id_claim (configurable OAuth 2.0)	Database, at connection time. The audience claim is matched against the database’s identity provider configuration.	Authorize the application's database connection, and identify the application's registered identity in the database so that its granted data roles can be enabled. The application/client ID claim must match the client ID specified in the database's CREATE APPLICATION IDENTITY DDL for that application.

For troubleshooting claim-related issues in tokens, see End-User Security Context Issues.

Required credentials

Before proceeding to configure your application, ensure you have gathered the following values from your application’s IAM registration:

• Client ID: The unique identifier assigned to your application.

• Client secret: The secret key generated for the application.

• Tenant ID (Entra ID) / Domain URL (OCI IAM) / Realm issuer URL (Keycloak): The identifier for your IAM instance.

• Database Scope: The scope required to access the database resource (for example, [DB_APP_ID_URI]/sessions:scope:connect in Entra ID or [primary_audience]DB_ACCESS_SCOPE in OCI IAM).