2.4 End-User Security Context

The end-user security context is the security boundary through which the database identifies an end user and determines what they can see and do. When an application executes a database operation, it passes a set of identity and authorization details (such as tokens and data roles) as the payload. The database uses this payload to establish the end-user security context, which governs the end user's access for the duration of the Oracle Deep Data Security (Deep Sec) session.

Traditionally, applications connect to databases using a highly privileged database user account. In contrast, the end-user security context constrains the privileges assigned to the database connection to strictly match those of the end user. Deep Sec enforces this by replacing the underlying database session's security domain (the database user and their roles) with the end-user security context.

Once this replacement occurs, the database authorizes all SQL queries from the application based solely on the end user, their roles, and their attributes, rather than the broad privileges of the application's database user account. Consequently, the database user account used by the application requires only basic privileges, such as CREATE SESSION and CREATE END USER SECURITY CONTEXT, effectively mitigating the risk of attacks like SQL injection.

Explore the following topics to learn more about the end-user security context.

See Also:

About the End-User Security Context in Chapter 15: Configure the Security Context.

2.4.1 Components of the Security Context

The end-user security context is an extensible, session-level object that functions as a security context scoped to an individual user for access control enforcement. It holds the active end user's identity, their enabled data roles, and all live attribute values.

The database creates an end-user security context automatically when an application sends an EndUserSecurityContext payload with the following components:

  • 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.

As discussed previously, for the application to obtain the end-user and database-access tokens, you must perform the required configurations in your IAM. During token issuance, IAM authenticates and authorizes both the end-user identity and the application's identity.

2.4.2 The Security Context Life Cycle

Learn how the end-user security context flows through a Deep Sec environment. Understand how your application builds the security context payload, propagates it to the database, and how the database establishes and manages that security context across SQL operations and connection reuse.

Security context population and transmission

The security context life cycle begins when the application initiates a database operation. During API calls, applications use an Oracle client driver to access data in the database. The Oracle client driver (such as JDBC, Python, or ODP.NET) allows application code to populate the end-user security context payload, which includes the end-user token (containing identity and roles) and application-specific attributes. Additionally, the application provides a database-access token. This token represents the application's authorization to access the database. For a complete list of end-user security context components, see Components of the Security Context.

Once populated, the client driver attaches this end-user security context payload, including the database-access token, to the database connection as metadata. This occurs before the request is sent to the database. The driver forwards this payload to the database with every subsequent SQL request.

Database validation and session attachment

When the database receives the security context payload, it validates the OAuth 2.0 tokens against three criteria:
  • Trust: The token must be signed by a trusted IAM provider.
  • Audience: The token's intended recipient must match the database's configured identity (set through the init.ora parameter).
  • Validity: Neither token can be expired. Both the end-user and database-access tokens have finite lifetimes, typically around one hour.

If validation succeeds and the tokens contain the required scopes, the database grants the application access, establishes the end-user security context on the session, and enables the required data roles in the security context. If the database detects an existing, identical end-user security context, it reuses it. Otherwise, it creates a new security context. All SQL operations in the session execute within the boundaries of this end-user security context (end user’s identity, roles, and attributes), ensuring strict policy enforcement throughout.

The Deep Sec security mechanism can't be bypassed, as establishing a valid session requires the application to present three elements simultaneously: a valid end-user token, a database-access token, and the database credentials for a connection that supports the end-user security context payload attachment.

Security context detachment and cleanup

The database automatically manages the detachment and reattachment of an end-user security context to a database session through the following mechanisms:
  • Connection release: When your application code releases the connection, the security context is detached from the database session.
  • Security context replacement: When your application reuses a connection, the database seamlessly replaces the previous security context with the new one. If the incoming request does not use an end-user security context, the server simply detaches the old one.
  • Garbage collection: The database automatically garbage-collects any end-user security contexts that remain inactive (not attached to any database session) after a timeout duration of one hour.

Driver support and configuration

Oracle client drivers, namely JDBC, Python, and ODP.NET drivers, support propagating the end-user security context payload to the database. You can implement this support in your Java, Python, or .NET applications using either of the two methods:
  • API extension methods
  • A configuration-driven Service Provider Interface (SPI)

For details, see Update Application Configuration with IAM Details.

2.4.3 End-User Contexts and Attributes

In Deep Sec, you use attributes associated with the active end user in data grant predicates to make authorization decisions at runtime. You can also use these attributes to drive application logic, simplify SQL queries, and avoid complex joins.

To support Deep Sec data grants, Oracle AI Database provides a flexible end-user context model that lets you define context attributes in the database, pass their runtime values in a JSON-formatted payload, and reference them by using JSON-style dot-path notation.

This model relies on two distinct but complementary objects: a database-side definition and its runtime counterpart.
  • End-user security context (runtime values within a database session): The session-level object the database creates automatically when an application sends an EndUserSecurityContext payload. It holds the active end user's identity, their enabled data roles, and all live attribute values. It is created, attached, and destroyed by the database server.
  • End-user context (database-side definition): A database schema object you create with the CREATE END USER CONTEXT command that defines a set of attributes, their data types, their default values, and optional PL/SQL routines to populate them. At runtime, the database uses this object as a template for JSON-style name-value pairs and instantiates it on first use in the current end-user security context — either when the application payload is attached or when an attribute is required for authorization checks.

Note:

If your data grant or application logic references custom context attributes, you must first create the corresponding end-user context definition in the database before those attributes are available within a runtime end-user security context. See End-user context definition.

Data grants in Deep Sec often reference multiple contexts, such as user, application, and system contexts. These contexts are composed of attribute-value pairs sourced from IAM systems, application logic, or the database itself.

Examples of context attributes include:

  • User attributes: username, employee_id, organization_id, customer_id
  • Environment attributes: NLS settings, device, location (IP address)
  • Application profile settings: default business unit, org hierarchy type, territory assignment type

End-user context definition

Before an application can pass custom attributes in the end-user security context payload at runtime, you must define the corresponding attributes and end-user contexts in the database. You can do this by creating an END USER CONTEXT object, which acts as a template that specifies allowed attributes, data types, and associated logic.

Oracle AI Database supports two types of end-user contexts: custom (user-defined) and default (system-defined).

  • Custom context
    • You can create your own end-user contexts using JSON schemas to store application-specific attributes. For example, a Human Capital Management (HCM) application might own an end-user context hr.hcm_context containing emp_id and org_id, while a Customer Relationship Management (CRM) application can own an end-user context ct.crm_context containing territory_id. This isolation prevents conflicts between different applications running on the same database.
    • At runtime, the application instantiates and initializes the required end-user context by passing the context and attributes through client drivers. Attribute values can be set directly in code or through event-handler functions that run on first read (lazy loading). Only authorized code can set or modify application-specific attributes.
  • Default context
    • The database provides two predefined, system-managed end-user contexts that are always available and do not require explicit instantiation. You cannot modify attributes in these contexts directly; they are initialized by the database server based on the user identity propagated from IAM.
    • USER.DEFAULT: Contains standard end-user identifiers and database session information (such as USERNAME, DB_NAME).
    • USER.TOKEN: Contains claims extracted directly from the end-user security context token. Only the following claims are available: iss [issuer], sub [subject], and aud [audience].

For further details, see Configure End-User Contexts and Attributes.

The ORA_END_USER_CONTEXT function

You can reference end-user context attributes using JSON-style dot-path notation with the SQL function, ORA_END_USER_CONTEXT. For example, you can reference a system attribute (the current end-user name) from the USER.DEFAULT context in a data grant as follows:
ORA_END_USER_CONTEXT.username
Similarly, if an HCM application instantiates an end-user context hr.hcm_context with an attribute org_id, the application code can refer to the org_id value as follows: 
ORA_END_USER_CONTEXT.hr.hcm_context.org_id

For the complete syntax details, see Read End-User Context Attributes.

2.4.4 Privilege Elevation

An application can dynamically enable additional data roles within an end-user security context to temporarily elevate privileges.

This allows the application to perform restricted database operations on behalf of users who are not directly authorized to perform them, without permanently granting those privileges to the users.

For example, a product marketing manager may need to view total sales for a product but must not have access to individual orders or customer data. The application temporarily elevates privileges in the end-user security context to run a sales-summary query, then reverts to the user's original access level, ensuring that the underlying granular data remains protected.

The following sections illustrate how you can implement privilege elevation for this example scenario.

Configure data roles and grants

To implement privilege elevation, you must first create a data role managed locally that contains the necessary privileges. You can configure these roles to be disabled by default, ensuring they are only active when explicitly required by the application.

Use the following command to create a data role as disabled specifically for viewing the sales summary:
CREATE OR REPLACE DATA ROLE summarize_sales_role DISABLED;

Next, define a data grant to assign specific permissions to the data role.

In this example, the oe.order_items table contains individual order line items, including product, quantity, and unit price. The sales-summary query aggregates this data without exposing individual order details.

The following command grants the data role permission to select from the oe.order_items table:
CREATE OR REPLACE DATA GRANT SummarizeSalesOrderItems
  AS SELECT
  ON oe.order_items
  TO summarize_sales_role;

Establish and authorize the application identity

To authorize the application, first create an application identity in the database that maps to the application's external client identifier (such as its client ID in Microsoft Entra ID). Then, grant the required data roles to that identity. The application can only enable data roles that have been explicitly granted to its identity.

Use the following command to create an application identity hcm_app, and map it to a specific client ID in Microsoft Entra ID:
CREATE OR REPLACE APPLICATION IDENTITY hcm_app
MAPPED TO 'AZURE_CLIENT_ID=f1fab37e-7aa2-4ff8-849c-7e731fea3b48';

Grant the previously created data role to the application identity, so the application can elevate privileges at runtime.

GRANT DATA ROLE summarize_sales_role TO hcm_app;

Runtime execution

At runtime, the application enables its assigned data roles through Oracle client-driver APIs, such as the JDBC API and the Python driver API. The application elevates privileges only for the duration of a specific query, establishing a confined security context for that execution.

This approach provides two key security benefits:

  • Confined context: Elevated privileges are scoped to a specific operation, limiting access even for SQL generated by AI agents.
  • Risk mitigation: Because elevated privileges are bound to the application's logic and are active only during execution, the risk of SQL injection attacks gaining unintended access is significantly reduced.

For an example of controlled privilege elevation, see Configure Oracle Deep Data Security for a Sample Application.