Oracle Cloud Infrastructure Documentation

Prerequisites

Before you create a Database Tools connection that uses IAM authentication, ensure that the following prerequisites are met.

Database Prerequisites

Before configuring a Database Tools connection to use IAM authentication, ensure the following database requirements are met:

Note

For ADB, the IAM authentication prerequisites (such as secure/TLS connectivity) are already configured in the Database Tools service. In most cases, you can go directly to the IAM policy and database user mapping steps.

For non-ADB Oracle Databases (such as Exadata and Base Database Service), you must first verify and configure the prerequisites (such as TCPS/TLS server authentication, wallets/certificates) for IAM token connections to work. See Prerequisites for IAM Authentication on Oracle Database

Supported Database Versions

  • The supported Oracle Database-as-a-Service (DBaaS) environments are:

    • Oracle Autonomous Database (ADB)
    • Oracle Exadata Database Service
    • Oracle Base Database Service

  • You need Oracle Database release 19c, version 19.16 or later.

  • The Oracle Database 21c client does not fully support IAM token-based authentication. Use a client version that supports the required IAM database token functionality. See the section Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) SSO Token Based Authentication in IAM Authentication with Oracle Database.

TLS (TCPS) Connectivity and Server Authentication

IAM authentication requires secure connectivity to the database:

  • Use TCPS from the Database Tools service to the database. Select this option when Creating a Connection.
  • Configure TLS server authentication for your database. For non-ADB environments, ensure you set up a TLS wallet and related certificates under WALLET_ROOT, following the requirements for your specific database service and configuration.

For more information, see Configure TLS to Use IAM Tokens.

Enable IAM Authentication for Oracle Database

To enable IAM authentication:

  1. Create a Database Tools connection using Password Authentication with a privileged database user (for example, SYS or ADMIN). To create a connection, see Creating a Connection.

  2. Configure external authentication for the database instance.

    1. Select the Database Tools connection.
    2. Expand Actions and select Configure external authentication.
    3. For External authentication type, select OCI_IAM.
    4. Click Update to save the configuration.

Create Global Database Users

IAM authentication requires a global user mapping in the database so the database can map an IAM principal (user or group) to a database user (schema).

Exclusive mapping

Use exclusive mapping when you want a one-to-one mapping between an IAM user and a database schema.

CREATE USER scott IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=<iam-user-name-or-identifier>';
GRANT CREATE SESSION TO scott;

where <iam-user-name-or-identifier> refers to the IAM user’s Database Username attribute. If Database Username is not available for the IAM user, the IAM user’s standard user name is used as the fallback.

For more information about Database Username and the IAM standard user name, see:

Shared mapping

Use shared mapping when you want multiple IAM users (members of an IAM group) to connect as a shared schema.

CREATE USER scott IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=<iam-group-name>';
GRANT CREATE SESSION TO scott;

where <iam-group-name> refers to the IAM Group Name value as defined in IAM for the group. All IAM users who are members of this IAM group will connect as the shared database user.

Note

If a user is a member of multiple IAM groups that each have a shared mapping, the database determines the mapping based on the database’s mapping rules (for example, creation order). Ensure your mappings are unambiguous for your intended authorization model.

For more information, see:

Grant IAM Permissions for Database Connections

To allow users to generate and use database tokens, grant IAM permissions for Database Tools connections (resource type: database-connections). These permissions include the DB_CONNECT permission.

Use policy statements such as the following examples:

  • Allow a group to use database connections in the tenancy.

    allow group dbuser to use database-connections in tenancy

  • Allow a group to use database connections in a compartment. 

    allow group dbuser to use database-connections in compartment prod

  • Restrict access to a specific database (by OCID).

    allow group dbuser to use database-connections in compartment prod 
where target.database.id = 'ocid1.autonomousdatabase.oc1.phx.xxxx'

For more information about IAM policies, see Use IAM Authentication with Autonomous AI Database.