About Default and Custom Contexts

15.1 About Default and Custom Contexts

Discover how the database uses both default and custom end-user contexts to manage session attributes and enforce fine-grained access control for applications.

Context attributes extend the end-user security context beyond identity and roles. They are JSON name-value pairs organized by named namespaces that an application can use in data grant predicates, SQL queries, and application logic. The application passes these context attributes to the database as part of the EndUserSecurityContext payload.

Requirement for a context definition in the database

Before an application can pass context attributes at runtime, you must create a corresponding END USER CONTEXT schema object in the database using the CREATE END USER CONTEXT command. This definition specifies the end-user context name, its allowed attributes, their data types, and optional PL/SQL handler logic.

If the application sends a context attribute that does not have a corresponding end-user context definition, the attribute is ignored. Data grant predicates that reference the attribute through the ORA_END_USER_CONTEXT function do not receive its value.

Oracle AI Database supports two categories of end-user contexts:

15.1.1 Default (System-Defined) Contexts

Two predefined, system-managed end-user contexts are always available in every end-user security context and do not require explicit instantiation. You cannot modify attributes in these end-user contexts directly; they are initialized by the database server based on the user identity propagated from IAM.

USER.DEFAULT: Contains system attributes that identify the end user, such as USERNAME, LOGON_END_USER, and CURRENT_END_USER. It also includes all predefined database session attributes from the SYS_CONTEXT namespace USERENV, such as AUTHENTICATED_IDENTITY and DB_NAME. For ease of use, USER.DEFAULT attributes are elevated to the top level of the ORA_END_USER_CONTEXT namespace, so you can reference them directly without specifying USER.DEFAULT in the path. For example, ORA_END_USER_CONTEXT.username returns the end user's name.
USER.TOKEN: Contains claims extracted directly from the end user's OAuth 2.0 access token. Only the following claims are available: iss [issuer], sub [subject], and aud [audience]. You must prefix these attributes with the full path in the function, for example, ORA_END_USER_CONTEXT.USER.TOKEN.iss.
To view the full end-user token content, query ORA_END_USER_CONTEXT.USER.TOKEN directly. The following examples show the end-user token output for supported identity providers:
- Microsoft Entra ID:
```
SELECT ORA_END_USER_CONTEXT.USER.TOKEN FROM DUAL;

TOKEN
--------------------------------------------------------------------------------
{"iss":"https://sts.windows.net/443e3044-e82d-410a-8b0a-57498722241d/",
 "sub":"tgc1Nc73wj6E6xKO0r1wMFN95PyNB_nnfCwj9URUxx0",
 "aud":"https://supremo.onmicrosoft.com/2edc9c9f-8e1e-4ade-8a4a-cc286ed1b899"}
```
- OCI IAM:
```
SELECT ORA_END_USER_CONTEXT.USER.TOKEN FROM DUAL;

TOKEN
--------------------------------------------------------------------------------
{"iss":"https://identity.oraclecloud.com/",
 "sub":"deep_sec_employee",
 "aud":"OracleDB"}
```

15.1.2 Custom (User-Defined) Contexts

In addition to system contexts, you can create your own end-user contexts using JSON schema definitions.

Custom contexts allow different applications to define and manage their own attributes without conflict. For example:

An HCM application may define an end-user context hr.hcm_context containing attributes emp_id and org_id.
A CRM application may define an end-user context ct.crm_context containing attributes territory_id and customer_id.

You can configure each attribute in a custom context with either a static default value or a lazy-loading event handler (PL/SQL callback), which is invoked the first time the attribute is read. You must create custom contexts in the database before you can use them at runtime. Instantiation occurs automatically on first reference and does not require an explicit command.

Size limits

When defining custom contexts and attributes, ensure you stay within the following system limits:

Maximum context name length: 128 characters
Maximum attribute name length: 128 characters
Maximum JSON schema payload length in the CREATE END USER CONTEXT command: 4,000 characters