15.2 Prerequisites for Establishing a Token-Based Security Context

Before the database can attach a token-based end-user security context to a session, you must configure your database and application environments.

These requirements apply when you manage end users through an IAM system, such as Microsoft Entra ID or OCI IAM, and authenticate them with OAuth 2.0 tokens. Review the deployment scenario that matches your environment.

IAM-managed users connecting through an application

Complete the following steps to enable security context establishment for this scenario.

  1. Configure the database for application sessions

    For detailed Oracle AI Database configuration instructions, see Set Up IAM Integration for Application-Mediated Connections.

  2. Configure the application

    Configure your application to propagate an end-user security context payload to Oracle AI Database for each database operation. For end users managed in an IAM system, the payload must include an end-user token and a database-access token obtained from the IAM. You can also include optional data roles and end-user context attributes, when your application needs to enable them for an end-user security context.

    You can propagate the end-user security context payload by using either API extension methods or a Service Provider Interface (SPI). If both approaches are configured, API calls take precedence over provider-based configuration.

    1. Use API extension methods

      Use this approach if you want to supply the end-user security context payload directly in your application code.

      In your application, use an Oracle client driver (such as JDBC, Python, or ODP.NET) to build and transmit the EndUserSecurityContext object on each database call.

      • Here's a JDBC example that illustrates a token-based security context payload attachment:
        System.out.println("Attaching End-User Security Context");

final String USER_TOKEN     = getUserToken();
final String DB_ACCESS_TOKEN = getDbAccessToken();

Map<String, OracleJsonObject> ctxAttrs = new HashMap<>();
OracleJsonObject attrs = new OracleJsonFactory().createObject();
    attrs.put("service_center_id", 52);
    attrs.put("region_id", "EMEA");
    ctxAttrs.put("HR.HCM", attrs);
    try (
      Connection connection = DriverManager.getConnection(sslURL, props)) {
        EndUserSecurityContext securityContext =
            EndUserSecurityContext.createWithToken(DB_ACCESS_TOKEN, USER_TOKEN)
              .withDataRoles(Set.of("hcm_role"))
              .withAttributes(ctxAttrs);
            connection.unwrap(OracleConnection.class)
               .setEndUserSecurityContext(securityContext);

    query(connection);
}

        For more information on Java API extension methods, see Use the API Extension Methods.

      • Here's a Python example that illustrates a token-based security context payload attachment:
        
user_context = oracledb.create_end_user_security_context(
    end_user_identity = <user_token>,  
    database_access_token = <db_access_token>,
    data_roles = ["hcm_role"],   #optional
    attributes = ctx_attrs     #optional
)

        For more information on Python API extension methods, see Use the API Extension Methods.

    2. Use the Service Provider Interface (SPI)

      Use this approach when you want the Oracle client driver or a configured provider to supply the end-user security context payload automatically, without requiring application code to attach the payload for each SQL operation.

      Install and configure a security context provider that is supported by your Oracle client driver. The provider must integrate with your application’s authentication flow, obtain or receive the end-user token, obtain the database-access token, and make the resulting security context payload available to the driver before database operations are executed. The provider can also include optional data roles and end-user context attributes when required.

      For Java applications, see Use the Service Provider Interface. For Python applications, see Use the Service Provider Interface. For other Oracle client drivers, use the equivalent driver-specific provider or configuration mechanism to propagate the same end-user security context payload.

IAM-managed users connecting directly (no application)

If your IAM-managed users (such as data analysts or developers) connect directly to the database using a SQL client and their own IAM access tokens, complete the following tasks.

Note:

In this scenario:

IAM-managed applications connecting directly

If an IAM-managed application or AI agent connects directly to the database as its own application identity, complete the following tasks. In this scenario, the application authenticates to IAM with its client credentials and obtains a database-access token, and the database establishes an end-user security context whose identity is the application identity.