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. A separate procedure covers IAM-registered applications that connect directly to the database using their own identity.

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.
Establish the database connection.
Create the database connection that the application uses to attach end-user security context payloads. The connecting principal (a connection pool user account or the application identity) must hold 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 establish the connection in any of the following three ways.
1. Password-authenticated connection pool user account
  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;
```
2. IAM-authenticated connection pool user account
  Alternatively, 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;
```
3. Application identity-based connection
  
  In this case, the application logs on directly as its application identity using its own database-access token, instead of a connection pool user account. The database validates the token and first looks for a global schema mapped to the token's subject (the application's client ID). If no mapped schema exists, the database resolves the subject to the mapped application identity and creates a schema-less lightweight session for it. Subsequently, the application attaches the end-user security context payload to that session at request time.
  
  Create an application identity that maps to the application's IAM client ID, and grant it the required connection privileges. Because system privileges cannot be granted to an application identity or a data role directly, grant CREATE SESSION and CREATE END USER SECURITY CONTEXT privileges to a database role, grant that database role to a data role that is locally managed, and grant the data role to the application identity.
```
CREATE APPLICATION IDENTITY hcm_app
  MAPPED TO 'AZURE_CLIENT_ID=<HRAPP_CLIENT_ID>';

CREATE ROLE hcm_app_db_role;
GRANT CREATE SESSION TO hcm_app_db_role;
GRANT CREATE END USER SECURITY CONTEXT TO hcm_app_db_role;
 
CREATE DATA ROLE hcm_app_logon_role;
GRANT hcm_app_db_role TO hcm_app_logon_role;
 
GRANT DATA ROLE hcm_app_logon_role TO hcm_app;
```
  For OCI IAM, use the identifier string IAM_OAUTH_CLIENT_ID instead of AZURE_CLIENT_ID.
  
  The IAM client ID of the application identity used for the direct logon must match the client ID in the database-access token of every end-user security context payload that the application attaches. For each attached end user, the database enables the data roles granted directly to the application identity, but not the data roles mapped from the application's own token.

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.
  
  Note:
  If you established the connection using application-identity-based connection in step 2(c), you already created this application identity and granted it the connection privileges. Use this step only to grant any additional data roles it can activate.
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 End-User 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.

Note:

This section configures the direct logon path with OAuth 2.0 tokens. For scenarios where an end user logs in directly with an OCI IAM auth token, see Configure the Database for OCI IAM Auth Tokens.

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 Step 3 of 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 or groups in IAM, using the mapping prefix that matches the identity provider and token type the end users present:
- Microsoft Entra ID (OAuth 2.0 token): Use AZURE_ROLE to map to an Entra ID application role.
```
CREATE DATA ROLE employee_role MAPPED TO 'AZURE_ROLE=employee';
```
- OCI IAM (OAuth 2.0 token): Use IAM_OAUTH_GROUP to map to an OCI IAM group.
```
CREATE DATA ROLE employee_role MAPPED TO 'IAM_OAUTH_GROUP=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;
```

9.1.3 Set Up IAM Integration for Application Direct Logon

If an IAM-managed application or AI agent connects directly to the database as an application identity with its own database-access token, complete the following configuration steps.

In this pattern, the application authenticates to IAM with its client credentials and obtains a database-access token. This token identifies the application as the subject. The database validates the token and, if no mapped global schema exists for the token subject, it resolves the subject to a mapped application identity. The database then creates a lightweight session and establishes an end-user security context for that application identity.

The application identity itself is the identity in the end-user security context, and the database enforces data authorization based on the active data roles for that application identity.

Enable Transport Layer Security (TLS).
Token-based authentication 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 application's database-access token.

Follow the procedure described in Step 3 of Set Up IAM Integration for Application-Mediated Connections.
Create the application identity
Create an application identity in the database that maps to the application’s IAM client identifier. When the application logs on with a database-access token whose subject is this client ID, the database resolves the session to this application identity.
```
CREATE APPLICATION IDENTITY hcm_app
  MAPPED TO 'AZURE_CLIENT_ID=<HRAPP_CLIENT_ID>';
```
For OCI IAM, use the identifier string IAM_OAUTH_CLIENT_ID instead of AZURE_CLIENT_ID. For the complete syntax and options, see Create Application Identity.
Create data roles.
Define the data roles that determine the application's data access. You can use either or both of the following approaches:
- Create data roles managed locally in the database, which you grant directly to the application identity.
- Create data roles that map to the application’s IAM roles or group claims.
The following example creates a data role managed locally in the database:
```
CREATE DATA ROLE hcm_app_logon_role;
```
The following example creates a data role mapped to the application's Microsoft Entra ID role:
```
CREATE DATA ROLE employee_role
  MAPPED TO 'AZURE_ROLE=EMPLOYEE';
```
For the complete syntax and options, see Configure Data Roles.
Create a generic database role with the required privileges for direct logon.
Create a database role and grant it the CREATE SESSION and CREATE END USER SECURITY CONTEXT privileges. Grant this database role to a data role that the application identity holds directly. The application identity must have both these privileges to log on directly and to establish the end-user security context. See Grant Database Role to Data Role.
```
-- Create a standard database role for connection privileges
CREATE ROLE hcm_app_db_role;
GRANT CREATE SESSION TO hcm_app_db_role;
GRANT CREATE END USER SECURITY CONTEXT TO hcm_app_db_role;

-- Grant the connection privileges to the data role
GRANT hcm_app_db_role TO hcm_app_logon_role;
```
Grant the data roles to the application identity.
Finally, grant the data roles that are locally managed to the application identity so the database enables them for the application's sessions. The database enables externally mapped data roles automatically, based on the role claims in the application's database-access token.
```
GRANT DATA ROLE hcm_app_logon_role TO hcm_app;
```