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:

• Default (System-Defined) Contexts

• Custom (User-Defined) Contexts

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; the database initializes them 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.

  Here are some key attributes you can reference directly:

  Attribute	Description
  ORA_END_USER_CONTEXT.username	The end user’s name in the security context.
  ORA_END_USER_CONTEXT.logon_end_user	The end user’s name at logon. If the end user is a proxy user, this value is different from the user name at runtime.
  ORA_END_USER_CONTEXT.current_end_user	The name of the end user whose privileges are currently active.
  ORA_END_USER_CONTEXT.authenticated_identity	The authenticated user for the underlying database connection.

• USER.TOKEN: Contains all the claims and attributes extracted directly from the end user’s OAuth 2.0 access token, or from the database-access token when the separate end-user token is omitted. You must prefix these attributes with the full path in the function, for example, ORA_END_USER_CONTEXT.USER.TOKEN.iss.

  To view the token claims, 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
    --------------------------------------------------------------------------------
    {
      "xms_ftd": "vBQfZ5-MpAigFH_Fll9VJTJiEjW9zGownSiQqe1ZuBCeYO4aZXN0NC1kc21z",
      "sub": "rHd7Mq42xk8D5yJL1sVN63Qw92PyKC_mfA6UZj0RbXE",
      "appid": "8f3d624a-5b19-4e76-9c82-2d7a0f6b135e",
      "exp": 1791596038,
      "tid": "7c9e2a41-6b35-4d80-a192-5f3e8c0b764d",
      "scp": "sessions:scope:read",
      "ver": "1.0",
      "sid": "b2f76419-8e30-4a65-9d17-6c0e3f825ab4",
      "iat": 1791591994,
      "iss": "https://sts.windows.net/7c9e2a41-6b35-4d80-a192-5f3e8c0b764d/",
      "oid": "a6d3185f-2c74-49e0-b863-7f1a5d902c48",
      "ipaddr": "192.0.2.105",
      "rh": "1.ATcAfJ4qQWs1TYChkl8-jAt2TZ-c3C4ejt5KikrMKG7RuJkAAJA3AA.",
      "upn": "[e-mail]",
      "aio": "AUQAu/8eAAAAMwUV/smT8CKL001cnYz68dCgweVCuG9fN8PdzP6z+Cgr9ce9MTL33xllyGpnGEySoY4oafB0ebvUv/4/OXjI0B==",
      "nbf": 1791591994,
      "roles": ["CLOUD_EXTERNAL_ROLE", "midtierapp_role"],
      "uti": "YQjmcVJOg1vUwSCS-Z5zBB",
      "unique_name": "[e-mail]",
      "name": "Marvin Anderson",
      "aud": "https://supremo.onmicrosoft.com/3b7e91d2-6a48-4f05-8c13-9d2a6e740b58",
      "appidacr": "0",
      "amr": ["pwd"],
      "acr": "1"
    }

  • OCI IAM:

    SELECT ORA_END_USER_CONTEXT.USER.TOKEN FROM DUAL;
    
    TOKEN
    --------------------------------------------------------------------------------
    {
      "client_ocid": "ocid1.domainapp.oc1.sea.amaaaaaaq7m2v5k3n6p4r2s7t5u3w6x4y2z7a5b3c6d4e2f7g5h3j6k4m2n7p5q3",
      "sub": "emma.baker",
      "client_id": "a7c29e416b8f4d039e5261f8c0a735bd",
      "resource_app_id": "c4e82b176a934f05b7d2619e3c8a045f",
      "exp": 1792018301,
      "domain_home": "us-seattle-1",
      "client_tenantname": "idcs-a83f2b716c494e05b9d0276f1a3c8e54",
      "tenant_iss": "https://idcs-a83f2b716c494e05b9d0276f1a3c8e54.identity.oraclecloud.com:443",
      "user_ocid": "ocid1.user.oc1..aaaaaaaam4n7p2q5r3s6t4u7v2w5x3y6z4a7b2c5d3e6f4g7h2j5k3m6n4p7q2r5",
      "domain_id": "ocid1.domain.oc1..aaaaaaaap5q3r6s4t7u2v5w3x6y4z7a2b5c3d6e4f7g2h5j3k6m4n7p2q5r3s6t4",
      "ca_name": "supremo",
      "user_locale": "en",
      "opc": false,
      "gtp": "ro",
      "sidle": 480,
      "user_displayname": "Emma Baker",
      "user_tenantname": "idcs-a83f2b716c494e05b9d0276f1a3c8e54",
      "client_guid": "5e82a3c7196b4d08a2f735c1e9b064ad",
      "group": [
        "deepsec_console_pwd_never_expires",
        "EMPLOYEE_ROLE",
        "iam_db_token_group"
      ],
      "iat": 1792014701,
      "iss": "https://identity.oraclecloud.com/",
      "tok_type": "AT",
      "client_name": "Oracle DB Client App",
      "tenant": "idcs-a83f2b716c494e05b9d0276f1a3c8e54",
      "primTenant": true,
      "ca_ocid": "ocid1.tenancy.oc1..aaaaaaaar6s4t7u2v5w3x6y4z7a2b5c3d6e4f7g2h5j3k6m4n7p2q5r3s6t4u7v2",
      "user_lang": "en",
      "sub_type": "user",
      "sub_mappingattr": "userName",
      "user_tz": "America/Chicago",
      "user_id": "9b4e2a716c834d05a8f137e2b6c940ad",
      "region_name": "us-sea-idcs-1",
      "jti": "2f7a4c916e384b05a9d263e8c1f740bd",
      "scope": "DB_ACCESS_SCOPE",
      "aud": "OracleDB",
      "domain": "Default",
      "user.tenant.name": "idcs-a83f2b716c494e05b9d0276f1a3c8e54"
    }

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