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.

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.
  
  For the configurable OAuth 2.0 provider, use CLIENT_ID instead of AZURE_CLIENT_ID. The database obtains the client identifier of the application connecting to the database from the claim specified by application_id_claim in the database-access token. This identifier can differ from sub and is used to resolve the corresponding application identity.
  
  The application identity used to establish the connection can differ from the application identified in the attached end-user security context payload’s database-access token. For example, Application A (AppA) can establish the connection and attach a payload containing Application C’s (AppC) client-credentials database-access token. For each attached end user, when the two-token payload and the connection identify the same application, the database enables the data roles granted directly to that application identity, but not the data roles mapped from the application’s own token. For single-token and cross-application flows, see Scenario 1a — Through an application.

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

Configurable OAuth 2.0 Provider

Use the OAUTH2 identity provider type to configure token validation and claim mappings. Keycloak is the initial supported provider. The database verifies that the database-access token’s aud claim matches the audience value in IDENTITY_PROVIDER_CONFIG. For the required Keycloak configuration, see Configure Keycloak for Application-Mediated Access.

On Oracle AI Database, connect to the target PDB and run the following statements. Replace the example values with the values for your Keycloak realm and clients.

ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE = OAUTH2 SCOPE=BOTH;

ALTER SYSTEM SET IDENTITY_PROVIDER_CONFIG = '{
  "issuer": "https://keycloak.example.com/realms/deepsec",
  "jwks_uri": "https://keycloak.example.com/realms/deepsec/protocol/openid-connect/certs",
  "audience": "db_app",
  "username_claim": "preferred_username",
  "unique_id_claim": "sub",
  "application_id_claim": "client_id",
  "roles_claim": "roles"
}' SCOPE=BOTH;

Parameter	Required	Default	Description
`issuer`	Yes	None	Expected value of the token’s `iss` claim.
`jwks_uri`	Yes	None	JWKS endpoint used to retrieve public signing keys. This configured endpoint is authoritative for signing-key retrieval.
`audience`	Yes	None	Expected database audience. Specify one string. The token’s `aud` claim can be a string or an array; a match succeeds when any audience value matches the configured value.
`username_claim`	Yes	None	Name of the claim that supplies the end-user name. For the Keycloak example, use `preferred_username`.
`unique_id_claim`	No	`sub`	Name of the claim that supplies the unique user identifier. Select a claim whose identifier scope matches your identity requirements.
`application_id_claim`	Yes	None	Name of the claim in the database-access token that supplies the client identifier of the application connecting to the database. In the Graalbase example, use `client_id`, which contains the ORDS client identifier, `ords_client`.
`roles_claim`	No	`roles`	Name of the top-level array claim that supplies realm roles. Nested role claims are not parsed.

The configurable OAuth 2.0 provider is not supported on Oracle Autonomous AI Database.

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.

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';
```
- Keycloak (configurable OAuth 2.0 provider): Use ROLE to map a data role to a Keycloak realm role.
```
CREATE DATA ROLE employee_role MAPPED TO '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;
```

Set Up IAM Integration for Logon as an Application Identity

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.

Note: For the configurable OAuth 2.0 provider, the database resolves the application identity using the client identifier from the claim specified by application_id_claim. This identifier can differ from sub.

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 configurable OAuth 2.0 provider, use 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 Keycloak, map data roles to the realm roles assigned to the service account of the application connecting to the database. These roles must be included in the application’s database-access token.

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