Using Centralized Oracle Cloud Infrastructure Services for Net Naming and Secrets

You can use the Oracle Cloud Infrastructure (OCI) object store and vault to centrally store net names and secrets.

This functionality is currently supported with the JDBC-thin and .NET-thin drivers.

See the following guides:

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.

Client Connections That Use a Token Requested by an IAM User Name and Database Password

You can create a client connection that uses a token requested by an IAM user name and database password.

About Client Connections That Use a Token Requested by an IAM User Name and Database Password

IAM users can connect to the Oracle DBaaS instance by using an IAM token that was retrieved using an IAM user name and IAM database password.

In both cases, the token is retrieved by using a database password, either by using SQL*Plus or through a SEPS.

In previous releases, you could only use the IAM user name and database password to get a password verifier from IAM. Getting a token with these credentials is more secure than getting a password verifier because a password verifier is considered sensitive. Using a token means that you do not need to pass or use the verifier. Applications cannot pass a token that was retrieved by the IAM user name and password through the database client API. Only the database client can retrieve this type of token. A database client can only retrieve a database token using the IAM user name and IAM database password.

You can enter the IAM username and IAM database password directly into the tool or use a SEPS wallet to hold these credentials securely.

Parameters to Set for Client Connections That Use a Token Requested by an IAM User Name and Database Password

To set these parameters, you modify either the sqlnet.ora file or the tnsnames.ora file.

Token-Specific Parameters for IAM User Name and Database Password Token Requests

DN-Specific Parameters for IAM User Name and Database Password Token Requests

Note: To bring Oracle parameters in accord with the actual encryption and authentication methods for network connections, Oracle is deprecating all connect parameters prefixed with SSL_ in favor of parameters prefixed with TLS_. During this deprecation period, if both the TLS_ and SSL_ versions of a parameter are configured, then the SSL_ version is ignored.

sqlnet.ora Example

PASSWORD_AUTH=OCI_TOKEN
OCI_IAM_URL=https://auth.region1.example.com/v1/actions/generateScopedAccessBearerToken
OCI_TENANCY=ocid1.tenancy..12345
OCI_COMPARTMENT=ocid1.compartment.region1..12345
OCI_DATABASE=ocid1.autonomousdatabase.oc1.iad.12345
TLS_SERVER_CERT_DN="C=US,O=ExampleCorporation,CN=sslserver2"
TLS_SERVER_DN_MATCH=TRUE

tnsnames.ora Example

db_connection=
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=tcps)(HOST=sales1-svr)(PORT=5678))
    (SECURITY=
      (PASSWORD_AUTH=OCI_TOKEN)
      (OCI_IAM_URL=https://auth.region1.example.com/v1/actions/generateScopedAccessBearerToken)
      (OCI_TENANCY=ocid1.tenancy..12345)
      (OCI_COMPARTMENT=ocid1.compartment.region1..12345)
      (OCI_DATABASE=ocid1.autonomousdatabase.oc1.iad.12345)
      (TLS_SERVER_CERT_DN="C=US,O=ExampleCorporation,CN=sslserver2")
      (TLS_SERVER_DN_MATCH=TRUE))
    (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

In this specification:

Configuring the Database Client to Retrieve a Token Using an IAM User Name and Database Password

You can configure the database client to retrieve the IAM database token using the provided IAM user name and IAM database password.

  1. Log in to the Oracle DBaaS client.

  2. Set the appropriate parameters to retrieve a token that will be requested by an IAM user name and database password.

  3. In the sqlnet.ora file, set the WALLET_LOCATION parameter to the location of the client. The root certificates will reside in this directory.

    For example:

    WALLET_LOCATION =
  (SOURCE=
    (METHOD=FILE)
      (METHOD_DATA=
        DIRECTORY=/ora_db/wallet)

Related Topics

Configuring a Secure External Password Store Wallet to Retrieve an IAM Token

You can enable an IAM user name and a secure external password store (SEPS) to request the IAM database token.

  1. Log in to the Oracle DBaaS client.

  2. Configure this client to use the secure external password store.

  3. Set the appropriate parameters to retrieve a token that will be requested by an IAM user name and database password.

Related Topics

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

For IAM token access to the Oracle AI 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:

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.

Related Topics

TLS Connections without Client Wallets

The use of Transport Layer Security (TLS) connections without client wallets is supported for IAM connections.

Before you configure this type of connection, ensure that the Oracle DBaaS environment meets the requirements.

Related Topics

Enabling Clients to Directly Retrieve IAM Tokens

You can set parameters to enable clients to directly retrieve IAM tokens on their own.

This feature is available in environments that use JDBC-thin clients, ODP.NET Core classes, or ODP.NET Managed Driver classes. It enables the client to display a dialog box to prompt for the user’s authentication. To enable this feature, you must set the following parameters in either the client’s sqlnet.ora file or in a connect string. The connect string takes precedence over sqlnet.ora.

Parameter Description
OCI_INTERACTIVE setting in TOKEN_AUTH Set this to OCI_INTERACTIVE to signal the database client to retrieve the db-token directly from OCI IAM.
TOKEN_AUTH=OCI_INTERACTIVE
OCI_CONFIG_FILE Specifies the location of the Oracle Cloud Infrastructure (OCI) configuration file that contains the user’s client connection information.
If you do not set this parameter, then Oracle Database searches for this configuration file in ` C:/user_profile/.oci/config`. If the configuration file is not in that location, then Oracle Database prompts the user for a region ID, presenting a list of region IDs from which the user can choose.
OCI_PROFILE Specifies the default user profile that is set in the OCI configuration file.

Common Database Client Configurations

IAM users can connect to the Oracle DBaaS instance using client tools such as SQLcl on a laptop.

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 Oracle AI 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 Oracle AI 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"

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.

  1. Ensure you have an IAM user account.

  2. 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.

  3. 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.

  4. Ensure that you are using the latest release updates for the Oracle Database client releases 19c, 21c, or 26ai.

    This configuration only works with the Oracle Database client release 19c, 21c, or 26ai.

  5. Follow the existing process to download the wallet from the Oracle AI Database and then follow the directions for configuring it for use with SQL*Plus.

    1. Confirm that DN matching is enabled by looking for TLS_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=(tls_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 Oracle AI 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=(tls_server_cert_dn="CN=example.uscom-east-1.oraclecloud.com,
     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 Oracle AI 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.

Using OCI Object Store for Network Service Configuration Information

You can store connect string and other network configuration information in the OCI Object Store.

See OCI Object Storage JSON File in the Oracle AI Database Net Services Administrator’s Guide for more information.