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

   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. The following JDBC example illustrates a complete 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 additional application configuration details, such as connection properties and settings, see Update Application Configuration with IAM Details.

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.

• Configure the database

  For detailed Oracle AI Database configuration instructions, see Set Up IAM Integration for Direct Logon.

• Create end-user context definitions (optional)

  Additionally, if your data grants rely on custom end-user context attributes, make sure you create the corresponding end-user context definitions. See Configure End-User Contexts and Attributes.

Note:

In this scenario:

• No connection pool user account is required: Because your users connect directly, you don't need a shared database user account.
• Connection strings: For direct logon, you use the same tnsnames.ora connection string format as the standard token-based database authentication. See Configure Oracle Deep Data Security for Direct Logon with End Users in IAM.