Connect to Autonomous Database with Identity and Access Management (IAM) Authentication

After the ADMIN user enables Oracle Cloud Infrastructure IAM on Autonomous Database, users log in to the Autonomous Database instance using their Oracle Cloud Infrastructure IAM credentials or access the database through an Oracle Cloud Infrastructure IAM database token.

After you enable Oracle Cloud Infrastructure IAM user access, you can also log in to the Autonomous Database using your local database account username and password (non-global database user account).

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

Alternatively, you can use an Oracle Cloud Infrastructure IAM database token to access an Autonomous Database instance. Using IAM tokens requires the latest Oracle Database client 19c (at least 19.16). Some earlier clients (19c and 21c) provide a limited set of capabilities for token access. Oracle Database client 21c does not fully support the IAM token access feature.

The following examples show password verifier with SQL*Plus to access the database with an Oracle Cloud Infrastructure IAM username and password and the steps required to use SQL*Plus with an Oracle Cloud Infrastructure IAM database token.

Note:

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

You can use an Oracle Cloud Infrastructure IAM database token to access an Autonomous Database instance with supported clients, including the following:

JDBC-Thin with support for IAM Token Authentication is supported with the following:
- JDBC version 19.13.0.0.1 (or later): See JDBC and UCP Downloads for JDBC drivers.
- JDBC version 21.4.0.0.1 (or later): See JDBC and UCP Downloads for JDBC drivers.
See Support for IAM Token-Based Authentication for more information:
SQL*Plus and Oracle Instant Client: Supported with SQL*Plus and Instant Client on Linux versions 19.13 or later, and Instant Client on Linux versions 21.4 or later.
See Identity and Access Management (IAM) Token-Based Authentication for more information.
The database client can also be configured to retrieve a database token using the IAM username and IAM database password.

See Client Connections That Use a Token Requested by an IAM User Name and Database Password for more information.
.NET clients (latest version of Linux or Windows). .NET software components are available as a free download from the following sites:

About Connecting to an Autonomous Database Instance Using IAM
IAM users can connect to the Autonomous Database instance by using either an IAM database password verifier or an IAM token.
Configuring a Client Connection for SQL*Plus That Uses an IAM Database Password
You can configure SQL*Plus to use an IAM database password.
Configuring a Client Connection for SQL*Plus That Uses an IAM Token
You can configure a client connection for SQL*Plus that uses an IAM token.
Use Instance Principal to Access Autonomous Database with Identity and Access Management (IAM) Authentication
After the ADMIN user enables Oracle Cloud Infrastructure IAM on Autonomous Database, an application can access the database through an Oracle Cloud Infrastructure IAM database token using an instance principal.

Parent topic: Use Identity and Access Management (IAM) Authentication with Autonomous Database

About Connecting to an Autonomous Database Instance Using IAM

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

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

The second connection method, the use of an IAM token for the database, is more modern. The use of token-based access is a better fit for Cloud resources such as Autonomous Database. 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.
Client Connections That Use a Token Requested by a Client Application or Tool
For IAM token access to the Autonomous Database, the client application or tool requests a database token from IAM for the IAM user.

Parent topic: Connect to Autonomous Database with Identity and Access Management (IAM) Authentication

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 Oracle Cloud Infrastructure (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 OCI DBaaS instance.

Parent topic: About Connecting to an Autonomous Database Instance Using IAM

Client Connections That Use a Token Requested by a Client Application or Tool

For IAM token access to the Autonomous 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 Oracle Cloud Infrastructure (OCI) command line interface (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
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 Oracle Cloud Infrastructure services
Using an IAM user name and IAM database password (can only be requested by 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. The instructions in this guide 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: SQLPlus on-premises, SQLcl on-premises, SQL*Plus in Cloud Shell, or applications that use SEP wallets.

Parent topic: About Connecting to an Autonomous Database Instance Using IAM

Configuring 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 Autonomous Database instance 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 an Autonomous 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"
```

Parent topic: Connect to Autonomous Database with Identity and Access Management (IAM) Authentication

Configuring a Client Connection for SQL*Plus That Uses an IAM Token

You can 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 an Oracle 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. (See OCI Command Line Interface 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 Oracle Cloud Infrastructure (OCI) command-line interface:
```
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, run the following command in the cloud shell:
```
oci iam db-token get
```
  - Retrieving an instance token by using the OCI command-line interface:
```
oci iam db-token get --auth instance_principal
```
3. The database client can also be configured to retrieve a database token using the IAM username and IAM database password.
  
  See Client Connections That Use a Token Requested by an IAM User Name and Database Password for more information.
See Required Keys and OCIDs for more information.
Ensure that you are using the latest release updates for the Oracle Database client releases 19c and 21c.
This configuration only works with the Oracle Database client release 19c or 21c.
Follow the existing process to download the wallet from the Autonomous 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.
  
  Note:
  Partial or full DN matching is required when sending a token from the database client to Autonomous Database. If Autonomous Database is using a private endpoint, you need to specify a host value for the connect string parameter. Using an IP address for the host parameter in the connect string will not work with DN matching and the IAM token will not be sent to the database.
  See Private Endpoints Configuration Examples on Autonomous Database for configuration information on how to set the host parameter when using a private endpoint.
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_dn_match=yes))
  (TOKEN_AUTH=OCI_TOKEN)))
```

After the connect string is updated with the TOKEN_AUTH parameter, the IAM user can log in to the Autonomous 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 Autonomous 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.

Parent topic: Connect to Autonomous Database with Identity and Access Management (IAM) Authentication

Use Instance Principal to Access Autonomous Database with Identity and Access Management (IAM) Authentication

After the ADMIN user enables Oracle Cloud Infrastructure IAM on Autonomous Database, an application can access the database through an Oracle Cloud Infrastructure IAM database token using an instance principal.

See Accessing the Oracle Cloud Infrastructure API Using Instance Principals for more information.

Parent topic: Connect to Autonomous Database with Identity and Access Management (IAM) Authentication