9.1 Configure Oracle AI Database

Configure Oracle AI Database to accept end-user security context payloads by setting up identity provider configuration, connection pool user accounts, data roles, and local end-user accounts.

The procedures differ depending on whether your end users are managed in an identity and access management (IAM) system or managed locally — either in the application's own user store or in the database.

Note:

Connect to the database as a named user with the DBA role to perform the configuration tasks in this section.

Topics:

9.1.1 Configure the Database for IAM Integration

Complete the required configuration in your database to integrate with an IAM system and implement Oracle Deep Data Security (Deep Sec). Your specific configuration steps vary depending on whether your IAM-managed users connect through an application or directly through a SQL client.

9.1.1.1 Set Up IAM Integration for Application-Mediated Connections

If your IAM-managed users connect to the database through an application, complete the following configuration steps in your database to enable end-user security context establishment.

Note:

  • On Oracle AI Database, run the SQL and PL/SQL statements in this section as a named user with the DBA role. Run the statements that create the OCI IAM credential object as SYS.
  • On Oracle Autonomous AI Database, run the statements as the ADMIN user.
  1. Enable transport layer security (TLS).
    Transmission of the end-user security context payload requires a TLS-secured connection between the Oracle client driver and the database server. If TLS is not already configured, see Configuring Transport Layer Security Encryption in Oracle AI Database Security Guide.
  2. Set up the connection pool user account.
    Create a connection pool user account and grant it both the CREATE SESSION and CREATE END USER SECURITY CONTEXT privileges. Without the latter privilege, the database server rejects any attempt to attach an end-user security context payload to the session.
    You can provision the connection pool user account in either of the following two ways.
    1. IAM-authenticated connection pool user account
      Create the connection pool user account by identifying it with the application's IAM client ID. This user authenticates to the database using the database-access token. This authentication method for the connection pool user account is supported only for Microsoft Entra ID.
      CREATE USER hr_app_user IDENTIFIED GLOBALLY
  AS 'AZURE_CLIENT_ID=${HRAPP_CLIENT_ID}';

GRANT CREATE SESSION TO hr_app_user;
GRANT CREATE END USER SECURITY CONTEXT TO hr_app_user;
    2. Password-authenticated connection pool user account
      Alternatively, create a standard database user account with a password. This user authenticates to the database using the password.
      CREATE USER hr_app_user IDENTIFIED BY <password>;

GRANT CREATE SESSION TO hr_app_user;
GRANT CREATE END USER SECURITY CONTEXT TO hr_app_user;
  3. Configure the identity provider.
    Set the database identity provider parameters to match your database's IAM application registration. This allows the database server to validate the audience (aud) claim in the application’s database-access token.
    On Oracle AI Database, connect to your target pluggable database (PDB) before applying configuration changes.

    Note:

    On Oracle Autonomous AI Database, this step is not required; you connect directly to the PDB as the ADMIN user. 
    ALTER SESSION SET CONTAINER = <your-target-PDB>;
    Configuration details vary by IAM system and token version in use. Complete the steps applicable to your environment.
    1. Microsoft Entra ID v1 Tokens

      For Entra ID v1 tokens, the database verifies that the database-access token’s aud claim matches the application_id_uri field in the database’s identity_provider_config.

      • On Oracle AI Database, run the following statements:
        ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE = AZURE_AD SCOPE=BOTH;

ALTER SYSTEM SET IDENTITY_PROVIDER_CONFIG = '{
  "application_id_uri": "<DB_APP_ID_URI>",
  "tenant_id": "<TENANT_ID>",
  "app_id": "<DB_APP_ID>"
}' SCOPE=BOTH;
      • On Oracle Autonomous AI Database, run the following statement:
        BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
    type   => 'AZURE_AD',
    params => JSON_OBJECT(
      'tenant_id'          VALUE '<TENANT_ID>',
      'application_id'     VALUE '<DB_APP_ID>',
      'application_id_uri' VALUE '<DB_APP_ID_URI>'
    ),
    force  => TRUE
  );
END;
/
        Replace the placeholders with values from your Entra ID instance. See Configure Microsoft Entra ID for Application-Mediated Access.
      Parameter Description
      application_id_uri The application ID URI of the database resource registered in Entra ID.
      tenant_id The directory (tenant) ID of your Entra ID environment.
      app_id The application (client) ID of the database resource.
    2. Microsoft Entra ID v2 Tokens

      For Entra ID v2 tokens, the database verifies that the database-access token’s aud claim matches the app_id field in the database’s identity_provider_config. The identity provider configuration follows the same format as v1 tokens.

    3. Oracle Cloud Infrastructure Identity and Access Management (OCI IAM)

      For OCI IAM environments, use the IDENTITY_PROVIDER_OAUTH_CONFIG parameter to set up the identity provider. Additionally, you must create a credential object.

      • On Oracle AI Database, run the following statements:
        ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE = OCI_IAM SCOPE=BOTH;

ALTER SYSTEM SET IDENTITY_PROVIDER_OAUTH_CONFIG = '{
  "app_id": "<application_id>",
  "domain_url": "<domain_url>"
}' SCOPE=BOTH;
      • On Oracle Autonomous AI Database, run the following statement:
        BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
    type   => 'OCI_IAM',
    params => JSON_OBJECT(
      'app_id'     VALUE '<application_id>',
      'domain_url' VALUE '<domain_url>'
    )
  );
END;
/

        Replace the placeholders with values from your OCI IAM instance. See Configure OCI IAM for Application-Mediated Access.

        Parameter Description
        app_id The application ID of the database application registered in OCI IAM.
        domain_url The OCI IAM domain URL. Used to retrieve the public signing key for OAuth 2.0 token validation.
      • Create the credential object.

        To obtain an access token for the public signing-key endpoint, the database requires the client ID and client secret of the database's application registration in OCI IAM.

        Create a credential object to store these values securely in the database. Obtain the client ID and client secret from the OAuth Configuration section of your database application in the OCI IAM console, and execute the following block.

        On Oracle AI Database, run the following block as SYS:
        BEGIN
  DBMS_CREDENTIAL.CREATE_CREDENTIAL(
    credential_name => 'OCI_IAM_DOMAIN_DB_CRED$',
    username        => '<CLIENT_ID>',
    password        => '<CLIENT_SECRET>'
  );
END;
/
        On Oracle Autonomous AI Database, run the following block as ADMIN:
        BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_IAM_DOMAIN_DB_CRED$',
    username        => '<CLIENT_ID>',
    password        => '<CLIENT_SECRET>'
  );
END;
/
    To verify the identity provider settings, run the following command from your SQL*Plus prompt:
    SHOW PARAMETER identity;
  4. Create data roles.
    Define the data roles that you want to enable in your end-user security contexts. Because you are using IAM-managed users, you must create data roles mapped to the application roles in IAM. For the complete syntax and options, see Configure Data Roles.
  5. Perform optional additional configuration.
    The following tasks are not mandatory to establish a basic end-user security context, but may be required depending on your application’s authorization model.
    1. Create end-user context definitions.
      If your application logic or data grants rely on custom end-user context attributes, create the corresponding END USER CONTEXT schema objects before deployment. See Configure End-User Contexts and Attributes.
    2. Create the application identity.
      Set up a database identity for your application that matches its IAM client ID. This identity authorizes the application to activate specific data roles within an end-user security context. See Configure Application Identities.
    3. Grant additional data roles to the application identity.
      Explicitly grant any additional or common data roles that your application is allowed to activate. If you skip this step, the database silently ignores the application’s requests for ungranted roles. See Grant and Revoke Data Roles.

9.1.1.2 Set Up IAM Integration for Direct Logon

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, the database-side setup is more concise. Complete the following tasks.

  1. Enable transport layer security (TLS).
    Transmission of the end-user security context payload requires a TLS-secured connection between the client and the database server. If TLS is not already configured, see Configuring Transport Layer Security Encryption in Oracle AI Database Security Guide.
  2. Configure the identity provider.
    Set the database identity provider parameters to match your database's IAM application registration. This enables the database server to validate the audience (aud) claim in the end-user token.
  3. Create data roles.
    Define the data roles that you want to enable in your end-user security contexts. Because you are using IAM-managed users, you must create data roles mapped to the application roles in IAM.
    CREATE DATA ROLE employee_role MAPPED TO 'AZURE_ROLE=EMPLOYEE';
    For the complete syntax and options, see Configure Data Roles.
  4. Create and grant a generic database role.
    Create a generic database role and grant it the CREATE SESSION privilege. Then grant this generic role to your data role used for direct logon. See Grant Database Role to Data Role.
    -- Create a standard database role for connection privileges
CREATE ROLE db_role;
GRANT CREATE SESSION TO db_role;

-- Grant the connection privileges to the data roles
GRANT db_role TO employee_role;

9.1.2 Configure the Database for Local End-User Authentication

Complete the required configuration in your database to implement Oracle Deep Data Security (Deep Sec) when your end users are managed locally rather than through an IAM system. Your specific configuration steps vary depending on whether your local end users connect through an application or establish direct database sessions with password authentication.

9.1.2.1 Set Up Local Authentication for Application-Mediated Connections

If your application maintains its own user store (for example, a user registry in a separate database, LDAP directory, or an application-managed identity system) and those users connect to the database through the application, use the database configuration detailed here to implement Deep Sec, without requiring the users to have IAM accounts.

In this scenario, the local end user is identified by a user name and a security context lookup key supplied by the application.

Even though the end users are managed locally, the application must still be registered in your IAM system and must obtain a database-access token to authorize its own connection to the database. A TLS-secured connection, a connection pool user account, and the identity provider configuration in the database are therefore required. For application registration in IAM, see Register the Application in Microsoft Entra ID and Register the Application in OCI IAM.

  1. Configure the database for application sessions.
    Complete the TLS, connection pool user account, and identity provider setup described in Set Up IAM Integration for Application-Mediated Connections. The configuration for this scenario is identical.
  2. Create end users in the database.
    Provision end users with user names that match the users in the application’s user store. Because these users authenticate to the database through the application’s trust rather than directly, create the end-user accounts without a password.
    CREATE END USER emma;
    For the complete syntax and options, see Configure Local End Users.
  3. Create data roles that are managed locally in the database.
    Create the required data roles to enable within your end-user security contexts. See Configure Data Roles.
    CREATE DATA ROLE employee_role;
  4. Grant the data roles to end users.
    Explicitly grant appropriate data roles to your end-user accounts. See Grant and Revoke Data Roles.
    GRANT DATA ROLE employee_role TO emma;
  5. Perform optional additional configuration.
    The following tasks are not mandatory to establish a basic end-user security context, but may be required depending on your application’s authorization model.
    1. Create end-user context definitions.
      If your application logic or data grants rely on custom end-user context attributes, create the corresponding END USER CONTEXT schema objects before deployment. See Configure End-User Contexts and Attributes.
    2. Create the application identity.
      Set up a database identity for your application that matches its IAM client ID. See Configure Application Identities.

9.1.2.2 Set Up Local Authentication for Direct Logon

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

  1. Create end users in the database.
    For this scenario, create end-user accounts with password authentication enabled.
    CREATE END USER emma IDENTIFIED BY <password>;
    For the complete syntax and options, see Configure Local End Users.
  2. Create data roles that are managed locally in the database.
    Create the required data roles to enable within your end-user security contexts. See Configure Data Roles.
    CREATE DATA ROLE employee_role;
  3. Create and grant a generic database role.
    Create a generic database role and grant it the CREATE SESSION privilege. Then grant this generic role to your data role used for direct logon. See Grant Database Role to Data Role.
    CREATE ROLE db_role;
GRANT CREATE SESSION TO db_role;

GRANT db_role TO employee_role;
  4. Grant the data roles to end users.
    Explicitly grant appropriate data roles to your end-user accounts. See Grant and Revoke Data Roles.
    GRANT DATA ROLE employee_role TO emma;