15.3 Prerequisites for Establishing a Local Security Context

For environments bypassing centralized IAM in favor of local user management, perform the following configuration tasks. These tasks ensure the database can successfully bind a local end-user security context to an active session.

Review the deployment scenario that matches your environment.

Local application users connecting through an application

If your application manages users in its own user store and those users connect through the application, complete the following steps to establish a security context for their sessions. The application user is identified by a user name and an optional security context lookup key supplied by the application.

1. Configure the database for application sessions

   For detailed Oracle AI Database configuration instructions, see Set Up Local Authentication 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 local application users, the payload must include the end-user name and an optional security context lookup key supplied by the application.

   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. Data roles, end-user context attributes, and the lookup key are optional. To maintain distinct end-user security contexts for the same local end user with the same data roles, specify a different lookup key for each security context.

      • Here's a JDBC example that illustrates a local security context payload attachment with data roles:

        String userName = "Emma";
        String lookupKey = "key1";
         
        EndUserSecurityContext securityContext =
            EndUserSecurityContext.createWithName(DB_ACCESS_TOKEN, userName, lookupKey)
                .withDataRoles(Set.of("hcm_role"))
                .withAttributes(ctxAttrs);
        

        The following JDBC example omits the lookup key:

        String userName = "Emma";
         
        EndUserSecurityContext securityContext =
            EndUserSecurityContext.createWithName(DB_ACCESS_TOKEN, userName)
                .withDataRoles(Set.of("hcm_role"))
                .withAttributes(ctxAttrs);
        

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

      • Here's a Python example that illustrates a local security context payload attachment with data roles:

        user_context = oracledb.create_end_user_security_context(
            end_user_identity = ("emma", "key1"),
            database_access_token = "database_access_token_1026",
            data_roles = ["hcm_role"]
        )

        To omit the lookup key, pass None for the key field:

        user_context = oracledb.create_end_user_security_context(
            end_user_identity = ("emma", None),
            database_access_token = "database_access_token_1026",
            data_roles = ["hcm_role"]
        )

        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 obtain or construct the local end-user identity, including the end-user name and optional security context lookup key, and make that payload available to the driver before database operations are executed.

      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.

Local end users connecting directly (password authentication)

For environments where local end users establish direct database sessions through a SQL client and credential-based authentication, perform the following configuration tasks.

1. Configure the database

   For detailed Oracle AI Database configuration instructions, see Set Up Local Authentication for Direct Logon.

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