Use Identity and Access Management Authentication with Base Database Service

About IAM Authentication

OCI IAM integration with Base Database Service supports both database password verifier authentication and token-based authentication. For more information on the architecture for using IAM users on Base Database Service, see Authenticating and Authorizing IAM Users for Oracle DBaaS Databases.

IAM Database Password Authentication

You can enable an Oracle Database instance to allow user access with an OCI IAM database password (using a password verifier).

For password verifier database access, you create the mappings for IAM users and OCI applications to the Oracle Database instance. The IAM user accounts themselves are managed in IAM. The user accounts and user groups can be in either the default domain or a custom, non-default domain.

Note:

Any supported 12c and above database client can be used for IAM database password access to the Oracle Database.

An OCI IAM database password allows an IAM user to log in to a database instance as Oracle Database users typically log in with a user name and password. The user enters their IAM user name and IAM database password. An IAM database password is a different password than the OCI Console password. Using an IAM user with a password verifier you can login to the database with any supported database client as long as the database client supports Oracle Database 12c password verifiers.

IAM SSO Token Based Authentication

You can enable an Oracle Database instance to use OCI IAM SSO tokens.

For token database access, you create the mappings for IAM users and OCI applications to the Oracle Database instance. The IAM user accounts themselves are managed in IAM. The user accounts and user groups can be in either the default domain or a custom, non-default domain.

There are several ways a database client can obtain an IAM database token:

A client application or tool can request the database token from IAM for the user and can pass the database token through the client API. Using the API to send the token overrides other settings in the database client. IAM database token usage requires the Oracle Database client 19.16 and above (not 21c). Limited (not full) IAM database token capabilities are available with some Oracle Database clients 21.5 and above.
If the application or tool does not support requesting an IAM database token and sending it to the database through the client API, the IAM user can first use OCI Command Line Interface (CLI) to retrieve the IAM database token and save it in a file location. For example, to use SQL*Plus and other applications and tools using this connection method, you first obtain the database token using the OCI CLI. If the database client is configured for IAM database tokens, when a user logs in with the slash login form, the database driver uses the IAM database token that has been saved in a default or specified file location.
A client application or tool can use an OCI IAM instance principal or resource principal to get an IAM database token, and use the IAM database token to authenticate itself to a database instance.
IAM users and OCI applications can request a database token from IAM with several methods, including using an API-key.
For more information about configuring client connection, see Configure Client Connection for SQL*Plus that Uses an IAM Token. For more information about other methods such as using a delegation token within an OCI cloud shell, see Authenticating and Authorizing IAM Users for Oracle DBaaS Databases.

If a user enters a username and password to login, then the database driver uses the password verifier method to access the database as the default method.

Prerequisites

The following prerequisites are required for IAM authentication on Base Database Service.

Network Settings

Before using IAM authentication on databases, you must use the Networking service to add a service gateway, a route rule, and an egress security rule to the Virtual Cloud Network (VCN) and subnets where your database resources reside.

Create a service gateway in the VCN where your database resources reside by following the instructions in Create the service gateway.
After creating the service gateway, add a route rule and an egress security rule to each subnet (in the VCN) where the database resources reside so that these resources can use the gateway to use IAM authentication:
1. Go to the Subnet Details page for the subnet.
2. In the Subnet Information tab, click the name of the subnet's Route Table to display its Route Table Details page.
3. In the table of existing Route Rules, check whether there is already a rule with the following characteristics:
  - Destination: All IAD Services In Oracle Services Network
  - Target Type: Service Gateway
  - Target: The name of the service gateway you just created in the VCN
  If such a rule does not exist, click Add Route Rules and add a route rule with these characteristics.
4. Return to the Subnet Details page for the subnet.
5. In the subnet's Security Lists table, click the name of the subnet's security list to display its Security List Details page.
6. In the side menu, under Resources, click Egress Rules.
7. In the table of existing Egress Rules, check whether there is already a rule with the following characteristics:
  - Stateless: No
  - Destination: All IAD Services In Oracle Services Network
  - IP Protocol: TCP
  - Source Port Range: All
  - Destination Port Range: 443
8. If such a rule does not exist, click Add Egress Rules and add an egress rule with these characteristics.

Environment Settings

Check if WALLET_ROOT is configured or not:

show parameters wallet_root;

NAME               TYPE        VALUE
------------------ ----------- --------
wallet_root        string

If a directory location does not show up for WALLET_ROOT, you will not be able to configure this database with IAM. WALLET_ROOT should be set the next time your database is patched. New databases will come with WALLET_ROOT set.

TLS Configuration

When sending IAM tokens from the database client to the database server, a TLS connection must be established. The TLS wallet with the database certificate for the Base DB Service instance must be stored under the WALLET_ROOT location. Create a tls directory so it looks like: WALLET_ROOT/<PDB GUID>/tls

When configuring TLS between the database client and server there are several options to consider.

Using a self-signed database server certificate vs a database server certificate signed by a commonly known certificate authority.
One-way TLS (TLS) vs Mutual or two-way TLS (mTLS).
Client with or without a wallet.

Self-signed certificate: Using a self-signed certificate is a common practice for internally facing IT resources since you can create these yourself and it's free. The resource (in our case, the database server) will have a self-signed certificate to authenticate itself to the database client. The self-signed certificate and root certificate will be stored in the database server wallet. For the database client to be able to recognize the database server certificate, a copy of the root certificate will also be needed on the client. This self-created root certificate can be stored in a client-side wallet or installed in the client system default certificate store (Windows and Linux only). When the session is established, the database client will check to see that the certificate sent over by the database server has been signed by the same root certificate.

A well-known certificate authority: Using a commonly known root certificate authority has some advantages in that the root certificate is most likely already stored in the client system default certificate store. There is no extra step for the client to store the root certificate if it is a common root certificate. The disadvantage is that this normally has a cost associated with it.

One-way TLS: In the standard TLS session, only the server provides a certificate to the client to authenticate itself. The client doesn't need to have a separate client certificate to authenticate itself to the server (similar to how HTTPS sessions are established). While the database requires a wallet to store the server certificate, the only thing the client needs to have is the root certificate used to sign the server certificate.

Two-way TLS (also called Mutual TLS, mTLS): In mTLS, both the client and server have identity certificates that are presented to each other. In most cases, the same root certificate will have signed both of these certificates so the same root certificate can be used with the database server and client to authenticate the other certificate. mTLS is sometimes used to authenticate the user since the user identity is authenticated by the database server through the certificate. This is not necessary for passing IAM tokens but can be used when passing IAM tokens.

Client with a wallet: A client wallet is mandatory when using mTLS to store the client certificate. However, the root certificate can be stored either in the same wallet or in the system default certificate store.

A client without a wallet: Clients can be configured without a wallet when using TLS under these conditions:

One-way TLS is being configured where the client does not have its own certificate, and
the root certificate that signed the database server certificate is stored in the system default certificate store. The root certificate would most likely already be there if the server certificate is signed by a common certificate authority. If it's a self-signed certificate, then the root certificate would need to be installed in the system default certificate store to avoid using a client wallet.

For details on how to configure TLS between the database client and database server including the options described above, see Configuring Transport Layer Security Authentication.

If you choose to use self-signed certificates and for additional wallet related tasks, refer to the orapki command line interface (CLI) reference guide in the Database Security Guide. See Managing Public Key Infrastructure (PKI) Elements.

Change External Identity Providers

This topic describes the steps to change the external identity provider from Centrally Managed Users (CMU) to OCI IAM authentication and authorization and vice-versa on Base Database Service.

OCI IAM authentication and authorization for users is not enabled for newly provisioned databases, by default. Another option for external authentication is to use Centrally Managed Users with Active Directory (CMU-AD). There can only be one external authentication scheme enabled at any given time.

Enable OCI IAM Authentication and Authorization

Perform the following steps to enable OCI IAM authentication and authorization.

Enable OCI IAM authentication and authorization using the ALTER SYSTEM command.
```
ALTER SYSTEM SET IDENTITY_PROVIDER_TYPE=OCI_IAM SCOPE=BOTH;
```

Verify the value of IDENTITY_PROVIDER_TYPE system parameter.

SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME='identity_provider_type';

NAME                   VALUE   
---------------------- ------- 
identity_provider_type OCI_IAM

Check if the IDENTITY_PROVIDER_CONFIG parameter has been set.

SELECT NAME, VALUE FROM V$PARAMETER WHERE NAME='identity_provider_config';

If the IDENTITY_PROVIDER_CONFIG parameter has been set, then reset this parameter.
```
ALTER SYSTEM RESET IDENTITY_PROVIDER_CONFIG SCOPE=BOTH;
```

Disable OCI IAM Authentication and Authorization

Perform the following step to disable OCI IAM authentication and authorization.

Disable OCI IAM integration using the ALTER SYSTEM command.
```
ALTER SYSTEM RESET IDENTITY_PROVIDER_TYPE SCOPE=BOTH;
```

Enable CMU-AD

Perform the following steps to enable Active Directory (AD) users to connect to the database using CMU:

Disable IAM integration as described in Disable OCI IAM Authentication and Authorization.
Configure CMU-AD as described in Configuring Centrally Managed Users with Microsoft Active Directory.

Disable CMU-AD

Perform the following step to disable CMU-AD:

Disable CMU-AD using the ALTER SYSTEM command.

ALTER SYSTEM SET LDAP_DIRECTORY_ACCESS = 'NONE';

Re-enable OCI IAM Authentication and Authorization

Perform the following steps to re-enable IAM users to connect to the database using OCI IAM authentication and authorization:

Disable CMU-AD as described in Disable CMU-AD.
Enable OCI IAM authentication and authorization as described in Enable OCI IAM Authentication and Authorization.

Create IAM Groups and Policies for IAM Users

This topic describes the steps to write policy statements for an IAM group to enable IAM user access to OCI resources, specifically the database instances.

A policy is a group of statements that specifies who can access particular resources, and how. Access can be granted for the entire tenancy, databases in a compartment, or individual databases. This means you write a policy statement that gives a specific group a specific type of access to a specific type of resource within a specific compartment.

Note:

Defining a policy is required to use IAM tokens to access the database. A policy is not required when using IAM database passwords to access the database.

To enable the database to allow IAM users to connect to the database using IAM tokens:

Perform OCI IAM prerequisites by creating a group and adding users to the group.

For example, create the group sales_dbusers.

For more information, see Managing Groups.
Write policy statements to enable access to OCI resources.
1. In the OCI Console, click Identity and Security and click Policies.
2. To a write policy, click Create Policy, and enter a Name and a Description.
3. Use the Policy Builder to create a policy.
  
  For example to create a policy to allow users in IAM group DBUsers to access any database in their tenancy:
```
Allow group DBUsers to use database-connections in tenancy
```
  For example to create a policy that limits members of DBUsers group to access the databases in compartment testing_compartment only:
```
allow group DBUsers to use database-connections in compartment testing_compartment
```
  For example to create a policy that limits group access to a single database in a compartment:
```
allow group DBUsers to use database-connections in compartment testing_compartment 
    where target.database.id = 'ocid1.database.oc1.iad.aabbcc' 
```
4. Click Create.
  For more information on policies, see Managing Policies.

Note:

The following is required for creating policies for use with IAM users on database in the Base Database Service.

Policies can allow IAM users to access database instances across the entire tenancy, in a compartment, or can limit access to a single database instance.
You can use either instance principal or resource principal to retrieve database tokens to establish a connection from your application to an database instance. If you are using an instance pricipal or resource principal, you must map a dynamic group. Thus, you cannot exclusively map instance and resource principals; you only can map them through a shared mapping and putting the instance or resource instance in an IAM dynamic group.

You can create Dynamic Groups and reference dynamic groups in the policies you create to access OCI.

For more information, see Managing Dynamic Groups.

Add IAM Users

To add IAM users to allow access to the database, map database global users to IAM groups or users with CREATE USER or ALTER USER statements (with IDENTIFIED GLOBALLY AS clause).

The authorization of IAM users to a database instance works by mapping database global users (schemas) to IAM users (exclusive mapping) or IAM groups (shared schema mapping).

Authorize IAM Users on a Database Instance:

Perform the following steps to authorize IAM users on a database instance.

Log in as the ADMIN user to the database that is enabled to use IAM (the ADMIN user has the required CREATE USER and ALTER USER system privileges that you need for these steps).
Create a mapping between the database user (schema) with CREATE USER or ALTER USER statements and include the IDENTIFIED GLOBALLY AS clause, specifying the IAM group name.

Use the following syntax to map a global user to an IAM group:
```
CREATE USER global_user IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_GROUP_NAME';
```
For example, to map an IAM group named db_sales_group to a shared database global user named sales_group:
```
CREATE USER sales_group IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=db_sales_group';
```
This creates a shared global user mapping. The mapping, with global user sales_group, is effective for all users in the IAM group. Thus, anyone in the db_sales_group can log in to the database using their IAM credentials (through the shared mapping of the sales_group global user).

The following example shows how to accomplish this for a non-default domain, sales_domain:
```
CREATE USER shared_sales_schema IDENTIFIED GLOBALLY AS 
    'IAM_GROUP_NAME=sales_domain/db_sales_group';
```
If you want to create additional global user mappings for other IAM groups or users, follow these steps for each IAM group or user.

Note:

Database users that are not IDENTIFIED GLOBALLY can continue to login as before, even when the database is enabled for IAM authentication.

Exclusively Map a Local IAM User to an Oracle Database Global User:

Perform the following steps to exlcusively map a local IAM user to an Oracle Database global user.

Log in as the ADMIN user to the database that is enabled to use IAM (the ADMIN user has the required CREATE USER and ALTER USER system privileges that you need for these steps).
Create a mapping between the database user (schema) with CREATE USER or ALTER USER statements and include the IDENTIFIED GLOBALLY AS clause, specifying the IAM local IAM user name.

For example, to create a new database global user named peter_fitch and map this user to an existing local IAM user named peterfitch:
```
CREATE USER peter_fitch IDENTIFIED GLOBALLY AS 'IAM_PRINCIPAL_NAME=peterfitch'
```
The following example shows how to create the user by specifying a non-default domain, sales_domain:
```
CREATE USER peter_fitch2 IDENTIFIED GLOBALLY AS 
    'IAM_PRINCIPAL_NAME=sales_domain/peterfitch';
```

Add IAM Roles

Optionally, create global roles to provide additional database roles and privileges to IAM users when multiple IAM users are mapped to the same shared global user.

Creating global roles is optional for an IAM user with an exclusive IAM mapping to a database user (schema). When the IAM mapping is to a shared schema, creating a global role is also optional. For example, all privileges and roles can be granted to the shared schema and all IAM users who map to the shared schema would be granted the privileges and roles assigned to the shared schema.

Use a global role to optionally differentiate users who use the same shared schema. For example, a set of users can all have the same shared schema and the shared schema could have the CREATE SESSION privilege. Then global roles can be used to provide differentiated privileges and roles assigned to different groups of users who all use the same shared schema.

Granting additional roles to IAM users works by mapping the database global roles to IAM groups.

Map the Database Global Roles to IAM Groups:

Perform the following steps to map the database global roles to IAM groups.

Log in as the ADMIN user to the database that is enabled to use IAM (the ADMIN user has the required CREATE USER and ALTER USER system privileges that you need for these steps).
Set database authorization for the database roles with CREATE ROLE or ALTER ROLE statements and include the IDENTIFIED GLOBALLY AS clause, specifying the IAM group name.

Use the following syntax to map a global role to an IAM group:
```
CREATE ROLE global_role IDENTIFIED GLOBALLY AS 
    'IAM_GROUP_NAME=IAM_GROUP_of_WHICH_the_IAM_USER_IS_a_MEMBER';
```
For example, to map an IAM group named ExporterGroup to a shared database global role named export_role:
```
CREATE ROLE export_role IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=ExporterGroup';
```
The following example shows how to create the role by specifying a non-default domain, sales_domain:
```
CREATE ROLE export_role IDENTIFIED GLOBALLY AS 
    'IAM_GROUP_NAME=sales_domain/ExporterGroup';
```
All members of the ExporterGroup in the sales_domain domain will be authorized with the database global role export_role when they log in to the database.
Use GRANT statements to grant the required privileges or other roles to the global role.
```
GRANT CREATE SESSION TO export_role;
GRANT DWROLE TO export_role;
```
If you want an existing database role to be associated with an IAM group, then use ALTER ROLE statement to alter the existing database role to map the role to an IAM group. Use the following syntax to alter an existing database role to map it to an IAM group:
```
ALTER ROLE existing_database_role 
   IDENTIFIED GLOBALLY AS 'IAM_GROUP_NAME=IAM_Group_Name';
```

If you want to add additional global role mappings for other IAM groups, follow the above steps for each IAM group.

Create IAM Database Password for IAM Users

To add an IAM user and allow the IAM user to login to the database by supplying a username and password, you must create an IAM database password. An IAM username and IAM database password can be used in one of two ways.

The IAM user can enter the IAM username and IAM database password when accessing the database. By default, the database client will follow the normal password authentication mechanism with the database and the database will retrieve the IAM database password verifier from IAM.
The database client can be configured to get an IAM database token using the IAM username and IAM database password. The database client will send this database token to the database for user access.

For more information on getting an IAM database token using the IAM username and IAM database password, see Configuring IAM for Oracle DBaaS.

For more information on IAM database passwords, see Working with IAM Database User Names and Passwords in Managing User Credentials.

Connect to Database with IAM Authentication

After the database ADMIN user maps global users and global roles to the IAM users and IAM groups, users log in to the database instance using their OCI IAM credentials or access the database through an OCI IAM database token.

You can still log in to the database using your local database account username and password (non-global database user account).

You can use a database client to access a database instance as an OCI IAM user. To use a client with OCI IAM username and password credentials and a password verifier, the database client must be 12c or newer.

IAM database token usage requires the Oracle Database client 19.16 and above (not 21c). Limited (not full) IAM database token capabilities are available with some Oracle Database clients 21.5 and above.

Note:

If your database instance is in Restricted Mode, only the users with the RESTRICTED SESSION privilege such as ADMIN can connect to the database.

About Connecting to a Database Instance Using IAM

IAM users can connect to the database instance by using either an IAM database password verifier or an IAM token.

Using the IAM database password verifier is similar to the database password authentication process. However, instead of the password verifier (encrypted hash of the password) being stored in the database, the verifier is instead stored as part of the OCI IAM user profile.

The second connection method makes use of an IAM token for the database. The use of token-based access is a better fit for Cloud resources such as Oracle Databases in the Base Database Service. The token is based on the strength that the IAM endpoint can enforce. This can be multi-factor authentication, which is stronger than the use of passwords alone. Another benefit of using tokens is that the password verifier (which is considered sensitive) is never stored or available in memory. A TCPS (TLS) connection is required when using tokens for database access.

Note:

You cannot configure native network encryption when passing an IAM token. Only Transport Layer Security (TLS) by itself is supported, not native network encryption or native network encryption with TLS.

Client Connections that Use an IAM Database Password Verifier

After you have configured the authorization needed for the IAM user, this user can log in using existing client application, such as SQL*Plus or SQLcl without additional configuration.

The IAM user enters the IAM user name and IAM database password (not the OCI Console password) using any currently supported database client. The only constraint is that the database client version be either Oracle Database release 12.1.0.2 or later to use Oracle Database 12c passwords. The database client must be able to use the 12c password verifier. Using the 11g verifier encryption is not supported with IAM. No special client or tool configuration is needed for the IAM user to connect to the database.

The database client is also able to request a token directly from IAM using the IAM username and IAM database password. For more information about configuring the client to get a token, see Client Connections That Use a Token Requested by an IAM User Name and Database Password.

Client Connections that Use a Token

For IAM token access to the database, the client application or tool requests a database token from IAM for the IAM user.

The client application will pass the database token directly to the database client through the database client API.

If the application or tool has not been updated to request an IAM token, then the IAM user can use OCI CLI to request and store the database token. You can request a database access token (db-token) using the following credentials:

Security tokens (with IAM authentication), delegation tokens (in the OCI cloud shell) and API-keys, which are credentials that represent the IAM user to enable the authentication.
IAM username and IAM database password, which can be used by the database client to retrieve an IAM database token directly when configured to do so.
Instance principal tokens, which enable instances to be authorized actors (or principals) to perform actions on service resources after authenticating.
Resource principal token, which is a credential that enables the application to authenticate itself to other OCI services.
Using an IAM username and IAM database password (which can only be requested by the database client).

When the IAM users logs into the client with a slash / login and the OCI_IAM parameter is configured (sqlnet.ora, tnsnames.ora, or as part of a connect string), then the database client retrieves the database token from a file. If the IAM user submits a user name and password, the connection will use the IAM database verifier access described for client connections that use IAM database password verifiers, unless the database client is configured to retrieve a database token from IAM with the IAM username and IAM database password. The instructions in this topic show how to use the OCI CLI as a helper for the database token. If the application or tool has been updated to work with IAM, then follow the instructions for the application or tool. Some common use cases include the following: SQL*Plus on-premises, SQLcl on-premises, SQL*Plus in Cloud Shell, or applications that use SEP wallets.

The following topics explain how to:

Configure a Client Connection for SQL*Plus that Uses an IAM Database Password
Configure Client Connection for SQL*Plus that Uses an IAM Token
Use Instance Principal to Access Database with IAM Authentication

Configure a Client Connection for SQL*Plus that Uses an IAM Database Password

You can configure SQL*Plus to use an IAM database password.

As the IAM user, log in to the database by using the following syntax:

CONNECT user_name@db_connect_string
Enter password: password

In this specification, user_name is the IAM user name. There is a limit of 128 bytes for the combined domain_name/user_name.

The following example shows how IAM user peter_fitch can log in to a database instance.

sqlplus /nolog
connect peter_fitch@db_connect_string
Enter password: password

Some special characters will require double quotation marks around user_name and password. For example:

"peter_fitch@example.com"@db_connect_string

"IAM database password"

Configure Client Connection for SQL*Plus that Uses an IAM Token

Perform the following steps to configure a client connection for SQL*Plus that uses an IAM token.

Ensure you have an IAM user account.
Check with an IAM administrator and the database administrator to ensure you have a policy allowing you to access the database in the compartment or your tenancy and that you are mapped to a global schema in the database.
If your application or tool does not support direct IAM integration, then download, install, and configure the OCI CLI. For more information about installing and configuring the OCI CLI, see Quickstart.
Set up an API key as part of the OCI CLI configuration and select default values.
1. Set up the API key access for the IAM user.
2. Retrieve the db-token. For example:
  - Retrieving a db-token with an API-key using the OCI CLI:
```
oci iam db-token get
```
  - Retrieving a db-token with a security (or session) token:
```
oci iam db-token get --auth security_token
```
    If the security token has expired, a window will appear so the user can log in to OCI again. This generates the security token for the user. OCI CLI will use this refreshed token to get the db-token.
  - Retrieving a db-token with a delegation token: When you log in to the cloud shell, the delegation token is automatically generated and placed in the /etc directory. To get this token, execute the following command in the OCI CLI:
```
oci iam db-token get
```
  - Retrieving an instance token by using the OCI CLI:
```
oci iam db-token get --auth instance_principal
```
For more information,see Required Keys and OCIDs.
This configuration only works with the Oracle Database 19c client. Ensure that you are using the latest release updates for this client.

Note:
Oracle Database client release 21c offers limited IAM token features.
Follow the existing process to download the wallet from the database and then follow the directions for configuring it for use with SQL*Plus.
1. Confirm that DN matching is enabled by looking for SSL_SERVER_DN_MATCH=ON in sqlnet.ora.
2. Configure the database client to use the IAM token by adding TOKEN_AUTH=OCI_TOKEN to the sqlnet.ora file. Because you will be using the default locations for the database token file, you do not need to include the token location.
The TOKEN_AUTH and TOKEN_LOCATION values in the tnsnames.ora connect strings take precedence over the sqlnet.ora settings for that connection. For example, for the connect string, assuming that the token is in the default location (~/.oci/db-token for Linux):
```
(description= 
  (retry_count=20)(retry_delay=3)
  (address=(protocol=tcps)(port=1522)
  (host=example.us-phoenix-1.oraclecloud.com))
  (connect_data=(service_name=aaabbbccc_exampledb_high.example.oraclecloud.com))
  (security=(ssl_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com, 
     OU=Oracle BMCS US, O=Example Corporation, 
     L=Redwood City, ST=California, C=US")
  (TOKEN_AUTH=OCI_TOKEN)))
```

After the connect string is updated with the TOKEN_AUTH parameter, the IAM user can log in to the database instance by running the following command to start SQL*Plus. You can include the connect descriptor itself or use the name of the descriptor from the tnsnames.ora file.

connect /@exampledb_high

or:

connect /@(description= 
  (retry_count=20)(retry_delay=3)
  (address=(protocol=tcps)(port=1522)
  (host=example.us-phoenix-1.oraclecloud.com))
  (connect_data=(service_name=aaabbbccc_exampledb_high.example.oraclecloud.com))
  (security=(ssl_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com, 
     OU=Oracle BMCS US, O=Example Corporation, 
     L=Redwood City, ST=California, C=US")
  (TOKEN_AUTH=OCI_TOKEN)))

The database client is already configured to get a db-token because TOKEN_AUTH has already been set, either through the sqlnet.ora file or in a connect string. The database client gets the db-token and signs it using the private key and then sends the token to the database. If an IAM user name and IAM database password are specified instead of slash /, then the database client will connect using the password instead of using the db-token unless another parameter is specified: PASSWORD_AUTH = OCI_TOKEN. This directs the database client to get the token from IAM using the IAM username and IAM database password. In addition to setting PASSWORD_AUTH, you will also need to set OCI_IAM_URL, OCI_TENANCY and optionally OCI_COMPARTMENT and OCI_DATABASE.

Use Instance Principal to Access Database with IAM Authentication

After the ADMIN user enables OCI IAM on the database, an application can access the database through an OCI IAM database token using an instance principal.

For more information, see Accessing the Oracle Cloud Infrastructure API Using Instance Principals.

Configure Proxy Authentication

Proxy authentication allows an IAM user to proxy to a database schema for tasks such as application maintenance.

Proxy authentication is typically used to authenticate the real user and then authorize them to use a database schema with the schema privileges and roles in order to manage an application. Alternatives such as sharing the application schema password are considered insecure and unable to audit which actual user performed an action.

A use case can be in an environment in which a named IAM user who is an application database administrator can authenticate by using their credentials and then proxy to a database schema user (for example, hrapp). This authentication enables the IAM administrator to use the hrapp privileges and roles as user hrapp in order to perform application maintenance, yet still use their IAM credentials for authentication. An application database administrator can sign in to the database and then proxy to an application schema to manage this schema.

You can configure proxy authentication for both the password authentication and token authentication methods.

Configuring Proxy Authentication for the IAM User

To configure proxy authentication for an IAM user, the IAM user must already have a mapping to a global schema (exclusive or shared mapping). A separate database schema for the IAM user to proxy to must also be available.

After you ensure that you have this type of user, alter the database user to allow the IAM user to proxy to it.

Log in to the database instance as a user who has the ALTER USER system privileges.
Grant permission for the IAM user to proxy to the local database user account. An IAM user cannot be referenced in the command so the proxy must be created between the database global user (mapped to the IAM user) and the target database user.In the following example, hrapp is the database schema to proxy to, and peterfitch_schema is the database global user exclusively mapped to user peterfitch.
```
ALTER USER hrapp GRANT CONNECT THROUGH peterfitch_schema;
```

At this stage, the IAM user can log in to the database instance using the proxy. For example:

To connect using a password verifier:

CONNECT peterfitch[hrapp]@connect_string
Enter password: password

To connect using a token:

CONNECT [hrapp]/@connect_string

Validating the IAM User Proxy Authentication

You can validate the IAM user proxy configuration for both password and token authentication methods.

Log in to the database instance as a user who has the CREATE USER and ALTER USER system privileges.

Connect at the IAM user and execute the SHOW USER and SELECT SYS_CONTEXT commands. For example, suppose you want to check the proxy authentication of the IAM user peterfitch when they proxy to database user hrapp. You will need to connect to the database using the different types of authentication methods shown here, but the output of the commands that you execute will be the same for all types.

For password authentication, assuming the IAM user is in the default domain:

CONNECT peterfitch[hrapp]/password\!@connect_string
SHOW USER;
--The output should be USER is "HRAPP"
SELECT SYS_CONTEXT('USERENV','AUTHENTICATION_METHOD') FROM DUAL;
--The output should be "PASSWORD_GLOBAL_PROXY"
SELECT SYS_CONTEXT('USERENV','PROXY_USER') FROM DUAL;
--The output should be "PETERFITCH_SCHEMA"
SELECT SYS_CONTEXT('USERENV','CURRENT_USER') FROM DUAL;
--The output should be "HRAPP"

For token authentication, for a user who is in a non-default domain, sales_domain:

CONNECT [hrapp]/@connect_string
SHOW USER;
--The output should be USER is "HRAPP "
SELECT SYS_CONTEXT('USERENV','AUTHENTICATION_METHOD') FROM DUAL;
--The output should be "TOKEN_GLOBAL_PROXY"
SELECT SYS_CONTEXT('USERENV','PROXY_USER') FROM DUAL;
--The output should be "PETERFITCH_SCHEMA"
SELECT SYS_CONTEXT('USERENV','CURRENT_USER') FROM DUAL;
--The output should be "HRAPP"

Use Database Link with IAM Authenticated Users

You can use a database link to connect from one database instance to another as an OCI IAM user.

You can use either connected user or fixed user database link to connect to a database as an OCI IAM user.

Note:

Current user database link is not supported for connecting to a database in Base Database Service as an OCI IAM user.

Connected User Database Link: For a connected user database link, an IAM user must be mapped to a schema in both the source and target databases connected by a database link. You can use a database password verifier or an IAM database token to use a connected user database link.
Fixed User Database Link: A fixed user database link can be created using a database user or an IAM user. When using an IAM user as a fixed user database link, the IAM user must have a schema mapping in the target database. The IAM user for a database link can be configured with a password verifier only.

Disable IAM Authentication

You can disable IAM user access on your database instance using the ALTER SYSTEM command as shown below:

ALTER SYSTEM RESET IDENTITY_PROVIDER_TYPE SCOPE=BOTH;

If you also want to update access to IAM from the resource, you may need to remove or modify the IAM group and the policies you set up to allow access to IAM from those resources.