14.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-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.
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. If your users (such as data analysts or developers) need to connect directly to the database using a SQL client, they can bypass the application entirely.
- IAM-managed users: They provide their IAM access token during authentication. The database automatically extracts their identity and roles from the token.
- Locally managed users: They connect using the local end-user credentials (end-user name and password), and the database resolves their identity and roles locally.
In either direct setup, no application or its database-access token is involved. The database natively establishes the correct end-user security context from the user's login.
Note:
End-user security context creation fails if the security context name passed to thesetEndUserSecurityContext API contains non-ASCII
characters.