Application Registrations, Users, and Roles

Learn about the application registrations, user accounts, and role assignments required across both the IAM system and database to support Oracle Deep Data Security (Deep Sec). These configurations are fundamental to establishing identity, enforcing access policies, and securing the flow of data across your environment. This section begins with an overview of common data access patterns that guide these configuration choices.

Data Access Patterns

Explore the primary patterns in which IAM-managed end users and applications access the database using token-based authentication. Understanding these patterns helps you determine the application registrations, user accounts, and role mappings required to implement Deep Sec in your environment.

End Users Connect Directly to the Database

In this pattern, end users log on directly to the database using a SQL client, such as SQL*Plus. No application is involved.

Use case

This pattern supports simple development or testing environments, where users query the database directly.

Deep Sec graphic showing direct logon using IAM.

Database authentication flow

Prerequisite setup:

To enable Deep Sec for this pattern, you must complete the following configuration:

The runtime flow is as follows:

  1. User login: The end user (Marvin) logs in through a SQL client configured for token-based authentication (for example, SQL*Plus).

  2. Token retrieval: The client obtains an end-user token from IAM and passes it to the database. This token includes the following information:

    • End user (Marvin) as the subject

    • The database as the audience

    • Marvin’s assigned IAM roles (employee, manager)

  3. Security context establishment: The database validates the token, establishes an end-user security context, and activates the data roles corresponding to the end user’s IAM roles (that is, employee_role and manager_role data roles are activated).

    Marvin receives the privileges associated with these data roles. Unlike traditional database users, Marvin does not have a dedicated database user or schema. Marvin’s identity and privileges are provided dynamically at runtime in the end-user security context.

Note:

For OCI IAM, the end user’s client can supply an OCI IAM auth token instead of an OAuth 2.0 token as the end-user token. An OCI IAM auth token is a scoped proof-of-possession token issued by OCI IAM for database authentication. See Key Terminology. In this pattern, you do not register the database as an OAuth resource. Instead, the database acts as a resource principal in OCI IAM, and you govern access using OCI IAM policies and groups mapped to data roles.

In a variation of this pattern, an application or MCP server can connect to the database using an OCI IAM auth token scoped to the end user, and the database establishes the end-user security context directly from that token. For an example of this scenario, see Integrate with the Database Tools MCP Server.

Configuration path

For the complete configuration path of this pattern, see IAM-Managed Users Connecting Directly.

Applications Log On as Application Identities

In this pattern, an application or AI agent logs on directly to the database as an application identity, using a database-access token that it obtains from IAM. The database establishes an end-user security context for the application identity itself and enforces data authorization.

Use case

This pattern supports service applications, autonomous AI agents, and scheduled jobs that access protected data using their own application identity. Use this pattern when data access must be authorized for the application or AI agent itself, rather than for an end user acting through the application.

This image shows the application direct logon scenario.

Database authentication flow

Prerequisite setup:

To enable Deep Sec for this pattern, you must complete the following configuration:

The runtime flow is as follows:

  1. Application authentication: The application authenticates to IAM with its client credentials and obtains a database-access token. This token includes the following information:

    • The application’s client ID as the subject (sub claim)

    • The database as the audience (aud claim)

    • The application’s assigned IAM roles

  2. Direct logon: The application uses the database-access token to log on directly to the database. The database validates the token and looks for a global schema mapped to the token’s subject (the application’s client ID). If no mapped schema exists, the database resolves the subject to the mapped application identity (for example, hcm_app) and creates a lightweight session for it. Unlike a traditional database user, the application identity has no dedicated schema.

  3. Security context establishment: The database establishes an end-user security context for the session whose identity is the application identity. It activates the data roles granted directly to the application identity in the database, together with the data roles mapped to the application’s IAM roles. SQL executed on the connection is enforced according to those data roles, so the application retrieves only the data its application identity is authorized to access.

Note:

Configuration path

For the complete configuration path of this pattern, see IAM-Managed Applications Logging On as Application Identities.

Applications or AI Agents Access the Database on Behalf of End Users

In this pattern, an application (such as an analytics tool or MCP server) executes SQL against the database using the end user’s authorization. The application acts on behalf of the end user, exchanging the end user’s token for a database-scoped on-behalf-of (OBO) token from IAM (for example, Microsoft Entra ID).

Use case

This pattern is ideal for reporting tools and MCP servers. In these scenarios, the application does not possess its own data privileges; instead, it acts on behalf of the user to retrieve only the data that specific user is authorized to access.

Deep Sec graphic showing an on-behalf-of authentication flow.

Database authentication flow

Prerequisite setup:

To enable Deep Sec for this pattern, you must complete the following configuration:

The following flow illustrates the two-token form. The application can also attach an end-user security context payload containing only the OBO token. In that case, the database uses the OBO token for authentication and authorization. However, the application still requires the end-user token as the assertion to obtain the OBO token from IAM. See How the Database Server Manages an End-User Security Context for the payload-processing information.

  1. User login: The end user (Marvin) logs in to the application through IAM and receives a token scoped specifically to that application.

  2. Token exchange: The application presents the end-user token as an assertion, along with its own credentials, and receives an on-behalf-of (OBO) token for Marvin. This OBO token is the database-access token, and it has Marvin as the subject (sub claim).

  3. Security context payload propagation: The application uses this database-access token to connect to the database. In this two-token example, it also passes the end-user token for role resolution.

  4. Security context establishment: The database validates the tokens, establishes an end-user security context, and activates the data roles corresponding to the end user’s IAM roles (that is, the employee_role and manager_role data roles).

    Because Marvin is the subject in the database-access token, the application is essentially accessing the database as Marvin. The database activates the data roles according to the claims in the end-user token. The application itself does not define or control the roles; the user’s own IAM role assignments drive database access.

Note:

The application establishes the database connection (on which it attaches end-user security context payloads) in either of the two ways: by using a connection pool user account authenticated by a password, or by logging on directly as an application identity using a database-access token. The attachment of the end-user security context payload and its enforcement are identical in both cases.

Configuration path

For the full configuration path for IAM-managed users with application connections, see IAM-Managed Users Connecting Through an Application.

End Users Operate in the Context of an Application or AI Agent

In this pattern, data access is controlled by both end-user and application authorization. The application is registered as an OAuth application in IAM with its own roles, and end users are assigned those roles. As a result, an end user acquires the combined privileges of their own account and the application (or AI agent).

Use case

This is the most common pattern for enterprise and agentic AI applications. This approach is ideal when an AI agent or enterprise application must connect to the database securely, but restrict the data it retrieves based on the end user interacting with the application.

Deep Sec graphic showing the common pattern for enterprise and agentic AI applications.

Database authentication flow

Prerequisite setup:

To enable Deep Sec for this pattern, you must complete the following configuration:

The runtime flow is as follows:

  1. User login: The end user (Marvin) logs in to the application (HCM) through IAM and receives a token scoped specifically to that application. The token includes the roles assigned to the end user.

  2. Application authentication: The HCM application obtains its own database-access token, with the application as the subject (sub claim) and the database as the audience. For a configurable OAuth 2.0 provider as IAM, the application’s client identifier comes from the claim specified by application_id_claim and can differ from sub.

  3. Security context payload propagation: The application uses its own database-access token to authorize the connection. Additionally, the application forwards the end-user token as an attribute assertion for Marvin’s identity and roles.

  4. Security context establishment: The database validates the tokens, establishes an end-user security context, and activates the data roles corresponding to the end user’s IAM roles (that is, the employee_role and manager_role data roles).

    In this case, the application accesses the database as itself, and the database activates the data roles corresponding to the end user’s assigned application roles, which are present as claims in the end-user token.

Note: The application establishes the database connection (on which it attaches end-user security context payloads) in either of the two ways: by using a connection pool user account authenticated by a password, or by logging on directly as an application identity using a database-access token. The attachment of the end-user security context payload and its enforcement are identical in both cases.

Configuration path

For the full configuration path for IAM-managed users with application connections, see IAM-Managed Users Connecting Through an Application.

Application Registrations in IAM

When an end user interacts with a modern application, their request traverses two distinct trust boundaries: the application server that orchestrates business logic and the database that enforces data-level security.

Each of these components has a unique security posture and must be represented as a separate application registration in your IAM (for example, Microsoft Entra ID or OCI IAM).

The chain of trust

Because these components are registered independently, the authentication architecture of Oracle Deep Data Security (Deep Sec) relies on a transitive chain of trust, where each component delegates identity assertion to the next.

About scopes and delegation

A scope is a named permission that a resource server (such as the application or the database) exposes. When a client requests a token, it specifies which scopes it needs, and IAM evaluates whether the client is authorized to request those scopes.

In Deep Sec’s security architecture, scopes define what a component is authorized to do. For example, the database exposes a scope (such as sessions:scope:connect) that the application requests when acquiring a database-access token. In an OBO flow, the scope authorizes the application to connect to the database on behalf of the user. In a client credentials flow, the scope authorizes the application to connect to the database using its own identity. In both flows, the database uses the end-user token when supplied, or otherwise the database-access token, to establish the end-user security context. The database ensures that data access is governed by the identity and roles of the end user or application represented by the respective token, regardless of whether an OBO or client credentials flow was used.

For steps to configure application registrations in your IAM, see IAM, Database, and Application Configuration.

User and Role Management in IAM

You create and manage application users and roles in your IAM (for example, Microsoft Entra ID or OCI IAM). Subsequently, you create corresponding Deep Sec data roles in the database, and map the data roles to IAM roles for authorization.

This section explains how users and roles are structured in IAM and how they connect to database-level access control.

User registrations in IAM

Typically, you’ll manage user identities for your application centrally in an IAM system. Each application user requires a user account in your IAM. IAM assigns every user a unique principal identifier, such as a user principal name (UPN) in Microsoft Entra ID or a user name in OCI IAM. This identifier is the canonical representation of the user’s identity and is embedded in every token IAM issues for that user.

When the database receives a token, it extracts this principal identifier to establish the end-user security context for the session. The database does not store a separate local identity for externally managed users; instead, it relies entirely on the identity asserted in the token. This means that IAM remains the single source of truth for user lifecycle operations, such as provisioning, deprovisioning, and credential management.

Role definitions in IAM

Roles define what an authenticated user is authorized to do within the application and, by extension, within the database. The specific mechanism for defining roles differs between IAM providers, but the principle remains the same: roles appear as claims in the tokens issued to users, and the database maps those claims to its internal data roles.

Microsoft Entra ID: App roles

In Entra ID, you define app roles within each application registration. App roles are scoped to a specific application, meaning a role named employee on the HCM application registration is distinct from a role named employee on a different application registration. You assign app roles to users (or to other service principals) through the Entra ID portal or API. When Entra ID issues a token for that application, it includes the user’s assigned app roles in the token’s roles claim. This gives the database a reliable, application-specific set of role assertions for each user.

OCI IAM: Groups

In OCI IAM, groups serve as the role mechanism. You create groups that represent logical roles within your application, such as employee or manager, and assign users to them. When OCI IAM issues a token, it includes the user’s group memberships in the token’s claims (typically through a custom claim configuration or a default groups claim). The database reads these group claims and treats them as the equivalent of role assertions for authorization.

Keycloak: Realm roles

In Keycloak, you define realm roles, such as EMPLOYEE or MANAGER, and assign them to end users. Configure a protocol mapper to include these roles in a top-level array claim in the end-user access token. The database reads the claim specified by roles_claim and maps its values to data roles. See Configure Keycloak for Application-Mediated Access.

Application roles in Microsoft Entra ID, groups in OCI IAM, and realm roles in Keycloak serve the same purpose in this architecture; they provide the role claims that the database needs to determine which data roles to enable for an end-user security context.

Role mappings

The Deep Sec feature in Oracle AI Database supports data roles that can be mapped to external identity claims. When the database receives a token containing role or group claims, it matches those claims to pre-configured data roles. For each match, the database automatically enables the corresponding data role for that session, granting the user the associated fine-grained data authorizations.

Each data role has a one-to-one relationship with an external role claim. This means that any changes to a user’s role assignments in IAM (such as adding the user to a new app role in Entra ID, or changing the user’s group membership in OCI IAM) take effect automatically the next time that user’s token is presented to the database, without requiring any changes to the database configuration itself. For details on data roles, see User and Role Management in the Database.

For steps to configure application users and roles in your IAM, see IAM, Database, and Application Configuration.

User and Role Management in the Database

Deep Sec provides a specialized framework for administering application users and roles within the database, designed to meet the security requirements of modern applications.

Traditional database user accounts pose two significant problems for application-level access control: they own database schemas and objects, and they typically carry excessive privileges, especially when multiple application users share a single account.

The Deep Sec framework addresses these problems by introducing end users and data roles as distinct entities from traditional database users and roles. This separation enables you to enforce fine-grained data authorization without granting application users direct ownership of database objects.

You can manage application users and roles in two ways:

Topics:

Entity Types

Learn about the principal entities in Deep Sec and how they interact within the database environment.

End user

A user that an application defines. Unlike a traditional database user, an end user does not own database schemas or database objects. Instead, the Deep Sec framework grants end users access to specific rows and columns of tables (and views) through data grants, which are assigned to data roles that correspond to their application roles.

End users can create lightweight database sessions (end-user security contexts) through the application, rather than establishing full traditional database sessions.

Deep Sec recognizes the following two categories of end users:

Data role

A data role is defined in the database specifically for fine-grained data grants. The keyword DATA in SQL statements distinguishes these roles from standard database roles.

Deep Sec supports the following two categories of data roles.

Application identity

An identity that represents an application or AI agent within the database and maps to the application’s OAuth client identifier. An application identity does not own a database schema; the database derives its authorization from the data roles associated with it. An application identity serves two complementary roles:

You create an application identity with the CREATE APPLICATION IDENTITY statement, mapping it to the application’s OAuth client identifier.

The following example creates an application identity that maps to the application’s client identifier in Microsoft Entra ID:

CREATE APPLICATION IDENTITY hcm_app MAPPED TO 'AZURE_CLIENT_ID=f1fab37e-7aa2-4ff8-849c-7e731fea3b48';

The following example grants the data role hcm_role to the application identity hcm_app. The database then enables hcm_role in the security context of every end user who connects through the HCM application:

GRANT DATA ROLE hcm_role TO hcm_app;

You can grant only data roles that are managed locally to an application identity. The database enables externally mapped data roles based on the role information in the access token(s) used to establish the end-user security context: the end-user token when supplied, or from the database-access token. You cannot grant externally mapped data roles directly to an application identity.

For full configuration details, including the privileges an application identity requires to establish a connection or log on directly, see Configure Application Identities.

Summary of entity types

The following table summarizes the principal entity types in Deep Sec’s user and role administration framework.

Table 2-1 Entity types in Deep Sec

Entity Description
End user

A user of an application who does not own database schemas or database objects. An end user can be:

  • A user whose identity is managed in IAM. Typically, they connect to the database through the application. Can also log in directly using token-based authentication.
  • A user created and managed in the database using the CREATE END USER statement. Can log in directly using password authentication. Can be mapped by user name to users managed in the application's own user store, so that those users can connect through the application's trust, without requiring direct password authentication on the database server.

Data role

It can be one of the following types:

  • A data role that maps one-to-one to an application role in IAM. Enables fine-grained data authorization for external users.
  • A data role created and managed entirely within the database. You can grant it to local end users, application identities, other data roles (that are managed locally), or assign data grants to it.
Application identity A registered identity for an application. Enables data roles and common privileges for all users connecting through that application. In addition, an application identity can serve as a logon principal: an application or AI agent can log on as its application identity to establish the database connection on which it attaches end-user security context payloads, or to access data directly under its own authorization.

For more details on how to configure Deep Sec entity types, see User and Role Administration.

SQL Quick Reference

Use this quick reference to find basic SQL statements for managing users, roles, and application identities in Deep Sec.

Task SQL Statement
Create an end user in the database with password authentication CREATE END USER <name> [IDENTIFIED BY <password>];
Create a data role that is externally mapped (Microsoft Entra ID) CREATE DATA ROLE <name> MAPPED TO 'AZURE_ROLE=<role>';
Create a data role that is locally managed in the database CREATE DATA ROLE <name>;
Grant a data role (that is locally managed) to a local end user GRANT DATA ROLE <role> TO <user>;
Create an application identity CREATE APPLICATION IDENTITY <name> MAPPED TO '<mapping>';
Grant a data role (that is locally managed) to an application identity GRANT DATA ROLE <role> TO <app_identity>;

For detailed syntax and additional options, see User and Role Administration.