Use External Authentication with Database Tools

Autonomous AI Database extends external authentication support to Databases Tools and related tools using identity providers like Oracle Cloud Infrastructure IAM, Microsoft Entra ID, Google Cloud Platform, AWS Cognito, and Okta. This enables secure single sign-on (SSO) access to Database Actions without traditional database passwords for globally identified users.

About External Authentication with Database Actions

You can authenticate to the tool interface with the same external identity used for database sessions. The identity provider configuration for Database Tools is separate from enabling external authentication on the database. The Autonomous AI Database stores the identity provider configuration required for authentication in the database, with sensitive values such as the client secret encrypted. This configuration includes the identity provider name, client ID, client secret, and OpenID Connect discovery URL.

During sign-in, the tools use this configuration to redirect you to the appropriate identity provider and to validate authentication tokens issued for externally authenticated users.

Note: Autonomous AI Database supports external authentication for the following built-in tools in Database Actions - SQL Developer and Data Studio. The database does not support external authentication for tools, such as APEX and Oracle Machine Learning.

Prerequisites

Ensure that you can access the Autonomous AI Database instance using a user account with ADMIN privileges.

To use external authentication with Database tools, you must:

Enable External Authentication for Database Actions
Create global database users
Register identity provider information with the database
Access Database Actions using external credentials

You must follow the above steps for every supported provider. The provider-specific differences are limited to the database-level enablement procedure, the global user mapping syntax, and whether the Database Tools identity provider metadata must be registered with DBMS_CLOUD_FUNCTION_ADMIN.CREATE_IDP.

Provider Step Requirements

Use this table to determine which provider setup steps apply before following the detailed steps.

Provider	Enable external authentication	Register IDP
OCI IAM	Mandatory if not enabled	Not required
Microsoft Entra ID (Azure)	Mandatory	Mandatory
AWS Cognito	Configure with IDP	Mandatory
Google Cloud Platform (GCP)	Configure with IDP	Mandatory
Okta	Configure with IDP	Mandatory

Provider-Specific Notes

Provider	Notes and exceptions
OCI IAM	Use `DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION` with `type => 'OCI_IAM'`. Do not run `CREATE_IDP` for OCI IAM. Map users or groups with `IAM_PRINCIPAL_NAME`, or `IAM_GROUP_NAME`.
Microsoft Entra ID (Azure)	Before you run the database configuration steps, a Microsoft Entra ID administrator must complete the Azure-side setup. Register the Autonomous AI Database instance with the Microsoft Entra ID tenancy, expose the Application ID URI and scope, create app roles if you use shared mappings, and assign the required users, groups, or applications. See Enable Microsoft Entra ID Authentication on Autonomous AI Database. Then use `DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION` with `type => 'AZURE_AD'` and the tenant/application values. Register Database Tools metadata with `CREATE_IDP` by using the tenant-specific OpenID Connect discovery URL. Map users, clients, or app roles with `AZURE_USER`, or `AZURE_ROLE`.
AWS Cognito	Configure the Cognito user pool, app client, domain, and user or group membership in AWS. Register Database Tools metadata with `CREATE_IDP` by using the Cognito user-pool OpenID Connect discovery URL. Map users with `AWS_USER` and shared-role mappings with `AWS_ROLE`.
Google Cloud Platform (GCP)	Configure the OAuth consent screen, OAuth client credentials, redirect URI, and user assignment in Google Cloud. Register Database Tools metadata with `CREATE_IDP` by using the Google OpenID Connect discovery URL. Map users with `GCP_USER`.
Okta	Assign the application to the Okta users or groups that should sign in. If group mapping is used, expose the groups scope and groups claim in the authorization server. Register Database Tools metadata with `CREATE_IDP` by using the appropriate Okta OpenID Connect discovery URL. Map users with `OKTA_USER` and groups with `OKTA_GROUP`.

Enable External Authentication for Database Actions

As an ADMIN user, enable external authentication on the Autonomous AI Database. This allows the database to authenticate you through supported external identity providers.

Note: The option to use external authentication in Database Actions is available only when external authentication has been enabled for the Autonomous AI Database. If no external authentication provider has been enabled, you will not see the option.

Before you enable external authentication, check whether an external authentication scheme is already enabled:

SELECT name, value
FROM v$parameter
WHERE name = 'identity_provider_type';

If identity_provider_type is OCI_IAM or AZURE_AD, then external authentication is already enabled for that provider, and no change is required for database external authentication.

To use external authentication with Database Tools, you must still complete the Database Tools configuration by creating or verifying the globally identified database users, registering the identity provider information with DBMS_CLOUD_FUNCTION_ADMIN.CREATE_IDP, and providing the required Database Actions and Web Access privileges.

If another external authentication provider is enabled, do not use force => TRUE unless you intend to replace the current external authentication configuration.

Using force => TRUE disables the currently enabled external authentication provider and can disrupt existing users or applications that depend on it.

See Enable Identity and Access Management (IAM) Authentication on Autonomous AI Database for more information.

Note: Only one external authentication provider can be enabled at a time.

Example: Enable External Authentication with OCI IAM

As an ADMIN user, you can enable Oracle Cloud Infrastructure IAM external authentication on the Autonomous AI Database:

BEGIN
   DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
      type  => 'OCI_IAM',
      force => TRUE
   );
END;
/

This DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION procedure enables Oracle Cloud Infrastructure IAM external authentication for the database. It does not use the identity provider name, client ID, client secret, or OpenID Connect discovery URL.

The ENABLE_EXTERNAL_AUTHENTICATION procedure configures the database to trust a supported external identity provider. The procedure varies depending on the identity provider you use.

Example: Enable External Authentication with Microsoft Entra ID

Before you run this example, complete the Microsoft Entra ID setup in Azure and collect the tenant ID, application ID, and Application ID URI from the Azure app registration. If you use app-role mappings, create the app roles and assign the required users, groups, or applications in Microsoft Entra ID. See Register the Oracle AI Database Instance with a Microsoft Entra ID Tenancy and Manage App Roles in Microsoft Entra ID.

As an ADMIN user, enable Microsoft Entra ID external authentication on the Autonomous AI Database:

BEGIN
  DBMS_CLOUD_ADMIN.ENABLE_EXTERNAL_AUTHENTICATION(
      type   => 'AZURE_AD',
      params => JSON_OBJECT(
                  'tenant_id' VALUE 'tenant-id',
                  'application_id' VALUE 'application-id',
                  'application_id_uri' VALUE 'application-id-uri'),
      force  => TRUE
  );
END;
/

For tools such as Database Actions and Data Studio, ensure that externally authenticated global database users are granted the appropriate database roles and have Web Access enabled.

Note: When external authentication is already enabled for the provider that you want to use, do not rerun ENABLE_EXTERNAL_AUTHENTICATION. Use CREATE_IDP only to register identity provider metadata for providers that require OpenID Connect metadata registration, such as Microsoft Entra ID, and use ENABLE_EXTERNAL_AUTHENTICATION cautiously. For Oracle Cloud Infrastructure IAM, you will enable external authentication and configure globally identified users, and you do not need to register identity provider information with the database. Using the force parameter can break an existing external authentication configuration.

Create Global Database Users

After enabling external authentication, create users that are IDENTIFIED GLOBALLY. A globally identified user is a database user or schema created in Autonomous AI Database and mapped to an external identity provider principal instead of a database password. You will create global database users for the same identity provider that you enabled for external authentication. Permissions and authorizations are granted to the global database users for privileges in the database, and to logon to DBActions you will need to enable the global database user for ORDS and grant create session at a minimium.

Run the following examples to create global database users mapped to their respective identity provider’s principals.

Example: Create Global Database Users for OCI IAM

Create a global database user mapped to an Oracle Cloud Infrastructure IAM principal:

CREATE USER adam_scott
IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=adamscott';

Grant access to the database user adam_scott.

GRANT CREATE SESSION TO adam_scott;

You can also map a shared database user to an Oracle Cloud Infrastructure IAM group:

CREATE USER sales_group
IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=db_sales_group';

Run these statements to allow the mapped sales_group database user to sign in to the database.

GRANT CREATE SESSION TO sales_group;

Example: Create Global Database Users for Microsoft Entra ID

Create a global database user mapped to a Microsoft Entra ID user:

CREATE USER peter_fitch
IDENTIFIED GLOBALLY AS 'AZURE_USER=peter.fitch@example.com';

Run these statements to grant database privileges or roles to the user peter_fitch:

GRANT CREATE SESSION TO peter_fitch;

You can also map a shared database user to a Microsoft Entra ID app role:

CREATE USER dba_azure
IDENTIFIED GLOBALLY AS 'AZURE_ROLE=AZURE_DBA';

Grant the user privilege to establish a database connection:

GRANT CREATE SESSION TO dba_azure;

You must use exclusive mappings to map a database user to a single external principal or use shared mappings to map a database user to an external group or role that can represent multiple principals.

Provider	Global user mapping examples: exclusive and shared mappings
OCI IAM	Exclusive mapping: `IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=<iam-user>'` Shared mapping: `IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=<iam-group>'`
Microsoft Entra ID (Azure)	Exclusive mapping: `IDENTIFIED GLOBALLY AS 'AZURE_USER=<user-principal-name>'` Shared mapping: `IDENTIFIED GLOBALLY AS 'AZURE_ROLE=<app-role>'`
AWS Cognito	Exclusive mapping: `IDENTIFIED GLOBALLY AS 'AWS_USER=<aws-user>'` Shared mapping: `IDENTIFIED GLOBALLY AS 'AWS_ROLE=<aws-role>'`
Google Cloud Platform (GCP)	Exclusive mapping: `IDENTIFIED GLOBALLY AS 'GCP_USER=<gcp-user>'` Shared mapping: Not available.
Okta	Exclusive mapping: `IDENTIFIED GLOBALLY AS 'OKTA_USER=<okta-user>'` Shared mapping: `IDENTIFIED GLOBALLY AS 'OKTA_GROUP=<okta-group>'`

Note: For global users, these examples cover Oracle Cloud Infrastructure IAM; for other identity providers, use the provider-specific mapping syntax in their documentation.

To use the user with Database Actions, you must create a session, grant the required Database Actions privileges, enable Oracle REST Data Services (ORDS) for the schema, and ensure the user has Web Access.

Example: Enable ORDS for a Globally Identified Database User

GRANT CREATE SESSION TO IDP_SHARED;
BEGIN
    ORDS_ADMIN.ENABLE_SCHEMA(
        p_enabled             => TRUE,
        p_schema              => 'idp_shared',
        p_url_mapping_type    => 'BASE_PATH',
        p_url_mapping_pattern => 'idp_shared',
        p_auto_rest_auth      => FALSE);
END;

Note: Grant DWROLE to enable the mapped users to access Data Studio suite of tools in Database Actions.

Register Identity Provider Information with the Database

After you create globally authenticated users, an administrator must register the identity provider with the database by using DBMS_CLOUD_FUNCTION_ADMIN.CREATE_IDP.

This registration stores the identity provider name, client ID, client secret, and discovery metadata required for OpenID Connect token validation. Registering an identity provider enables Database Tools, such as Database Actions and Data Studio, to authenticate users through the supported external identity providers.

You will use the CREATE_IDP procedure to create a new identity provider for external authentication. You only need to register an identity provider once for a database.

You do not need to register identity provider information for Oracle Cloud Infrastructure IAM. You will only enable external authentication and configure globally identified users for Oracle Cloud Infrastructure IAM.

The identity provider registration step in this section applies to the other supported external providers.

Example: Generic CREATE_IDP Example for External Providers

BEGIN
   DBMS_CLOUD_FUNCTION_ADMIN.CREATE_IDP(
      idp_name      => '<IDP_NAME>',
      client_id     => '<client-id>',
      client_secret => '<client-secret>',
      params        => JSON_OBJECT(
                         'discovery_url' VALUE '<openid-configuration-url>'));
END;
/

For more information on the parameters and description, refer to CREATE_IDP Procedure.

You can also update an existing identity provider entry using the UPDATE_IDP Procedure and remove an existing identity provider registration from the database using the DELETE_IDP Procedure.

Access Database Actions with External Authentication

When an identity provider is registered and external authentication is enabled, Database Actions and other supported tools display the Sign in with SSO option. Sign in with SSO means that you sign in to Database Actions as an externally authenticated global database user through the configured identity provider. If you do not already have an active identity provider session, Database Actions redirects you to Oracle Cloud Infrastructure IAM or Microsoft Entra ID to complete authentication.

To sign in as an externally authenticated global database user:

Open the Database Actions URL.
Select Sign in with SSO.
Authenticate with the configured identity provider, such as Oracle Cloud Infrastructure IAM or Microsoft Entra ID.
After authentication succeeds, Database Actions opens for the mapped global database user.

Note: Accessing Database Actions from the Oracle Cloud Infrastructure Console as an ADMIN is a separate flow. With the required Oracle Cloud Infrastructure IAM policy, you can open Database Actions from the Console as ADMIN. This is different from signing in directly to Database Actions as an externally authenticated global database user. When an externally authenticated user signs out, Database Actions returns to the Database Actions sign-in page.