15.1 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 identity, data roles, and context attributes. Consequently, the database authorizes all executed SQL based on who the end user actually is, rather than the connection pool user account. This is conceptually similar to the security context switch that occurs when a definer's-rights PL/SQL procedure executes. As a result, 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:

  • End-user identity: The end user's name as asserted in the IAM access token. 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.

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 user context. When the database receives the payload, it validates the access 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. The attachment of the end-user security context payload and its enforcement are identical in both cases. See Set Up IAM Integration for Application-Mediated Connections.

The direct logon option

While the application architecture described above is the most common use case, 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 Connect Directly to the Database.

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.