About the End-User Security Context

In a typical scenario, the application connects to the database using a shared, highly privileged database user account (the connection pool user account). All queries run under this account’s identity, regardless of which end user is actually making the request.

This broad-access model creates a significant security risk; for example, a SQL injection attack or a compromised AI-generated query can run with the same elevated privileges as the application itself.

The end-user security context solves this problem. When active, it replaces the database session’s broad security domain (the connection pool user account and its roles) with the end user’s or application’s identity, data roles, and context attributes. Consequently, the database authorizes all executed SQL based on which end user or application is making the request, rather than the connection pool user account. This replacement is conceptually similar to the security context switch that occurs when a definer’s-rights PL/SQL procedure executes. Under this security model, the application’s database user account requires only basic privileges, such as CREATE SESSION and CREATE END USER SECURITY CONTEXT, effectively mitigating the risk of attacks like SQL injection.

How the security context is established

When the application initiates a database operation, the Oracle client driver (JDBC, Python, or ODP.NET) invokes a callback, enabling the application code to populate an EndUserSecurityContext object. Through this object, the application provides the following details to the database:

• Identity information: For IAM-managed identities, this is the identity from the end-user token when it is supplied, or from the database-access token when the separate end-user token is omitted. For end users managed locally, this is the name of the end user created in the database.

• Data roles (optional): Additional data roles that the application can enable for the end-user security context, beyond those mapped to application roles in IAM and those enabled by default for the application identity.

• End-user context attributes (optional): A dictionary of application-defined key-value pairs to include in the security context. Used when data grants or application logic rely on custom end-user context attributes.

• Database-access token: An on-behalf-of (OBO) token or an OAuth client-credential token that the application obtains from IAM to authorize its access to the database. This token ensures the database accepts requests only from trusted applications. Only an authorized application (with its application secret) can obtain this token from IAM. When the separate end-user token is omitted, the database also uses the database-access token for authentication and authorization.

Single-token payloads use the following token variants:

• Microsoft Entra ID v1 and v2 client-credentials database-access tokens and OBO database-access tokens. A client-credentials database-access token identifies an application or service. An OBO database-access token identifies the end user and the application. The OBO flow still requires an end-user token to obtain the database-access token; only its inclusion in the payload is optional.
• OCI IAM database-access tokens for the default and Oracle Deep Data Security (Deep Sec) domains.
• OCI IAM auth tokens obtained using user credentials, service tokens, or resource-principal credentials.

For the single-token JDBC example, see Use the API Extension Methods.

Once populated, the client driver attaches the EndUserSecurityContext object to the database connection as metadata before sending the request to the database. The driver then forwards this metadata with every subsequent SQL request, ensuring that long-running connection-pool connections always operate under the correct, current security context. When the database receives the payload, it validates the supplied access token or tokens and establishes the end-user security context. The database creates, attaches, and destroys security contexts automatically; no custom session-management code is required in the application.

Note: The application can establish the database connection on which it attaches end-user security context payloads in either of 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, including for an application identity–based connection pool. For application-only access, a client-credentials database-access token can establish the connection and also be supplied in the payload. For an OBO request, the connection can use a client-credentials database-access token, while the payload contains an OBO database-access token.

The attachment of the end-user security context payload and its enforcement are identical whether the database connection is established using a password-authenticated connection pool user account or an application identity. The application identified by the payload’s database-access token can differ from the application that established the connection. See Set Up IAM Integration for Application-Mediated Connections.

The direct logon option

Oracle AI Database also supports a direct logon option, in which the connecting principal establishes the session directly and the database natively establishes the end-user security context from the login. The connecting principal can be an end user or an application:

• IAM-managed users: An end user (such as a data analyst or developer) connects with a SQL client and provides their IAM access token (either OAuth 2.0 token, or OCI IAM auth token). The database extracts the end user’s identity and roles from the token and establishes the end-user security context for that user.

• Locally managed users: An end user connects using local end-user credentials (end-user name and password), along with a second authentication factor, if configured. The database resolves the end user’s identity and roles locally.

• IAM-managed applications and AI agents: An application or AI agent connects directly as its own application identity, using a database-access token it obtains from IAM with its client credentials. The database establishes an end-user security context whose identity is the application identity itself, and authorizes access by the application identity’s data roles. See Applications Log On as Application Identities.

  As discussed in the previous section, an IAM-managed application can also access data as itself by attaching an end-user security context payload containing only its client-credentials database-access token to the database connection.

Note:

• End-user security context creation fails if the security context name passed to the setEndUserSecurityContext API contains non-ASCII characters.

• A session running with an end-user security context cannot use a private database link directly. Any statement that references the link fails with ORA-02019: connection description for remote database not found, even though the same link works before the security context is attached. A Deep Sec end user's access comes only through data roles, and a private link cannot be granted to a data role, so the security context has no path to the link. However, public database links resolve and execute normally.

  To use a private link with a Deep Sec end user, wrap it in a definer's-rights PL/SQL procedure owned by the link's schema, and grant EXECUTE on that procedure to the end user through a data role. The end user calls the procedure instead of referencing the link directly.