Configure the Database for IAM Integration

9.1 Configure the Database for IAM Integration

Complete the required configuration in your database to integrate with an IAM system (for example, Microsoft Entra ID or OCI IAM) 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 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.

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.
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;
```

Configure the identity provider.

Set the database identity provider parameters to match your database's IAM 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. (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.

Note:

On Oracle Autonomous AI Database, if external authentication has already been enabled, the DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION call fails with ORA-20004. Add force => TRUE to the call to override the existing configuration. Only one external authentication method can be active at a time, so using force to switch IAM types (for example, from Entra ID to OCI IAM) deactivates the previously configured one.

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. If external authentication has already been enabled, add force => TRUE to the call by uncommenting the line:

Note:
If Entra ID is already configured with the required parameter values, calling DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION again is not necessary. Use force only when you need to explicitly change the Entra ID values. Force-enabling overwrites the existing configuration and may break existing Entra ID-authenticated database users.
```
BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
     type   => 'AZURE_AD',
     -- force => TRUE,
     params => JSON_OBJECT(
       'tenant_id'          VALUE '<TENANT_ID>',
       'application_id'     VALUE '<DB_APP_ID>',
       'application_id_uri' VALUE '<DB_APP_ID_URI>'
     )
  );
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.

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.

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. If external authentication has already been enabled for OCI IAM, add

force =>
                                        TRUE

to provide the additional parameters required for configuration. Force-enabling does not break the existing OCI IAM global user authentication:

BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
     type   => 'OCI_IAM',
     -- force => TRUE,
     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.

Note:

On Oracle Autonomous AI Database, the DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION call for OCI_IAM automatically populates both IDENTITY_PROVIDER_CONFIG (with the OCI realm, region, and endpoint values) and IDENTITY_PROVIDER_OAUTH_CONFIG (with the app_id and domain_url parameters you pass). You do not have to set these parameters separately.

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;

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

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

Follow the procedure described in Set Up IAM Integration for Application-Mediated Connections.
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.
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;
```