1. Database Net Services Administrator's Guide
  2. Configuration and Administration of Oracle Net Services
  3. Configuring Naming Methods

8 Configuring Naming Methods

Find out how to configure connectivity information for client connections to the database server.

  • Configuring the Local Naming Method
    The local naming method adds network service names to the tnsnames.ora file. Each network service name maps to a connect descriptor.
  • Configuring the Directory Naming Method
    With this naming method, connect identifiers are mapped to connect descriptors contained in an LDAP-compliant directory server, such as Oracle Internet Directory, Oracle Unified Directory, or Microsoft Active Directory.
  • Configuring the Centralized Configuration Provider Naming Method
    With this naming method, connect identifiers are mapped to connect descriptors contained in a Centralized Configuration Provider, such as Azure App Configuration store or Oracle Cloud Infrastructure (OCI) Object Storage as a JSON file.
  • Configuring the Easy Connect Naming Method
    The Easy Connect naming method eliminates the need for service name lookup in tnsnames.ora files for TCP/IP environments. In fact, no naming or directory system is required when using this method.

Related Topics

Parent topic: Configuration and Administration of Oracle Net Services

8.1 Configuring the Local Naming Method

The local naming method adds network service names to the tnsnames.ora file. Each network service name maps to a connect descriptor.

The following example shows the network service name sales mapped to the connect descriptor contained in DESCRIPTION. The DESCRIPTION section contains the protocol address and identifies the destination database service. In this example, the protocol is TCP/IP and the port is 1521.

Example 8-1 Connector Descriptor with Host Name

sales=
(DESCRIPTION= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA= 
     (SERVICE_NAME=sales.us.example.com)))

The following example shows a valid tnsnames.ora entry to connect to a host identified with an IPv6 address and a port number of 1522.

Example 8-2 Connect Descriptor with IPv6 Address

salesdb =
  ( DESCRIPTION =
    ( ADDRESS=(PROTOCOL=tcp)(HOST=2001:0db8:1:1::200C:417A)(PORT=1522) )
    ( CONNECT_DATA = 
        (SERVICES_NAME=sales.example.com) )
  )

You can configure local naming during or after installation, as described in the following sections:

Related Topics

Parent topic: Configuring Naming Methods

8.1.1 Configuring the tnsnames.ora File During Installation

Oracle Net Configuration Assistant enables you to configure network service names for clients. Oracle Universal Installer launches Oracle Net Configuration Assistant after software installation. The configuration varies depending on the installation mode.

  • Administrator or runtime installation: Oracle Net Configuration Assistant prompts you to configure network service names in the tnsnames.ora file to connect to an Oracle Database service.

  • Custom installation: Oracle Net Configuration Assistant prompts you to select naming methods to use. If local is selected, then Oracle Net Configuration Assistant prompts you to configure network service names in the tnsnames.ora file to connect to an Oracle Database service.

Parent topic: Configuring the Local Naming Method

8.1.2 Configuring the tnsnames.ora File After Installation

You can add network service names to the tnsnames.ora file at any time after installation.

To configure the local naming method, perform the following tasks:

Note:

The underlying network connection must be operational before attempting to configure connectivity with Oracle Net.

Task 1   Configure Net Services Names

To configure the network services names, use one of the following methods:

Each method provides similar functionality. However, Oracle Net Manager has more configuration options for the sqlnet.ora file.

  • Net Services Names Configuration using Oracle Enterprise Manager Cloud Control

    The following procedure describes how to configure network service names in the tnsnames.ora file with Oracle Enterprise Manager Cloud Control:

    1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control.

      See Also:

      "Accessing the Net Services Administration Page"

    2. Select Local Naming from the Administer list, and then select the Oracle home that contains the location of the configuration files.

    3. The Local Naming page appears. You may be prompted to log in to the database server.

    4. Click Create Like.

      The Create Net Service Name page appears.

    5. Enter a name in the Net Service Name field.

      You can qualify the network service name with the client's domain. The network service name is automatically domain qualified if the sqlnet.ora file parameter NAMES.DEFAULT_DOMAIN is set.

      See Also:

      "About the Default Domain for Clients"

    6. In the Database Information section, configure service support as follows:

      1. Enter a destination service name.

        See Also:

        "About Connect Descriptors" for additional information about the service name string to use

      2. Select a database connection type.

        The default setting of Database Default is recommended for the connection type. If dedicated server is configured in the initialization parameter file, then you can select Dedicated Server to force the listener to spawn a dedicated server, bypassing shared server configuration. If shared server is configured in the initialization parameter file and you want to guarantee the connection always uses shared server, then select Shared Server.

        See Also:

        "Configuring a Shared Server Architecture " for additional information about shared server configuration

    7. In the Addresses section, configure protocol support, as follows:

      1. Click Add.

        The Add Address page appears.

      2. From the Protocol list, select the protocol on which the listener is configured to listen. This protocol must also be installed on the client.

      3. Enter the appropriate parameter information for the selected protocol in the fields provided.

        See Also:

        Oracle Database Net Services Reference for additional information about protocol parameter settings

      4. (Optional) In the Advanced Parameters section, specify the I/O buffer space limit for send and receive operations of sessions in the Total Send Buffer Size and Total Receive Buffer Size fields.

        See Also:

        "Configuring I/O Buffer Space " for additional information about buffer space

      5. Click OK.

        The protocol address is added to the Addresses section.

    8. Click OK to add the network service name.

      The network service name is added to the Local Naming page.

    9. Select connect-time failover and client load balancing option for the addresses.

    10. Click OK.

    See Also:

  • Net Services Names Configuration using Oracle Net Manager

    The following procedure describes how to configure network service names in the tnsnames.ora file with Oracle Net Manager:

    1. Start Oracle Net Manager.

      See Also:

      "Using Oracle Net Manager to Configure Oracle Net Services"

    2. In the navigator pane, select Service Naming from Local.

    3. Click the plus sign (+) from the toolbar, or select Create from the Edit menu.

      The Welcome page of the Net Service Name wizard appears.

    4. Enter a name in the Net Service Name field.

      You can qualify the network service name with the client's domain. The network service name is automatically domain qualified if the sqlnet.ora file parameter NAMES.DEFAULT_DOMAIN is set.

      See Also:

      "About the Default Domain for Clients"

    5. Click Next.

      The Protocol page appears.

    6. Select the protocol on which the listener is configured to listen. The protocol must also be installed on the client.

    7. Click Next.

      The Protocol Settings page appears.

    8. Enter the appropriate parameter information for the selected protocol in the fields provided.

      See Also:

      Oracle Database Net Services Reference for additional information about protocol parameter settings

    9. Click Next.

      The Service page appears.

    10. Enter a destination service name, and optionally, select a database connection type.

      Oracle recommends that you use the default setting of Database Default for the connection type. If dedicated server is configured in the initialization parameter file, then you can select Dedicated Server to force the listener to spawn a dedicated server, bypassing shared server configuration. If shared server is configured in the initialization parameter file and you want to guarantee the connection always uses shared server, then select Shared Server.

      See Also:

    11. Click Next.

      The Test page appears.

    12. Click Test to verify that the network service name works, or click Finish to dismiss the Net Service Name wizard.

      If you click Test, then Oracle Net connects to the database server by using the connect descriptor information you configured. Therefore, the listener and database must be running for a successful test. If they are not, then see "Starting Oracle Net Listener and the Oracle Database Server" to start components before testing. During testing, a Connection Test dialog box appears, providing status and test results. A successful test results in the following message: 

      The connection test was successful.

      If the test was successful, then click Close to close the Connect Test dialog box, and proceed to Step 13.

      If the test was not successful, then do the following:

      1. Ensure that the database and listener are running, and then click Test.

      2. Click Change Login to change the user name and password for the connection, and then click Test.

    13. Click Finish to close the Net Service Name wizard.

    14. Select Save Network Configuration from the File menu.

      See Also:

  • Net Services Names Configuration using Oracle Net Configuration Assistant

    The following procedure describes how to configure network service names in the tnsnames.ora file with Oracle Net Configuration Assistant:

    1. Start Oracle Net Configuration Assistant.

      See Also:

      "Using Oracle Net Configuration Assistant to Configure Network Components"

      The Welcome page appears.

    2. Select Local Net Service Name Configuration, and then click Next.

      The Net Service Name Configuration page appears.

    3. Click Add, and then click Next.

      The Service Name Configuration page appears.

    4. Enter a service name in the Service Name field.

    5. Click Next.

    6. Follow the prompts in the wizard and online help to complete network service name creation.

Task 2   Configure Local Naming as the First Naming Method

Configure local naming as the first method specified in the NAMES.DIRECTORY_PATH parameter in the sqlnet.ora file. This parameter specifies the order of naming methods Oracle Net uses to resolve connect identifiers to connect descriptors.

To configure the local naming method as the first naming method, use one of the following methods:

Each method provides the same functionality.

Local Naming Configuration using Oracle Enterprise Manager Cloud Control

The following procedure describes how to specify local naming as the first naming method using Oracle Enterprise Manager Cloud Control:

  1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control.

    See Also:

    "Accessing the Net Services Administration Page"

  2. Select Network Profile from the Administer list.

  3. Click Go.

  4. Select Naming Methods.

  5. Select TNSNAMES from the Available Methods list.

  6. Click Move to move the selection to the Selected Methods list.

  7. Use the Promote button to move TNSNAMES to the top of the list.

  8. Click OK.

Local Naming Configuration using Oracle Net Manager

The following procedure describes how to specify local naming as the first naming method using Oracle Net Manager:

  1. Start Oracle Net Manager.

    See Also:

    "Using Oracle Net Manager to Configure Oracle Net Services"

  2. In the navigator pane, select Profile from the Local menu.

  3. From the list in the right pane, select Naming.

  4. Click the Methods tab.

  5. From the Available Methods list, select TNSNAMES, and then click the right-arrow button.

  6. From the Selected Methods list, select TNSNAMES, and then use the Promote button to move the selection to the top of the list.

  7. Choose Save Network Configuration from the File menu.

    The sqlnet.ora file updates with the NAMES.DIRECTORY_PATH parameter, listing tnsnames first: 

    NAMES.DIRECTORY_PATH=(tnsnames, EZCONNECT)
Task 3   Copy the Configuration to the Other Clients

After one client is configured, copy the tnsnames.ora and sqlnet.ora configuration files to the same location on the other clients. This ensures that the files are consistent. Alternatively, you can use Oracle Net Assistant on every client.

Task 4   Configure the Listener

Ensure that the listener located on the server is configured to listen on the same protocol address configured for the network service name. By default, the listener is configured for the TCP/IP protocol on port 1521.

See Also:

Configuring and Administering Oracle Net Listener for listener configuration details

Task 5   Connect to the Database

Clients can connect to the database using the following syntax:

CONNECT username@net_service_name

Parent topic: Configuring the Local Naming Method

8.2 Configuring the Directory Naming Method

With this naming method, connect identifiers are mapped to connect descriptors contained in an LDAP-compliant directory server, such as Oracle Internet Directory, Oracle Unified Directory, or Microsoft Active Directory.

A directory provides central administration of database services and network service names, making it easier to add or relocate services.

You can specify the protocol-specific and directory usage parameters either in external configuration files (such as ldap.ora and sqlnet.ora) or directly in a database client connection identifier.

Parent topic: Configuring Naming Methods

8.2.1 Configure Net Service Name, Database Service, and Alias Entries

You can use Oracle Enterprise Manager Cloud Control and Oracle Net Manager to configure network service names, network service alias entries, and database service entries. Clients can use these entries to connect to the database.

  1. Verify Directory Compatibility:

    On the computer from which you plan to create network service names, do the following verification steps:

    1. Ensure the computer has the latest release of Oracle Net Services software. The release information is located in the About Net Manager option on the help menu.
    2. Run Oracle Internet Directory Configuration Assistant to verify directory server, Oracle Context, and Oracle schema releases.
  2. Create Net Service Names in the Directory:

    You can configure clients to use a network service name rather than the database service entry.

    Note:

    1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control. See Accessing the Net Services Administration Page.
    2. Select Directory Naming from the Administer list, and then select the Oracle home that contains the location of the directory server.
    3. Click Go.

      The Directory Naming page appears.

    4. Click the Net Service Names tab.
    5. In the Results section, click Create.

      The Create Net Service Name page with the General tab appears.

    6. Enter a name in the Net Service Name field.
    7. In the Database Information section, configure service support, as follows:

      1. Enter a destination service name. See About Connect Descriptors.

      2. Select a database connection type. Oracle recommends that you use the Database Default for the connection type. If a shared server is configured in the initialization parameter file, then the following options are available:

        • Select Dedicated Server to force the listener to spawn a dedicated server, and bypass shared server configuration.

        • Select Shared Server to guarantee the connection always uses shared server.

        See Configuring a Shared Server Architecture.

    8. In the Addresses section, configure protocol support:

      1. Click Add.

        The Add Address page appears.

      2. From the Protocol list, select the protocol that the listener is configured to listen. This protocol must also be installed on the client.

      3. Enter the appropriate parameter information for the selected protocol in the fields provided.

        See Oracle Database Net Services Reference.

        Note:

        Optionally, you can specify LDAP parameters directly in the connect identifier, instead of configuring the sqlnet.ora file. See Specify LDAP Parameters Directly in a Connect Identifier.

      4. (Optional) In the Advanced Parameters section, specify the I/O buffer space limit for send and receive operations of sessions in the Total Send Buffer Size and Total Receive Buffer Size fields. See Configuring I/O Buffer Space.

      5. Click OK.

        The protocol address is added to the Addresses section.

    9. Click OK to add the network service name.

      The network service name is added to the Results section of the Net Service Names tab.

      See Creating a List of Listener Protocol Addresses to configure multiple protocol addresses. See About the Advanced Connect Data Parameters to configure additional CONNECT_DATA options.

  3. Create or Modify Connectivity Information for Database Service Entries:

    A database service entry is created during installation. When database registration with the directory naming completes, a database service entry is created in the directory. By default, this entry contains network route information with the location of the listener through a protocol address. You can re-create this information or modify the existing network route information.

    Note:

    Only users that are members of the OracleNetAdmins or OracleContextAdmins group can modify network information for a database service in a directory. To add or remove users from these groups, see Who Can Add or Modify Entries in the Directory Server.

    1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control. See Accessing the Net Services Administration Page.
    2. Select Directory Naming from the Administer list, and then select the Oracle home that contains the location of the directory server.
    3. Click Go. You may be prompted to log in to the database server and the directory server.

      The Directory Naming page appears.

    4. Click the Database Services tab.
    5. In the Simple Search section, select Oracle Context and search criteria to see the network service names for Oracle Context.

      The database service names display in the Results section.

    6. In the Results section, select a database service, and then click Edit.
  4. Create Net Services Aliases:

    Net service aliases in a directory server enable clients to refer to a database service or a network service name by an alternative name. For example, a network service alias of salesalias can be created for a network service name of sales. When salesalias is used to connect to a database, as in CONNECT scott@salesalias, it resolves to and use the connect descriptor information for sales.

    There are two main uses of network service aliases:

    • Use a network service alias as a way for clients to refer to a database service or network service name by another name.

    • Use a network service alias in one Oracle Context for a database service or network service name in a different Oracle Context. This enables a database service or network service name to be defined once in the directory server, and referred to by clients that use other Oracle Contexts. See Understanding Net Service Alias Entries for an overview of network service aliases.

    Note:

    • Only users that are members of either the OracleNetAdmins or OracleContextAdmins group can create or modify network service alias entries in a directory. To add or remove users from the OracleNetAdmins group, see Who Can Add or Modify Entries in the Directory Server.

    • Net service aliases are not supported by Microsoft Active Directory.

    • Ensure the NLS_LANG environment variable is set for the clients when using network service aliases.

    To create a network service alias, use one of the following methods. Each method provides similar functionality:

    • Network Service Alias Configuration using Oracle Enterprise Manager Cloud Control

      The following procedure describes how to configure a network service alias using Oracle Enterprise Manager Cloud Control:

      1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control. See Accessing the Net Services Administration Page.

      2. Select Directory Naming from the Administer list, and then select the Oracle home that contains the location of the directory server.

      3. Click Go.

        The Directory Naming page appears.

      4. Click the Net Service Aliases tab.

      5. In the Results section, click Create.

        The Create Net Service Alias page appears.

      6. Enter a name for the alias in the Net Service Alias Name field.

      7. In the Referenced Service Detail section, enter the following information in the fields:

        • Oracle Context: Select the Oracle Context of the database service or network service name from the list or enter one in the field.

        • Referenced Service Name: Select the DN of the database service or network service name.

      8. Click OK to add the network service alias.

        The network service alias is added to the Directory Naming page.

    • Network Service Alias Configuration using Oracle Net Manager

      The following procedure describes how to configure a network service alias using Oracle Net Manager:

      1. Start Oracle Net Manager. See Using Oracle Net Manager to Configure Oracle Net Services.

      2. In the navigator pane, select Service Naming from Directory.

      3. Select Aliases.

      4. Select Create from the Edit menu.

      5. Enter the network service alias in the Net Service Alias field.

      6. Select Oracle Context and name.

      7. Click Create.

      8. Select Save Network Configuration from the File menu.

  5. Configure LDAP as the First Naming Method for Client Lookups:

    Configure directory naming as the first method to be used in the NAMES.DIRECTORY_PATH parameter in the sqlnet.ora file. This parameter specifies the order of naming methods Oracle Net uses to resolve connect identifiers to connect descriptors.

    To configure LDAP as the first naming method you can use one of the following methods:

    • LDAP Configuration using Oracle Enterprise Manager Cloud Control

      The following procedure describes how to specify directory naming as the first naming method using Oracle Enterprise Manager Cloud Control:

      1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control. See Accessing the Net Services Administration Page.

      2. Select Network Profile from the Administer list.

      3. Click Go.

      4. Select Naming Methods.

      5. Select LDAP from the Available Methods list.

      6. Click Move to move the selection to the Selected Methods list.

      7. Use the Promote button to move LDAP to the top of the list.

      8. Click OK.

    • LDAP Configuration using Oracle Net Manager

      The following procedure describes how to specify directory naming as the first naming method using Oracle Net Manager:

      1. Start Oracle Net Manager. See Using Oracle Net Manager to Configure Oracle Net Services.

      2. In the navigator pane, select Profile from the Local menu.

      3. From the list in the right pane, select Naming.

      4. Click the Methods tab.

      5. From the Available Methods list, select LDAP, and then click the right-arrow button.

      6. From the Selected Methods list, select LDAP, and then use the Promote button to move the selection to the top of the list.

      7. Select Save Network Configuration from the File menu.

        The sqlnet.ora file updates with the NAMES.DIRECTORY_PATH parameter, listing ldap first, such as the following: 

        NAMES.DIRECTORY_PATH=(ldap, tnsnames, hostname)
  6. Configure the Listener:

    Ensure that the listener located on the server is configured to listen on the same protocol address configured for the network service name. By default, the listener is configured to listen on the TCP/IP protocol, port 1521. See Configuring and Administering Oracle Net Listener for listener configuration details.

  7. Connect to the Database:

    Clients that are configured with a default directory entry that matches the directory location of the database service or network service name can connect to the database using the following syntax:

    CONNECT username@connect_identifier

    Clients that are configured with a default directory entry that does not match the entry's directory location must use the entry's distinguished name or its fully-qualified name. See Understanding the Directory Information Tree for fully-qualified name usage.

Parent topic: Configuring the Directory Naming Method

8.2.2 Create Multiple Default Contexts in a Directory Naming Server

To enable multiple default contexts, define the orclCommonContextMap with a list of associations between a domain and a DN to be used as the default oracleContext.

If you want clients to use discovery in directories which have more than one Oracle Context, then you can define the orclCommonContextMap attribute in the base admin context. This attribute overrides the orclDefaultSubscriber attribute. During name lookup the discovery operation returns both values, and the client decides based on these which Oracle Context to use.

If the orclCommonContextMap attribute is not defined, then the orclDefaultSubscriber is used as the default. If orclCommonContextMap is defined, then the client finds the default Oracle Context which is associated with its DNS domain in the orclCommonContextMap.

Here is a sample LDIF file entry:

$ ldapmodify -v -h sales-server -p 1389 -D cn=orcladmin -q
 dn: cn=Common,cn=Products,cn=OracleContext
 replace: orclCommonContextMap
 orclCommonContextMap:
 (contextMap=
   (domain_map=(domain=us.example.com)(DN="dc=example,dc=com"))
   (domain_map=(domain=uk.example.com)(DN="dc=sales,dc=com"))
  )

You must enter a contextMap entry without line breaks.

Related Topics

Parent topic: Configuring the Directory Naming Method

8.2.3 Export Local Naming Entries to a Directory Naming Server

If a tnsnames.ora file already exists, then you can export the network service names stored in that file to a directory server. These tasks assume the directory server has been installed and is running.

The export procedure is performed for one domain at a time.

Task 1   Create Structure in the Directory Server

In the directory server, create the directory information tree (DIT) with the structure in which you want to import network service names. Create the structure leading to the top of the Oracle Context.

For example, if the tnsnames.ora file supports a domain structure example.com and you want to replicate this domain in the directory, then create domain component entries of dc=com and dc=example in the directory, as shown in the following figure.

Figure 8-1 example.com in Directory Server

Description of Figure 8-1 follows
Description of "Figure 8-1 example.com in Directory Server"

You can replicate the domain structure you currently use with tnsnames.ora, or you can develop an entirely different structure. Introducing an entirely different structure can change the way clients enter the network service name in the connect string. Oracle recommends considering relative and fully-qualified naming issues before changing the structure.

Task 2   Create Oracle Contexts

Create an Oracle Context under each DIT location that you created in Task 1 using Oracle Internet Directory Configuration Assistant. Oracle Context has a relative distinguished name (RDN) of cn=OracleContext. Oracle Context stores network object entries, as well as other entries for other Oracle components. In the following figure, cn=OracleContext is created under dc=example,dc=com.

Figure 8-2 Oracle Context

Description of Figure 8-2 follows
Description of "Figure 8-2 Oracle Context"
Task 3   Configure Directory Server Usage

If not done as a part of creating Oracle Contexts, then configure the Oracle home for directory server use. The Oracle home you configure should be the one that performs the export.

Task 4   Export Objects to a Directory Server

To export network service names contained in a tnsnames.ora file to a directory, use either Oracle Enterprise Manager Cloud Controlr or Oracle Net Manager.

  • Export Objects using Oracle Enterprise Manager Cloud Control

    The following procedure describes how to export objects using Oracle Enterprise Manager Cloud Control

    1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control. See Accessing the Net Services Administration Page.

    2. Select Directory Naming from the Administer list, and then select the Oracle home that contains the location of the directory server.

    3. Click Go.

      The Directory Naming page appears.

    4. Click the Net Service Names tab.

    5. In the Related Links section, click Import Net Service Names To Directory Server.

      The Import Net Service Names To Directory Server page appears.

    6. From the Oracle Context list in the Oracle Internet Directory Server Destination section, select Oracle Context to which you want to export the selected network service names.

    7. In the Net Service Names to Import section, select the network service names.

    8. Click Add to add the network service names to the directory.

      The network service name is added to the Directory Naming page.

  • Export Objects using Oracle Net Manager

    The following procedure describes how to export objects using Oracle Net Manager:

    1. Start Oracle Net Manager. See Using Oracle Net Manager to Configure Oracle Net Services.

    2. If the tnsnames.ora file you want to export is not loaded in Oracle Net Manager, then select Open Network Configuration from the File menu to select the tnsnames.ora file to export to the directory.

    3. Select Directory from the Command menu, and then select Export Net Service Names.

      The Directory Server Migration wizard starts.

    4. Click Next.

      If network service names with multiple domain were detected in the tnsnames.ora file, then the Select Domain page appears. Continue to Step 5.

      If the network service names are not domain qualified, then the Select Net Service Names page appears. Skip to Step 6.

    5. Select the network domain whose network service names you want to export, and then click Next.

      The Select Net Service Names page appears.

    6. Select the network service names from the list to export, and then click Next.

      The Select Destination Context page appears.

    7. In the Select Destination Context page, do the following:

      1. From the Directory Naming Context list, select the directory entry that contains the Oracle Context. The directory naming context is part of a directory subtree that contains one or more Oracle Contexts.

      2. From the Oracle Context list, select the Oracle Context to which you want to export the selected network service names.

      3. Click Next.

      The Directory Server Update page appears with the status of the export operation.

    8. Click Finish to close the Directory Server Migration wizard.

Related Topics

Parent topic: Configuring the Directory Naming Method

8.2.4 Configure the LDAP Naming Adapter to Use Wallets

The client LDAP naming adapter authenticates the LDAP bind while connecting to the LDAP directory to resolve connect string names. You can configure the adapter to use an Oracle wallet during the authentication.

  1. Obtain an LDAP server certificate, create an Oracle wallet, and store the certificate and LDAP user credentials in the wallet truststore:
    1. Obtain an LDAP server certificate from the LDAP directory server using openssl s_client:
      openssl s_client -connect LDAP server host:port -showcerts -outform PEM

      The -connect LDAP server host:port option specifies the LDAP directory server host name and port for the connection. The -showcerts option displays the LDAP server certificate list sent by the server. The -outform PEM option extracts the server certificate to your file system directory (for example, /tmp/ldapservercert.txt) in a PEM format.

    2. Create an empty Oracle wallet:
      orapki wallet create -wallet wallet_directory

      The -wallet wallet_directory option specifies the location of the file system directory where you want to create the wallet.

    3. Add the LDAP server certificate to the wallet:
      orapki wallet add -wallet wallet_directory -trusted_cert -cert

      The -cert option specifies the location of the file system directory (for example, /tmp/ldapservercert.txt) where you have stored the LDAP server certificate.

    4. Create an entry in the wallet with the DN of the LDAP user name:
      mkstore -wrl wallet_directory -createEntry oracle.ldap.client.dn dn_of_ldap_username

      For example:

      mkstore -wrl /app/wallet -createEntry oracle.ldap.client.dn cn=userinldap,dc=example,dc=com

      For Microsoft Active Directory, you can also specify the userPrincipalName or down-level logon name (sAMAccountName) attribute.

    5. Create an entry in the wallet with the LDAP password:
      mkstore -wrl wallet_directory -createEntry oracle.ldap.client.password ldap_password
    6. Enable auto-login for the wallet:
      orapki wallet create -wallet wallet_directory -auto_login

      Note:

      • The mkstore wallet management command line tool is deprecated with Oracle Database 23ai, and can be removed in a future release.

        To manage wallets, Oracle recommends that you use the orapki command line tool.

      • Auto-login wallets are protected by file system permissions. Use operating system utilities to protect the wallet directory by granting read and write permissions only to the client.

      • Oracle has introduced a new auto-login wallet version (7) with Oracle Database 23ai. Version 6 of the Oracle local auto-login wallet is deprecated.

        You can update your local auto-login wallet by modifying it with orapki.

  2. Use the WALLET_LOCATION parameter to specify your wallet directory in the sqlnet.ora file: 
    WALLET_LOCATION=
  (SOURCE=
    (METHOD=file)
    (METHOD_DATA=
       (DIRECTORY=wallet_directory)))

    For example:

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

    For detailed information on configuring this parameter, see WALLET_LOCATION.

    Note:

    The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client or listener.

    For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

  3. Configure authentication settings for your LDAP connection in the sqlnet.ora file:

    • Set NAMES.LDAP_AUTHENTICATE_BIND=TRUE to specify that the LDAP connection is authenticated using the wallet directory (defined by WALLET_LOCATION).

    • Set NAMES.LDAP_AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH to use simple authentication method over LDAPS (LDAP over TLS connection).

    For detailed information on configuring these settings, see NAMES.LDAP_AUTHENTICATE_BIND and NAMES.LDAP_AUTHENTICATE_BIND_METHOD.

  4. Using Oracle Net Manager, add one or more directory entries to the LDAP server.
  5. Using SQL*Plus or any other database client, verify names resolution.

Related Topics

Parent topic: Configuring the Directory Naming Method

8.2.5 Specify LDAP Parameters Directly in a Connect Identifier

The Directory Naming method provides an alternative way to specify LDAP name lookup, by using LDAP parameters in a database client connection identifier. With this feature, you do not need to configure external configuration files (ldap.ora or sqlnet.ora) to connect to the database.

The values that are specified as part of ldap.ora and sqlnet.ora for LDAP name lookup are directly passed in the connect identifier. If ldap.ora or sqlnet.ora is present and you use LDAP parameters in the connect identifier, then the connect identifier values take precedence.

Syntax for the Connect Identifier

ldap[s]://host[:port]/name[,context][?parameter1=value1{&parameter2=value2}]

For example:

sqlplus "<user_name>/<password>@ldaps://<host_name>:<port>/cn=sales,cn=oraclecontext?DIRECTORY_SERVER_TYPE=oid&WALLET_LOCATION=/oracle/network/admin&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

Here, <user_name>/<password> specify the database user name and password for the connection.

The following are protocol-specific parameters specified using ldap[s]://host[:port]/name[,context]:

Syntax Element Description Default Value

ldap[s]

This is a mandatory parameter. Specifies the protocol, such as LDAP or LDAPS.

The LDAPS protocol uses a TLS connection.

Not applicable

host

This is a mandatory parameter. Specifies the host name where your LDAP directory server is running.

Not applicable

port

This is an optional parameter. Specifies the port number for the LDAP connection.

389 for the LDAP protocol

636 for the LDAPS protocol

name

This is a mandatory parameter. Specifies the LDAP entry to resolve the service name in the connect string.

This entry must be contained in the OracleContext container of a given context.

Not applicable

context

This is an optional parameter. Specifies the directory naming context containing OracleContext.

For example, a context can be:

cn=OracleContext,dc=example,dc=com

cn=OracleContext

The following are directory usage parameters specified using parameter=value. All these are optional parameters:

Syntax Element Description Default Value

directory_server_type

Specifies the directory server to use for LDAP-based name lookup.

The value can be:

  • OID for Oracle Internet Directory or Oracle Unified Directory

  • AD for Microsoft Active Directory

See DIRECTORY_SERVER_TYPE.

OID

authenticate_bind

Specifies whether the LDAP naming adapter should use a wallet for authentication.

The value can be true or false.

See AUTHENTICATE_BIND.

false

wallet_location

Specifies the directory where Oracle wallet is stored.

See WALLET_LOCATION.

Not applicable

authenticate_bind_method

Specifies the authentication method for the client LDAP naming adapter.

The value can be LDAPS_SIMPLE_AUTH or NONE.

See AUTHENTICATE_BIND_METHOD.

NONE

Note:

The directory_server_type, wallet_location, authenticate_bind, and authenticate_bind_method parameters are position independent.

Sample Connect Identifiers

Let us look at some examples on how to specify a connect identifier with different values:

  • With all parameters:

    All the required and optional parameters are specified in the string.

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com?DIRECTORY_SERVER_TYPE=oid&WALLET_LOCATION=/wallet&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • Without directory server:

    The default directory server (OID) is used:

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com?WALLET_LOCATION=wallet&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • Without authenticate_bind:

    The default authenticate_bind value (false) is used, and thus authenticate_bind_method is ignored. 

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com?DIRECTORY_SERVER_TYPE=oid&WALLET_LOCATION=wallet&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • With admin context:

    The context name value is specified as cn=OracleContext,dc=example,dc=com. 

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com?DIRECTORY_SERVER_TYPE=oid&WALLET_LOCATION=/wallet&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • Without admin context:

    The context value (cn=OracleContext,dc=example,dc=com) is null. 

    “scott/password@ldaps://ldapserver:636/orcl?DIRECTORY_SERVER_TYPE=oid&WALLET_LOCATION=/wallet&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • With minimal parameters:

    A minimal set of protocol-specific parameters are specified (protocol as ldaps, host as ldapserver, port as 636, and context that varies in each string). 

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com"
    "scott/password@ldaps://ldapserver:636/cn=orcl"
    "scott/password@ldaps://ldapserver:636/orcl"

  • Uses system wallet:

    The WALLET_LOCATION value is not specified in the connect identifier and sqlnet.ora file. In this case, the client uses wallet from the operating system's default certificate store. 

    "scott/password@ldaps://ldapserver:636/cn=orcl,cn=OracleContext,dc=example,dc=com?DIRECTORY_SERVER_TYPE=oid"

  • With the LDAP protocol:

    The LDAP protocol is specified for OID configuration in these strings. 

    "scott/password@ldap://ldapserver:2389/cn=orcl,cn=OracleContext,dc=example,dc=com?DIRECTORY_SERVER_TYPE=oid&AUTHENTICATE_BIND=false"
    "scott/password@ldap://ldapserver:2389/cn=orcl,cn=OracleContext,dc=example,dc=com"

  • With directory server along with user name and password authentication

    The DIRECTORY_SERVER_TYPE value is specified as AD (to use Microsoft Active Directory). The AUTHENTICATE_BIND and AUTHENTICATE_BIND_METHOD values specify LDAPS_SIMPLE_AUTH, which provides user name and password-based authentication. 

    "scott/password@ldaps://ldapserver:636/cn=orcl?DIRECTORY_SERVER_TYPE=AD&WALLET_LOCATION=/wallet&AUTHENTICATE_BIND=true&AUTHENTICATE_BIND_METHOD=LDAPS_SIMPLE_AUTH"

  • With directory server along with Windows native authentication

    The DIRECTORY_SERVER_TYPE value is specified as AD (to use Microsoft Active Directory). The AUTHENTICATE_BIND value is specified as true, which implies the default LDAPS_SIMPLE_AUTH=NONE setting. This provides Windows native authentication, using Windows login credentials. 

    "scott/password@ldap://ldapserver:389/cn=orcl?DIRECTORY_SERVER_TYPE=AD&AUTHENTICATE_BIND=true"

Related Topics

Parent topic: Configuring the Directory Naming Method

8.2.6 Export Directory Naming Entries to the tnsnames.ora file

After you create the directory naming entries, consider exporting the entries to a local tnsnames.ora file and distributing that file to clients. Clients can use the locally saved file when the directory server is temporarily unavailable.

The following procedure describes how to export directory naming entries to a local tnsnames.ora file:

  1. Access the Net Services Administration page in Oracle Enterprise Manager Cloud Control.

  2. Select Directory Naming from the Administer list, and then select the Oracle home that contains the location of the directory server.

  3. Click Go.

    The Directory Naming page appears.

  4. Click the Net Service Names tab.

  5. In the Simple Search section, select Oracle Context and search criteria to see the network service names for a particular Oracle Context.

    The network service names display in the Results section.

  6. In the Results section, click Save to tnsnames.ora.

    The Processing: Create tnsnames.ora File page appears, informing you of the creation process.

Related Topics

Parent topic: Configuring the Directory Naming Method

8.3 Configuring the Centralized Configuration Provider Naming Method

With this naming method, connect identifiers are mapped to connect descriptors contained in a Centralized Configuration Provider, such as Azure App Configuration store or Oracle Cloud Infrastructure (OCI) Object Storage as a JSON file.

Optionally, you can also store database credentials (such as database user name and database password) and Oracle Call Interface attributes (such as statement_cache_size, prefetch_rows, or session_pool) in a Centralized Configuration Provider. You need to use Azure Key Vault or OCI Vault to store the database password, and then add a reference to that vault in your Centralized Configuration Provider. You can also store an Oracle wallet in Azure Key Vault or OCI Vault, and then add a reference to that vault in your Centralized Configuration Provider.

A connect identifier here includes instance-specific details of a Centralized Configuration Provider (such as server name or app configuration name), path, and authentication details. Database clients can securely look up the configuration data from your Centralized Configuration Provider and connect to the database.

Note:

In addition to the Azure App Configuration store and OCI Object Storage, JDBC supports built-in Centralized Configuration Providers such as HTTPS provider and File provider (see Oracle Database JDBC Developer’s Guide). Also, ODP.NET supports local file system access for web and desktop apps (see Oracle Data Provider for .NET Developer's Guide).

Use one of the following Centralized Configuration Providers:

  • Azure App Configuration Store
    Stores configuration data in the Azure App Configuration store as key-value pairs, which are accessible with network service name paths as URI.
  • OCI Object Storage JSON File
    Stores configuration data in the Oracle Cloud Infrastructure (OCI) Object Storage as a JSON file.

Related Topics

Parent topic: Configuring Naming Methods

8.3.1 Azure App Configuration Store

Stores configuration data in the Azure App Configuration store as key-value pairs, which are accessible with network service name paths as URI.

Parent topic: Configuring the Centralized Configuration Provider Naming Method

8.3.1.1 Prerequisites for Using the Azure App Configuration Store

Perform these steps in the Azure portal or using the Azure CLI or API, before beginning to use the Azure App Configuration store.

  • Register an OAuth application and grant authorization permissions:

    The Azure App Configuration store's administrator must register an OAuth application with Microsoft Entra ID (previously called Microsoft Azure Active Directory) using App Registrations. The administrator must also give authorization permissions to this OAuth application for accessing the Azure App Configuration store.

  • (Optional) Create Azure Key Vault for secrets and grant authorization permissions:

    You can store Oracle Database credentials and Oracle wallet data in Azure Key Vault.

    • To store Oracle Database credentials:

      Create Azure Key Vault with the database password stored as a secret in that vault.

    • To store Oracle wallet data:

      The SQLNET client applications running on multitenant cloud service environments can store wallets in remote stores. Because these applications may not have access to the wallets stored in a local system file, this feature is especially useful for Mutual Transport Layer Security (mTLS) connections that require file system access to keep the wallet.

      To store wallet data, you first convert an auto-login wallet file (cwallet.sso) to a Base64 format, and then create Azure Key Vault with the Base64-formatted cwallet.sso value stored as a secret.

      1. Convert your cwallet.sso file to a Base64 format.

        A common way to convert cwallet.sso to Base64 is by using the following openssl command on Linux: 

        cat cwallet.sso | base64 -w 0 > file_to_upload

        Here, file_to_upload specifies the cwallet.sso file that you want to convert.

      2. Create Azure Key Vault by pasting contents of the Base64-formatted string of the cwallet.sso file, as secret contents without any new lines.

    You will later add a Key Vault reference to this vault in Azure App Configuration. The Azure App Configuration store's administrator must give authorization permissions to the registered OAuth application for accessing this vault.

    For detailed information on how to perform these steps, see Azure Key Vault Documentation.

  • Understand how to organize keys in Azure App Configuration:

    Keys ending with connect_descriptor, user, password, and wallet_location serve as identifiers for key-values, and are used to store and retrieve corresponding values for the database connection.

    The connect_descriptor keys (keys ending with connect_descriptor) store connection descriptors, also known as TNS connection strings.

    It is a common practice to organize keys into a hierarchical namespace by using a character delimiter, such as / (slash), & (ampersand), or : (colon). Use a convention that suits your application. The examples here use / (slash) as a character delimiter to organize keys.

    An application user can organize connect descriptors under a prefix as per application requirements, and set up authentication and authorization for all such keys in Azure App Configuration. Optionally, you can add database credentials (such as the user name and password of database user), wallet location, and Oracle Call Interface attributes under the same prefix:

    • prefix/connect_descriptor (required)

    • prefix/user (optional)

    • prefix/password (optional)

    • prefix/wallet_location (optional)

    • prefix/oci (optional)

    The portion of a key without the connect_descriptor suffix is treated as a prefix for deriving the database user name, database password, and OCI attributes. Database clients look for a key ending with the user suffix after the derived prefix is used as the database user name, a key ending with the password suffix for the database password, a key ending with the wallet_location suffix for the wallet directory, and a key ending with the oci suffix for OCI attributes.

    A connect identifier contains the part of a key without terminating connect_descriptor as a prefix. Database clients complete the key by appending connect_descriptor, user, password, wallet_location, or oci, and then search the Azure App Configuration store with that key.

    Syntax for Azure Centralized Configuration Provider Naming:
    config-azure://{appconfig-name}[?key=prefix&label=value&option1=value1&option2=value2...]
    For example:
    sqlplus dbuser/@"config-azure://dbclient-appconfig?key=database/sales/&azure_client_id=client id&azure_client_secret=secret&azure_tenant_id=tenant id"

    This syntax is explained in details in the sections that follow.

8.3.1.2 Step 1: Create a Key-Value with the Connect Descriptor

Create a key-value pair with the connect descriptor, which contains the protocol address of the listener and the connect information for the destination service.

  1. In the Azure portal, search for App Configuration, and then navigate to the Configuration explorer page of your Azure App Configuration store.
  2. Click Create and select Key-value to create a new key-value.

    • Key: Add a key with the connect_descriptor suffix for your chosen prefix.

      For example, for the database/sales/ prefix, add a key as:
      database/sales/connect_descriptor

    • Value: Store a value for your key by specifying the connect descriptor in either the Easy Connect syntax or the connect descriptor format.

      The connect descriptor value must start with either (DESCRIPTION= or (DESCRIPTION_LIST=. The DESCRIPTION parameter defines connect descriptor containers. The DESCRIPTION_LIST parameter defines a list of connect descriptors for a service name.

      Note:

      There are some restrictions on the parameter names and values that can appear in connect descriptors. Ensure that you specify only the allowed parameters and values, as listed in Oracle Database Net Services Reference.
    As shown in the preceding image, the suffix connect_descriptor in the database/sales/connect_descriptor key is paired with the following connect descriptor value:
    (DESCRIPTION=
    (ADDRESS=
        (PROTOCOL=tcp)
        (HOST=sales-server)
        (PORT=1521)
    )
    (CONNECT_DATA=
        (SERVER=DEDICATED)
        (SERVICE_NAME=sales.us.example.com)
    )
)
8.3.1.3 Step 2: Add the User Name and Password Vault Reference (Optional)

Under the prefix that you used in Step 1, create key-value pairs with the database user name and password for authentication to Oracle Database. The password value is a vault reference.

This step is optional. With this configuration, you can omit database credentials in the connect identifier for the database connection.
  1. Ensure that you have created Azure Key Vault with the database password stored as a secret, as explained in Prerequisites for Using the Azure App Configuration Store.
  2. On the Configuration explorer page of your Azure App Configuration store, click Create and select Key-value to add a key-value pair with the database user name.

    • Key: Add a key with the user suffix to your chosen prefix.

      For example, to the database/sales/ prefix, add a key as:
      database/sales/user

    • Value: Store a value for your key by specifying the database user name.

    As shown in the following image, the suffix user in the database/sales/user key is paired with scott as its value:

  3. Click Create and select Key Vault reference to add a key-value pair with the database password.

    • Key: Add a key with the password suffix to your chosen prefix.

      For example, to the database/sales/ prefix, add a key as:
      database/sales/password

    • Value: Select the Key Vault and Secret values corresponding to the Azure Key Vault that you created for storing your database password.

    As shown in the following image, the suffix password in the database/sales/password key is paired with dbclient-sales-secret (stored in vault1) as its value:

8.3.1.4 Step 3: Add the Wallet Vault Reference (Optional)

Under the same prefix, create a key-value pair with the wallet location. The wallet location value is a vault reference.

This step is optional. With this configuration, you can store an Oracle wallet in a remote store using Azure App Configuration.
  1. Ensure that you have created Azure Key Vault with your wallet data stored as a secret, as explained in Prerequisites for Using the Azure App Configuration Store.
  2. On the Configuration explorer page of your Azure App Configuration store, click Create and select Key Vault reference to add a key-value pair with the wallet location.

    • Key: Add a key with the wallet_location suffix to your chosen prefix.

      For example, to the database/sales/ prefix, add a key as:
      database/sales/wallet_location

    • Value: Select the Key Vault and Secret values corresponding to the Azure Key Vault that you created for storing your wallet data.

    As shown in the following image, the suffix wallet_location in the database/sales/wallet_location key is paired with abcwallet (stored in vault1) as its value:

8.3.1.5 Step 4: Add Oracle Call Interface Parameters (Optional)

Under the same prefix, create key-value pairs with Oracle Call Interface configuration parameters.

This step is optional. With this configuration, you can override the Oracle Call Interface parameters configured in the oraaccess.xml file or omit configuring the file. The oraaccess.xml file is a client-side configuration file that lets you configure selected OCI parameters during deployment.
  1. On the Configuration explorer page of your Azure App Configuration store, click Create and select Key-value to add a key-value to your store.

    • Key: Add a key with the oci/oci parameter name suffix to your chosen prefix.

      Note:

      Ensure that you specify only the allowed Oracle Call Interface parameters, as listed in Oracle Call Interface Developer's Guide.
      For example, to specify the prefetch_rows parameter for the database/sales/ prefix, add a key as:
      database/sales/oci/prefetch_rows
      Similarly, to specify the <session_pool> inactivity_timeout parameter, add a key as:
      database/sales/oci/session_pool/inactivity_timeout

    • Value: Store a value for your key by specifying the required configuration parameter.

    As shown in the following image, the suffix oci/prefetch_rows in the database/sales/oci/prefetch_rows key is paired with the prefetch_rows value of 100:

8.3.1.6 Step 5: Use a Connect Identifier Containing Azure App Configuration Store Values

Use the Azure App Configuration name, key path, and Azure authentication parameters in a database client connection identifier.

Syntax:
config-azure://{appconfig-name}[?key=prefix&label=value&option1=value1&option2=value2...]

The syntax details are:

Syntax Element Description

config-azure:// {appconfig-name}

Name of your Azure App Configuration store.

key=prefix

Prefix of your key, without the connect_descriptor suffix in Azure App Configuration.

label=value

Label to be used for the connect descriptor.

Labels are used to differentiate key-values with the same key. Refer to Microsoft Azure documentation for additional details.

option=value

Both the authentication method and corresponding authentication parameters to access your Centralized Configuration Provider.

Authentication method:

Use the AUTHENTICATION parameter to set one of the following authentication methods:

  • For Azure Service Principal (or OAuth 2.0 Client Credentials): AUTHENTICATION=AZURE_DEFAULT

    Note: This is the default setting, which means that the OAuth 2.0 Client Credentials authentication method is implied by default and you do not need to explicitly specify the AUTHENTICATION parameter. In this case, you can omit this setting.

  • For Azure Service Principal: AUTHENTICATION=AZURE_SERVICE_PRINCIPAL

  • For Azure Managed Identity (or Azure Managed User Identity): AUTHENTICATION=AZURE_MANAGED_IDENTITY

Authentication parameters:

Set authentication parameters corresponding to your chosen authentication method, as described in AUTHENTICATION.

For example, if using the default OAuth 2.0 Client Credentials authentication method, then set authentication parameters such as AZURE_TENANT_ID, AZURE_CLIENT_ID, or AZURE_CLIENT_SECRET.

For detailed information on all authentication parameters, see Authentication Parameters for Azure App Configuration Store.

Examples:

Let us look at some examples on how to specify a connect identifier string with different values:

  • With the default OAuth 2.0 Client Credentials authentication:

    For multiple applications, such as sales and hr, you can store a connect descriptor for sales under the database/sales prefix and for hr under the database/hr prefix.

    The following usage of naming looks up a connect_descriptor under the database/sales prefix. Here, the AUTHENTICATION=AZURE_DEFAULT setting is omitted. Authentication method for the default flow is implicit, so only the client credentials are specified using the AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID authentication parameters.
    • With database credentials specified in the string:
      sqlplus dbuser@"config-azure://dbclient-appconfig?key=database/sales/&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
    • With database credentials stored in Azure Key Vault:
      sqlplus /@"config-azure://dbclient-appconfig?key=database/sales/&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
    Similarly, the following usage of naming looks up a connect_descriptor under the database/hr prefix:
    • With database credentials specified in the string:
      sqlplus dbuser@"config-azure://dbclient-appconfig?key=database/hr/&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
    • With database credentials stored in Azure Key Vault:
      sqlplus /@"config-azure://dbclient-appconfig?key=database/hr/&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
  • With the Azure Service Principal authentication:
    • With database credentials specified in the string:
      sqlplus dbuser@"config-azure://dbclient-appconfig?key=database/sales/&authentication=azure_service_principal&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_client_certificate_path=/app/dbclient/certificate_for_authenticaion.txt&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
    • With database credentials stored in Azure Key Vault:
      sqlplus /@"config-azure://dbclient-appconfig?key=database/sales/&authentication=azure_service_principal&azure_client_id=a1abc12-ab12-1ab1-a1b1-123a&azure_client_secret=A123B~AB123a~AB1234_abab&azure_client_certificate_path=/app/dbclient/certificate_for_authenticaion.txt&azure_tenant_id=123ab-12a12-1a2b1-a1b2"
  • With the Azure Managed Identity authentication:
    • With database credentials specified in the string:
      sqlplus dbuser@"config-azure://dbclient-appconfig?key=database/sales/&authentication=azure_managed_identity"
    • With database credentials stored in Azure Key Vault:
      sqlplus /@"config-azure://dbclient-appconfig?key=database/sales/&authentication=azure_managed_identity"

8.3.2 OCI Object Storage JSON File

Stores configuration data in the Oracle Cloud Infrastructure (OCI) Object Storage as a JSON file.

Parent topic: Configuring the Centralized Configuration Provider Naming Method

8.3.2.1 Prerequisites for Using the OCI Object Storage JSON File

Perform these steps in the Oracle Cloud Infrastructure (OCI) console or using the OCI CLI or API, before beginning to use the OCI Object Storage.

  • Create a bucket in the OCI Object Storage:

    Use the OCI Object Storage service to create a bucket within a compartment of your Object Storage namespace. You will later upload a Centralized Configuration Provider JSON file as an object to this bucket.

  • Create a policy and assign it to database user:

    The OCI administrator must grant security access in a policy. Create an OCI Identity and Access Management (IAM) policy, and assign it to database user for accessing Object Storage resources in the compartment.

  • (Optional) Create a vault for secrets and grant authorization permissions:

    You can store Oracle Database credentials and Oracle wallet data in OCI Vault or Azure Key Vault.

    • To store Oracle Database credentials:

      Create OCI Vault or Azure Key Vault with the database password stored as a secret in that vault.

    • To store Oracle wallet data:

      The SQLNET client applications running on multitenant cloud service environments can store wallets in remote stores. Because these applications may not have access to the wallets stored in a local system file, this feature is especially useful for Mutual Transport Layer Security (mTLS) connections that require file system access to keep the wallet.

      To store wallet data, you first convert an auto-login wallet file (cwallet.sso) to a Base64 format, and then create OCI Vault or Azure Key Vault with the Base64-formatted cwallet.sso value stored as a secret.

      1. Convert your cwallet.sso file to a Base64 format.

        A common way to convert cwallet.sso to Base64 is by using the following openssl command on Linux: 

        cat cwallet.sso | base64 -w 0 > file_to_upload

        Here, file_to_upload specifies the cwallet.sso file that you want to convert.

      2. Create OCI Vault or Azure Key Vault by pasting contents of the Base64-formatted string of the cwallet.sso file, as secret contents without any new lines.

    You will later add a reference to these vaults in the JSON file. The OCI administrator must give authorization permissions to the database user for accessing the OCI Vault. Similarly, the Azure App Configuration store's administrator must give authorization permissions to the registered OAuth application for accessing the Azure Key Vault.

    For detailed information on how to perform these steps, see OCI Vault Documentation or Azure Key Vault Documentation.

  • Understand the format of a Centralized Configuration Provider JSON file:

    You can organize connect descriptors in a Centralized Configuration Provider JSON file based on your application requirements, in one of the following JSON formats:

    • A single object with a connect_descriptor sub-object

    • Multiple objects (separated by a comma) with each object having its own connect_descriptor sub-object

    Optionally, you can add user and password sub-objects (to specify the database user name and database password), wallet_location sub-object (to specify the wallet directory), and oci sub-object (to specify Oracle Call Interface configuration parameters) in the same file.

    Database clients look for specific network service names in a JSON object for deriving the connect descriptor, database user name and password, wallet data, and other Oracle Call Interface attributes. A connect identifier retrieves these JSON objects from the OCI Object Storage endpoint and uses it to locate the stored attributes. These values are used for the database connection.

    The syntax for Centralized Configuration Provider JSON (CCJSON) is:
    Centralized Configuration Provider JSON -> CCJSON_elements

CCJSON_elements       -> CCJSON_elment
                      -> CCJSON_element, CCJSON_element

CCJSON_element        -> '{' members '}'

members               -> member
                      -> member, member

member                -> cd
                      -> member, cd_related

cd                    -> "connect_descriptor" : "<connect_descriptor>"

cd_related            -> "user" : "<database user name>"
                      -> "password" : '{' password_data '}'
                      -> "wallet_location" : '{' wallet_data '}'
                      -> "oci" : '{' oci_config_members '}'
                      -> nul

password_data         -> '{' "type" : vault_type, 
                             "value" : vault_value, 
                             "authentication": authentication_value '}'

wallet_data           -> '{' "type" : vault_type,  
                             "value" : vault_value, 
                             "authentication": authentication_value '}'

vault_type            -> "ocivault"
                      -> "azurevault"

vault_value           -> "<vault-specific identifier>"    

authentication_value  -> '{' "azure_client_id" : "<client id>", 
                             "azure_client_secret" : "<secret>",
                             "azure_tenant_id" : "<tenant id>" '}'          
                      -> null

oci_config_members    -> '{' oci_config_name : oci_config_value '}'

oci_config_value      -> json_value

oci_config_name       -> prefetch_rows
                      -> statement_cache_size
                      -> lob_prefetch_size 
                      -> session_pool

session_pool          -> '{' "min" : value, "max" : value, 
                             "increment" : value, "max_lifetime_session" : value, 
                             "max_use_session" : value, "inactivity_timeout" : value '}'

prefetch_rows         -> "prefetch_rows" : numeric_value

statement_cache_size  -> "statement_cache_size" : numeric_value

lob_prefetch_size     -> "lob_prefetch_size" : numeric_value

numeric_value         -> "<number>"

    You will see how to create a JSON file with these values in the sections that follow.

8.3.2.2 Step 1: Create a JSON file with the Connect Descriptor

Create a Centralized Configuration Provider JSON file with the connect descriptor and upload it to the Oracle Cloud Infrastructure (OCI) Object Storage.

  1. Create a JSON file in one of the following formats:

    • Single object specified with a connect_descriptor sub-object:

      The following example shows a sample sales.json file, configured with a connect descriptor for the sales.myexample.com service:
      { 
 "connect_descriptor": "(DESCRIPTION=
                           (ADDRESS=
                              (PROTOCOL=TCP)
                              (HOST=my sales dbserver)
                              (PORT=1521))
                           (CONNECT_DATA=
                              (SERVER=DEDICATED)
                              (SERVICE_NAME=sales.myexample.com))
                        )" 
}

    • Multiple objects (separated by a comma), and each object with a separate connect_descriptor sub-object:

      The following example shows a sample multi.json file, configured with multiple connect descriptors for the sales and hr objects. 
      { 
 "sales" : { 
    "connect_descriptor": "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my sales dbserver)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=sales.myexample.com))
                           )"
 },
 "hr" : { 
    "connect_descriptor": "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my dbserver.my.example.com)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=hr.my.example.com))
                           )" 
 } 
}

    Note:

    There are some restrictions on the parameter names and values that can appear in connect descriptors. Ensure that you specify only the allowed parameters and values, as listed in Oracle Database Net Services Reference.
  2. Store your JSON file in the OCI Object Storage:

    In the OCI console, navigate to the Object Storage - Bucket Details page of your bucket and upload the file to that bucket under Objects.

8.3.2.3 Step 2: Add the User Name and Password Vault Reference (Optional)

To the JSON file that you created in Step 1, add the database user name and database password for authentication to Oracle Database. The password value is a vault reference.

This step is optional. With this configuration, you can omit database credentials in the connect identifier for the database connection.

  1. Ensure that you have created either OCI Vault or Azure Key Vault with the database password stored as a secret, as explained in Prerequisites for Using the OCI Object Storage JSON File.
  2. Specify the user and password objects in your JSON file.

    • user: Database user name.

    • password:

      • type: Type of vault used. Specify ocivault for OCI Vault and azurevault for Azure Key Vault.

      • value: For OCI Vault, specify the Oracle Cloud Identifier (OCID) of the secret stored in your vault. You can get this value from the Secret Details page under Secret Information in the OCI console. For example: "ocid1.vaultsecret.my-secret-id"

        For Azure Key Vault, specify the URI value of Azure Key Vault. You can get this value from the Azure portal or use REST API that gives details about vault. For example: "https://dbclients.vault.azure.net/secrets/salesappaswd"

      • authentication: Authentication parameters to access the Azure Key Vault secrets store:
        { 
  "azure_client_id" : "<client id>", 
  "azure_client_secret" : "<secret>",
  "azure_tenant_id" : "<tenant id>" 
}

        You can access OCI Vault using the authentication parameters set at the command line in the connect identifier.

    The following sales.json file shows the user and password attributes along with connect_descriptor, configured for the sales.myexample.com service. The password is stored in Azure Key Vault.
    { 
 "connect_descriptor" : "(DESCRIPTION=
                           (ADDRESS=
                              (PROTOCOL=TCP) 
                              (HOST=my sales dbserver)
                              (PORT=1521))
                           (CONNECT_DATA=
                              (SERVER=DEDICATED)
                              (SERVICE_NAME=sales.myexample.com))
                         )"
 "user" : "admin",  
 "password" : {
    "type" : "azurevault",
    "value" : "https://dbclient.vault.azure.net/secrets/salesdbpasswd",
    "authentication" : {
       "azure_client_id" : "a12a1b12-ab12-1ab1-a1b2-12345a123aba",
       "azure_client_secret" : "A1B1A~ABCabc~ABaAbAb1223ABAB12abc_abcd",
       "azure_tenant_id" : "1a123ab1-a1b2-1a12-a1b1-a12bcdab01234"
    }
 }
}
    Similarly, the following multi.json file shows the user and password attributes along with connect_descriptor, specified for the sales and hr objects. The passwords are stored in OCI Vault.
    { 
 "sales" : { 
    "connect_descriptor" : "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my sales dbserver)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=sales.myexample.com))
                            )"
    "user" : "admin", 
    "password" : { 
      "type" : "ocivault", 
      "value" : "ocid1.vaultsecret.my-secret-id"
    }
 },
 "hr" : { 
    "connect_descriptor" : "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my dbserver.my.example.com)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=hr.my.example.com))
                           )" 
    "user" : "admin", 
    "password" : { 
      "type" : "ocivault", 
      "value" : "ocid1.vaultsecret.my-secret-id" 
    }
 } 
}
  3. Store your updated JSON file in the OCI Object Storage:

    In the OCI console, navigate to the Object Storage - Bucket Details page of your bucket and upload the file to that bucket under Objects.

8.3.2.4 Step 3: Add the Wallet Vault Reference (Optional)

To the same JSON file, add the wallet location. The wallet location value is a vault reference.

This step is optional. With this configuration, you can store an Oracle wallet in a remote store using OCI Object Storage.
  1. Ensure that you have created either OCI Vault or Azure Key Vault with your wallet data stored as a secret, as explained in Prerequisites for Using the OCI Object Storage JSON File.
  2. Specify the wallet_location object with the wallet data.

    • type: Type of vault used. Specify ocivault for OCI Vault and azurevault for Azure Key Vault.

    • value: For OCI Vault, specify the OCID of the secret stored in your vault. You can get this value from the Secret Details page under Secret Information in the OCI console. For example: "ocid2.vaultsecret.my-wallet-secret-id"

      For Azure Key Vault, specify the URI value of Azure Key Vault. You can get this value from the Azure portal or use REST API that gives details about vault. For example: "https://dbclients.vault.azure.net/secrets/saleswallet"

    • authentication: Authentication parameters to access the Azure Key Vault secrets store:
      { 
  "azure_client_id" : "<client id>", 
  "azure_client_secret" : "<secret>",
  "azure_tenant_id" : "<tenant id>" 
}

      You can access OCI Vault using the authentication parameters set at the command line in the connect identifier.

    The following sales.json file shows the user, password, and wallet_location attributes along with connect_descriptor, configured for the sales.myexample.com service. The password and wallet data are stored in Azure Key Vault.
    { 
 "connect_descriptor" : "(DESCRIPTION=
                           (ADDRESS=
                              (PROTOCOL=TCP) 
                              (HOST=my sales dbserver)
                              (PORT=1521))
                           (CONNECT_DATA=
                              (SERVER=DEDICATED)
                              (SERVICE_NAME=sales.myexample.com))
                         )"
 "user" : "admin",  
 "password" : {
    "type" : "azurevault",
    "value" : "https://dbclient.vault.azure.net/secrets/salesdbpasswd",
    "authentication" : {
       "azure_client_id" : "a12a1b12-ab12-1ab1-a1b2-12345a123aba",
       "azure_client_secret" : "A1B1A~ABCabc~ABaAbAb1223ABAB12abc_abcd",
       "azure_tenant_id" : "1a123ab1-a1b2-1a12-a1b1-a12bcdab01234"
    }
 },
 "wallet_location" : {
    "type" : "azurevault",
    "value" : "https://dbclient.vault.azure.net/secrets/saleswallet"
    "authentication" : {
       "azure_client_id" : "a12a1b12-ab12-1ab1-a1b2-12345a123aba",
       "azure_client_secret" : "A1B1A~ABCabc~ABaAbAb1223ABAB12abc_abcd",
       "azure_tenant_id" : "1a123ab1-a1b2-1a12-a1b1-a12bcdab01234"
 }  
}
    Similarly, the following multi.json file shows the user, password, and wallet_location attributes along with connect_descriptor, specified for the sales and hr objects. The passwords and wallet data are stored in OCI Vault.
    { 
 "sales" : { 
    "connect_descriptor" : "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my sales dbserver)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=sales.myexample.com))
                            )"
    "user" : "admin", 
    "password" : { 
      "type" : "ocivault", 
      "value" : "ocid1.vaultsecret.my-password-secret-id"
    } 
    "wallet_location" : {
      "type" : "ocivault",
      "value" : "ocid2.vaultsecret.my-wallet-secret-id"
    }
 },
 "hr" : { 
    "connect_descriptor" : "(DESCRIPTION=
                              (ADDRESS=
                                 (PROTOCOL=TCP)
                                 (HOST=my dbserver.my.example.com)
                                 (PORT=1521))
                              (CONNECT_DATA=
                                 (SERVER=DEDICATED)
                                 (SERVICE_NAME=hr.my.example.com))
                           )" 
    "user" : "admin", 
    "password" : { 
      "type" : "ocivault", 
      "value" : "ocid1.vaultsecret.my-password-secret-id" 
    } 
    "wallet_location" : {
      "type" : "ocivault",
      "value" : "ocid2.vaultsecret.my-wallet-secret-id"
    }
 } 
}
  3. Store your updated JSON file in the OCI Object Storage:

    In the OCI console, navigate to the Object Storage - Bucket Details page of your bucket and upload the file to that bucket under Objects.

8.3.2.5 Step 4: Add Oracle Call Interface Parameters (Optional)

To the same JSON file, add Oracle Call Interface configuration parameters.

This step is optional. With this configuration, you can override the Oracle Call Interface parameters configured in the oraaccess.xml file or omit configuring the file. The oraaccess.xml file is a client-side configuration file that lets you configure selected OCI parameters during deployment.
  1. Specify Oracle Call Interface parameters in the oci JSON object.

    Note:

    Ensure that you specify only the allowed Oracle Call Interface parameters, as listed in Oracle Call Interface Developer's Guide.
    The following sales.json file shows Oracle Call Interface attributes along with the connect descriptor, database credentials, and wallet location values that are configured for the sales.myexample.com service:
    { 
 "connect_descriptor": "(DESCRIPTION=
                          (ADDRESS=
                            (PROTOCOL=TCP)
                            (HOST=my sales dbserver)
                            (PORT=1521))
                          (CONNECT_DATA=
                            (SERVER=DEDICATED)
                            (SERVICE_NAME=sales.myexample.com))
                        )", 
 "user": "admin", 
 "password": { 
    "type": "ocivault", 
    "value": "ocid1.vaultsecret.my-password-secret-id" 
 }, 
 "wallet_location" : {
    "type" : "ocivault",
    "value" : "ocid2.vaultsecret.my-wallet-secret-id"
 },
 "oci": { "statement_cache_size" : 5,
          "prefetch_rows" : 10, 
          "lob_prefetch_size": 1024, 
          "session_pool" : { "min" : 4, "max" : 10, "increment" : 2 }
 }
}
    Similarly, the following multi.json file shows Oracle Call Interface attributes along with the connect descriptor, database credentials, and wallet location values that are specified for the sales and hr objects:
    { 
 "sales" : { 
   "connect_descriptor": "(DESCRIPTION=
                            (ADDRESS=
                              (PROTOCOL=TCP)
                              (HOST=my sales dbserver)
                              (PORT=1521))
                            (CONNECT_DATA=
                              (SERVER=DEDICATED)
                              (SERVICE_NAME=sales.myexample.com))
                          )",   
   "user": "scott", 
   "password": { 
      "type": "ocivault", 
      "value": "ocid1.vaultsecret.oc1.my-password-secret-id" 
   }, 
   "wallet_location" : {
      "type" : "ocivault",
      "value" : "ocid2.vaultsecret.my-wallet-secret-id"
   },
   "oci":{ "statement_cache_size" : 5, 
           "prefetch_rows" : 10, 
           "lob_prefetch_size": 1024, 
           "session_pool" : { "min" : 4, "max" : 10, "increment" : 2 }
   } 
 },
 "hr" : { 
   "connect_descriptor": "(DESCRIPTION=
                            (ADDRESS=
                              (PROTOCOL=TCP)
                              (HOST=my dbserver.my.example.com)
                              (PORT=1521))
                            (CONNECT_DATA=
                              (SERVER=DEDICATED)
                              (SERVICE_NAME=hr.my.example.com))
                          )" 
   "oci":{ 
   "statement_cache_size" : 6, 
   "prefetch_rows" : 10 
   } 
 } 
}
  2. Store your updated JSON file in the OCI Object Storage:

    In the OCI console, navigate to the Object Storage - Bucket Details page of your bucket and upload the file to that bucket under Objects.

8.3.2.6 Step 5: Use a Connect Identifier Containing OCI Object Storage Values

Use the Oracle Cloud Infrastructure (OCI) Object Storage server name, key path, and authentication parameters in a database client connection identifier.

Syntax:
config-ociobject://objectstorage-server-name/n/{namespaceName}/b/{bucketName}/o/{objectName}/[c/{networkServiceName}]?[option1=value1&option2=value2...]

The syntax details are:

Syntax Element Description

config-ociobject:// objectstorage-server-name

Server name of your OCI Object Storage. This is the URL Path (URI) value given on the Object Details page in the OCI console.

Specify this value without the https:// prefix.

n/{namespaceName}

OCI Object Storage namespace where you have stored the JSON file.

b/{bucketName}

OCI Object Storage bucket name where you have stored the JSON file.

o/{objectName}

JSON file to look up and resolve a network service name.

c/{networkServiceName}

Network service name if the JSON file contains two or more network service names.

option=value

Both the authentication method and corresponding authentication parameters to access your Centralized Configuration Provider.

Authentication method:

Use the AUTHENTICATION parameter to set one of the following authentication methods:

  • For OCI API Key: AUTHENTICATION=OCI_DEFAULT

    Note: This is the default setting, which means that the OCI API Key authentication method is implied by default and you do not need to explicitly specify the AUTHENTICATION parameter. In this case, you can omit this setting.

  • For OCI Instance Principal: AUTHENTICATION=OCI_INSTANCE_PRINCIPAL

  • For OCI Resource Principal: AUTHENTICATION=OCI_RESOURCE_PRINCIPAL

For detailed information on these authentication methods, see AUTHENTICATION.

Authentication parameters:

Set authentication parameters corresponding to your chosen authentication method:

  • If using the default OCI API Key authentication method, then set authentication parameters such as OCI_TENANCY, OCI_USER, OCI_FINGERPRINT, or OCI_KEY_FILE. See Authentication Parameters for OCI Object Storage.

  • If using the OCI Instance Principal or the OCI Resource Principal authentication method, then you do not need to set any authentication parameter.

Examples:

Let us look at some examples on how to specify a connect identifier string with different values:

  • Database credentials specified in the string:
    sqlplus dbuser/@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/sales.json?oci_tenancy=ocid1.tenancy.oc1..aaabbb1234aaabbb&oci_user=ocid1.user.oc1..ababab12121212&oci_fingerprint=a1:bc:a1:1a:12:a1:a2:b1:b2:1b&oci_key_file=//app/mykey.pem"

  • Database credentials stored in OCI Vault:

    The vault reference is configured in the sales.json file:
    sqlplus /@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/sales.json?oci_tenancy=ocid1.tenancy.oc1..aaabbb1234aaabbb&oci_user=ocid1.user.oc1..ababab12121212&oci_fingerprint=a1:bc:a1:1a:12:a1:a2:b1:b2:1b&oci_key_file=//app/mykey.pem"

  • Network service name specified in the JSON file:

    A network service name is given (as c/hr) to indicate a specific name among many network service names in the multi.json file:
    sqlplus dbuser/@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/multi.json/c/hr?oci_tenancy=ocid1.tenancy.oc1..aaabbb1234aaabbb&oci_user=ocid1.user.oc1..ababab12121212&oci_fingerprint=a1:bc:a1:1a:12:a1:a2:b1:b2:1b&oci_key_file=//app/mykey.pem"

  • With the default OCI API Key authentication:

    Here, the AUTHENTICATION=OCI_DEFAULT setting is omitted. Authentication method for the default flow is implicit, so only the API key-related values are specified using the OCI_TENANCY, OCI_USER, OCI_FINGERPRINT, and OCI_KEY_FILE authentication parameters. 

    sqlplus dbuser/@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/sales.json?oci_tenancy=ocid1.tenancy.oc1..aaabbb1234aaabbb&oci_user=ocid1.user.oc1..ababab12121212&oci_fingerprint=a1:bc:a1:1a:12:a1:a2:b1:b2:1b&oci_key_file=//app/mykey.pem"
  • With the OCI Instance Principal authentication:
    sqlplus dbuser/@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/multi.json/c/sales?authentication=oci_instance_principal"
  • With the OCI Resource Principal authentication:
    sqlplus dbuser/@"config-ociobject://objectstorage.us-region-1.example.com/n/myappnamespace/b/dbclientapps/o/multi.json/c/sales?authentication=oci_resource_principal"

8.4 Configuring the Easy Connect Naming Method

The Easy Connect naming method eliminates the need for service name lookup in tnsnames.ora files for TCP/IP environments. In fact, no naming or directory system is required when using this method.

Parent topic: Configuring Naming Methods

8.4.1 Understanding the Easy Connect Naming Method

The Easy Connect naming method provides out-of-the-box TCP/IP connectivity to databases.

Overview

This naming method extends the functionality of the host naming method by enabling clients to connect to a database server with an optional port and service name in addition to the host name of the database:


CONNECT username@[//]host[:port][/[service_name][:server_type][/instance_name]]
Enter password: password

The connect identifier converts to the following connect descriptor:

(DESCRIPTION= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=host)(PORT=port))
  (CONNECT_DATA=
    (SERVICE_NAME=service_name)
    (SERVER=server_type)
    (INSTANCE_NAME=instance_name))
)

If the Oracle Database server installation was performed in Typical mode, then the default service name used by the Oracle instance is the database name, and the following Easy Connect syntax can be used to connect to that instance:

SQLPLUS /nolog
SQL> CONNECT username@host/db_name
SQL> Enter password: password

Easy Connect Syntax Examples

The connect strings in the following example connect the client to database service sales.us.example.com with a listening endpoint of 1521 on database server sales-server:
CONNECT scott@sales-server:1521/sales.us.example.com
CONNECT scott@//sales-server/sales.us.example.com
CONNECT scott@//sales-server.us.example.com/sales.us.example.com

After each of the connect strings, you must enter a password to connect to the database service.

These connect strings convert into the following connect descriptor:
(DESCRIPTION= 
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)))

Connect Identifier for Easy Connect Naming

This is a list of the Easy Connect syntax elements and descriptions for each:

Syntax Element Description

//

Use // to specify a URL or JDBC connection.

Required for URL or JDBC connections. The connect identifier must be preceded by a double-slash (//). For example: 

scott@//sales-server
Enter password: password

Optional for SQL connections. The connect identifier can preceded by a double-slash (//). For example, the following connect strings are semantically equivalent: 

SQL> CONNECT scott@sales-server

SQL> CONNECT scott@//sales-server

host

Required. Specify the host name or IP address of the database host computer.

The host name is domain-qualified if the local operating system configuration specifies a domain.

You may use an IPv4 or IPv6 address as a value. IPv6 addresses or host names that resolve to IPv6 addresses must be enclosed in square brackets, as in [2001:0db8:0:0::200C:417A] and [salesdb].

port

Optional. Specify the listening port.

The default is 1521.

service_name

Optional. Specify the service name of the database.

If a user specifies a service name, then the listener connects the user to that specific database. Otherwise, the listener connects to the database specified by the DEFAULT_SERVICE_listener_name parameter in the listener.ora file. If DEFAULT_SERVICE_listener_name is not configured for the listener and a service name is not explicitly specified by the user as part of the Easy Connect syntax, then the listener returns an error.

server_type

Optional. Specify the database server type to use.

This parameter instructs the listener to connect the client to a specific type of service handler.

The values for the server_type parameter are dedicated, shared, and pooled. If server is not specified in the Easy Connect syntax, then the type of server is chosen by the listener (shared server if configured, otherwise a dedicated server is used).

Note: In Oracle Call Interface documentation, server is referred to as connect_type.

instance_name

Optional. Identify the database instance to access.

The instance name can be obtained from the INSTANCE_NAME parameter in the initialization parameter file.

Related Topics

Parent topic: Configuring the Easy Connect Naming Method

8.4.2 Support for Easy Connect Plus

Starting with Oracle Database 19c, the Easy Connect syntax that applications use to connect to Oracle Database supports an enhanced functionality known as Easy Connect Plus.

The Easy Connect Plus feature simplifies Oracle Database application configuration and deployment for common use cases. You do not need to configure Oracle Net parameter files, such as tnsnames.ora and sqlnet.ora. You also do not need to set the TNS_ADMIN environment variable.

With this enhancement, Easy Connect supports both the TCP and TCPS protocols (earlier, it supported only the TCP transport protocol). This simplifies the client configurations to Oracle Database Cloud Services that mandate TCPS connections for network security.

Syntax:

The enhanced Easy Connect syntax, using the Easy Connect Plus feature, is as follows:

[[protocol:]//]host1{,host12}[:port1]{,host2:port2}{;host1{,host12}[:port1]}[/[service_name][:server][/instance_name]][?parameter_name=value{&parameter_name=value}]

The question mark (?) indicates the start of name-value pairs and the ampersand (&) is the delimiter between the name-value pairs.

Here, the Easy Connect syntax includes:

  • Protocol: Easy Connect adapter supports specification of protocol as part of the connect string. This protocol is applicable to each host in the connect string.

  • Multihost or port: Easy Connect adapter can accept multiple hosts or ports in the connect string. This helps in load-balancing the client connections.

  • Name-Value pairs: Easy Connect adapter can accept a list of name value pairs. Each name-value pair is added as a DESCRIPTION level parameter.

    The following names are supported:

    • ENABLE
    • FAILOVER
    • LOAD_BALANCE
    • RECV_BUF_SIZE
    • SEND_BUF_SIZE
    • SDU
    • SOURCE_ROUTE
    • RETRY_COUNT
    • RETRY_DELAY
    • CONNECT_TIMEOUT
    • TRANSPORT_CONNECT_TIMEOUT

  • Address lists: Starting with Oracle Database 23ai, you can specify one or more address lists of protocol addresses that share common characteristics.

  • Security attributes: The following SECURITY attributes are supported for TLS:

    • SSL_SERVER_DN_MATCH=on/off
    • SSL_SERVER_CERT_DN=longDN
    • WALLET_LOCATION=Wallet location

Note:

The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client or listener.

For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION.

Examples

  • With a single protocol address using the ADDRESS parameter:

    The following syntax to specify the Session Data Unit (SDU)

    salesserver1:1521/sales.us.example.com?sdu=16384

    translates to the following connect descriptor:

    (DESCRIPTION=
  (SDU=16384) 
  (ADDRESS=(PROTOCOL=tcp)(HOST=saleserver1)(PORT=1521))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
)

    Similarly, the following syntax to specify connect timeout, transport connect timeout, and retry count values

    salesserver1:1521/sales.us.example.com?connect_timeout=1min&transport_connect_timeout=30sec&retry_count=3&retry_delay=2

    translates to the following connect descriptor:

    (DESCRIPTION=
   (retry_count=3)(retry_delay=2)
   (connect_timeout=1min)(transport_connect_timeout=30sec)
   (ADDRESS=(PROTOCOL=tcp)(HOST=salesserver1)(PORT=1521))
   (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
)

  • With multiple protocol addresses using the ADDRESS_LIST parameter:

    The following syntax to specify the Session Data Unit (SDU)

    salesserver1:1521;saleserver2:1522/sales.us.example.com?sdu=16384

    translates to the following connect descriptor:

    (DESCRIPTION=
  (SDU=16384) 
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=saleserver1)(PORT=1521))
  )
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=saleserver2)(PORT=1522))
  )
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
)

Related Topics

Parent topic: Configuring the Easy Connect Naming Method

8.4.3 Examples of Easy Connect Naming Method

Review some example Easy Connect strings and how each string converts into a connect descriptor.

Naming Option Connect String Connect Descriptor

With host.

The host name is sales-server. 

sales-server
 
(DESCRIPTION=
   (CONNECT_DATA=
       (SERVICE_NAME=))
   (ADDRESS=
       (PROTOCOL=TCP)
       (HOST=sales-server)
       (PORT=1521)))

With host and port.

The host name is sales-server, and the port is 3456. 

sales-server:3456
 
(DESCRIPTION=
   (CONNECT_DATA=
       (SERVICE_NAME=))
   (ADDRESS=
       (PROTOCOL=TCP)
       (HOST=sales-server)
       (PORT=3456)))

With host and service name.

The host name is sales-server and the service name is sales. 

sales-server/sales
 
(DESCRIPTION=
  (CONNECT_DATA=
     (SERVICE_NAME=sales))
  (ADDRESS=
     (PROTOCOL=TCP)
     (HOST=sales-server)
     (PORT=1521)))

With IPv6 address.

The IPv6 address of the host is 2001:0db8:0:0::200C:417A, the port is 80, and the service name is sales. 

[2001:0db8:0:0::200C:417A]:80/sales

Square brackets are required around IPv6 host names.

 
(DESCRIPTION=
  (CONNECT_DATA=
      (SERVICE_NAME=sales)
  (ADDRESS=
      (PROTOCOL=TCP)
      (HOST=2001:0db8:0:0::200C:417A)
      (PORT=80)))

With IPv6 host address.

The host is sales-server, the port is 80, and the service name is sales. 

sales-server:80/sales
 
(DESCRIPTION=
  (CONNECT_DATA=
      (SERVICE_NAME=sales)
  (ADDRESS=
      (PROTOCOL=TCP)
      (HOST=sales-server)
      (PORT=80)))

With host, service name, and server.

The host name is sales-server, the service name is sales, the server is dedicated, and the instance name is inst1

 
sales-server/sales:dedicated/inst1
 
(DESCRIPTION=
  (CONNECT_DATA=
      (SERVICE_NAME=sales)
      (INSTANCE_NAME=inst1)
      (SERVER=dedicated))
  (ADDRESS=
      (PROTOCOL=TCP)
      (HOST=sales-server)
      (PORT=1521)))

With host and instance name.

The host name is sales-server and the instance name is inst1. 

sales-server//inst1
 
(DESCRIPTION=
   (CONNECT_DATA=
      (SERVICE_NAME=)
      (INSTANCE_NAME=inst1))
   (ADDRESS=
      (PROTOCOL=TCP)
      (HOST=sales-server)
      (PORT=1521)))

Here are some sample Easy Connect strings using the Easy Connect Plus feature:

Naming Option Connect String Connect Descriptor

With a list of name value pairs (SDU, RETRY_COUNT, and CONNECT_TIMEOUT).

The host is salesserver, the port is 1521, and the service name is sales.

salesserver1:1521/sales?SDU=8128&retry_count=3&connect_timeout=10 
(DESCRIPTION=
  (SDU=8128)(retry_count=3)(connect_timeout=10)
  (ADDRESS=
    (PROTOCOL=tcp)
    (HOST=saleserver1)(PORT=1521)) 
    (CONNECT_DATA=(SERVICE_NAME=sales)))

With multiple hosts or ports.

The host is salesserver, the port is 1521, and the service name is sales.

salesserver1:1521,salesserver2,salesserver3:1522/sales 
((DESCRIPTION=
  (LOAD_BALANCE=ON) 
  (ADDRESS=
    (PROTOCOL=tcp)
    (HOST=sales-server1)
    (PORT=1521))
  (ADDRESS=
    (PROTOCOL=tcp)
    (HOST=sales-server2)
    (PORT=1522))
  (ADDRESS=
    (PROTOCOL=tcp)
    (HOST=sales-server3)
    (PORT=1522)))
  (CONNECT_DATA=(SERVICE_NAME=sales)))

With specification of protocol.

The host is salesserver, the port is 1521, and the service name is sales.

tcps://salesserver1:1521/sales 
(DESCRIPTION=
  (ADDRESS=
    (PROTOCOL=tcps)
    (HOST=salesserver1)
    (PORT=1521))
  (SECURITY=(SSL_SERVER_DN_MATCH=TRUE))
  (CONNECT_DATA=(SERVICE_NAME=sales)))

With SECURITY attributes supported for TLS.

The host is sales-server, the port is 1521, and the service name is sales.

tcps://sales-server:1521/sales?ssl_server_cert_dn="cn=sales,cn=OracleContext,dc=us,dc=example,dc=com"&wallet_location="/tmp/oracle"

Note: The parameter WALLET_LOCATION is deprecated for use with Oracle Database 23ai for the Oracle Database server. It is not deprecated for use with the Oracle Database client or listener.

For Oracle Database server, Oracle recommends that you use the WALLET_ROOT system parameter instead of using WALLET_LOCATION. 

(DESCRIPTION= 
  (ADDRESS=
    (PROTOCOL=tcps)
    (HOST=salesserver)
    (PORT=1521)) 
  (CONNECT_DATA=(SERVICE_NAME=sales))
  (SECURITY=
    (SSL_SERVER_DN_MATCH=TRUE)
    (SSL_SERVER_CERT_DN=cn=sales,cn=OracleContext,dc=us,dc=example,dc=com)
    (WALLET_LOCATION=/tmp/oracle)))

With ADDRESS_LIST to specify multiple protocol addresses.

salesserver1:1521;saleserver2:1522/sales.us.example.com?sdu=16384

 
(DESCRIPTION=
  (SDU=16384) 
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=saleserver1)(PORT=1521)))
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=saleserver2)(PORT=1522)))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

Related Topics

Parent topic: Configuring the Easy Connect Naming Method

8.4.4 Configuring Easy Connect Naming on the Client

Learn about the required conditions and configuration tasks that clients need to ensure before using the Easy Connect naming method.

Clients can connect to Oracle Database using Easy Connect naming if the following conditions are met:

  • Oracle Net Services software is installed on the client.

  • Oracle TCP/IP protocol is supported on both the client and database server.

  • No features require a more advanced connect descriptor.

Easy Connect naming is not suitable for large or complex environments with advanced features, such as external procedure calls, or Heterogeneous Services, that require additional connect information. In these cases, another naming method is recommended.

Easy Connect naming is automatically configured at installation. Before using it, you must ensure that EZCONNECT is specified by the NAMES.DIRECTORY_PATH parameter in the sqlnet.ora file. This parameter specifies the order of naming methods Oracle Net can use to resolve connect identifiers to connect descriptors.

Note:

If you use the Easy Connect naming method for TCPS connections (PROTOCOL=TCPS), then SSL_SERVER_DN_MATCH is set to TRUE by default. With the SSL_SERVER_DN_MATCH=TRUE setting, the client performs a partial DN matching to ensure that the server and listener certificates are valid.

If you want to check with the full DN (not partial DN), then you must also specify the DN in SSL_SERVER_CERT_DN. If you do not set SSL_SERVER_CERT_DN, then a partial DN match must succeed for the client to establish a connection to the server. If you set SSL_SERVER_CERT_DN, then a full DN match (with certificates for both the server and listener) must succeed for the client to establish a connection to the server.

The following procedure describes how to verify that the Easy Connect naming method is configured:

  1. Start Oracle Net Manager.

  2. In the navigator pane, expand Local, and then select Profile.

  3. From the list in the right pane, select Naming.

  4. Click the Methods tab.

    Verify that EZCONNECT is listed in the Selected Methods list. If it is not, then proceed to Step 5. If it is listed, then proceed to Step 7.

  5. From the Available Methods list, select EZCONNECT, and then click the right-arrow button.

  6. In the Selected Methods list, select EZCONNECT, and then use the Promote button to move the selection to the top of the list.

  7. Select Save Network Configuration from the File menu.

    The sqlnet.ora file updates the NAMES.DIRECTORY_PATH parameter, listing hostname first: 

    NAMES.DIRECTORY_PATH=(ezconnect, tnsnames)

Related Topics

Parent topic: Configuring the Easy Connect Naming Method

8.4.5 Configuring Easy Connect Naming to Use a DNS Alias

You can optionally configure a DNS alias for the host name, as provided with the host naming method.

With host naming, clients use a connect string that uses the following pattern:

CONNECT username@DNS_alias
Enter password: password

The following procedure describes how to configure a DNS alias:

  1. Ensure the database service is registered with the listener.

    If the database can find the listener, then information about the database service is dynamically registered with the listener during service registration, including the service name. The listener is found if the following conditions are met:

    • The default listener named LISTENER on TCP/IP, port 1521 is running.

    • The LOCAL_LISTENER parameter is set in the initialization file.

    If the database cannot find the listener, then you can configure static registration for the listener.

  2. Establish a host name resolution environment.

    You can configure a mechanism such as DNS, NIS, or a centrally-maintained TCP/IP host file, /etc/hosts. For example, if a service name of sales.us.example.com for a database exists on a computer named sales-server, then the entry in the /etc/hosts file would look like the following: 

    #IP address of server     host name       alias
192.0.2.35              sales-server    sales.us.example.com

    The domain section of the service name must match the network domain.

  3. Connect to the database using the DNS alias.

    Using the example in the previous step, the client can use sales.example.com in the connect string: 

    CONNECT username@sales.us.example.com
Enter password: password

    If the client and server are in the same domain such as us.example.com, then the client must enter only sales in the connect string.

Related Topics

Parent topic: Configuring the Easy Connect Naming Method