Understand Authentication Flow and Prerequisites

10.1 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. At runtime, the application must typically acquire and manage two distinct tokens to build the 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.

The application passes these tokens as part of the end-user security context payload on the database connection; the database-access token authorizes the connection, and the end-user token supplies the 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).

Token Who gets it Key claims Who validates it Used to

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) or `sub` (OCI IAM) Application roles: `roles` (Entra ID v1/v2) or `group` (OCI IAM) 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), or `resource_app_id` and `tenant_iss` (OCI IAM) Application/Client ID: `appid` (Entra ID v1) or `azp` (Entra ID v2) or `client_id` (OCI IAM)	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.

End-user token

End user, after authenticating with the IAM.

End-user identity: upn (Entra ID v1/v2) or sub (OCI IAM)

Application roles: roles (Entra ID v1/v2) or group (OCI IAM)

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), or resource_app_id and tenant_iss (OCI IAM)

Application/Client ID: appid (Entra ID v1) or azp (Entra ID v2) or client_id (OCI IAM)

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): 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).