Local Naming Parameters in the tnsnames.ora File

Learn about the Oracle Net service names local naming parameters that you specify in the tnsnames.ora configuration file.

Overview of Local Naming Parameters

The tnsnames.ora file is a configuration file that contains network service names that are mapped to connect descriptors for the Local Naming method.

A net service name is an alias that is mapped to a database network address that is contained in a connect descriptor. A connect descriptor contains the location of the listener that is accessed through a protocol address and the service name of the database to which to connect. Clients and database servers that are clients of other database servers use the net service name when connecting with applications.

Typically, tools such as Oracle Database Configuration Assistant (DBCA) and Oracle Net Configuration Assistant (NETCA) create the tnsnames.ora file in the ORACLE_HOME/network/admin directory for Oracle Database installations, the GRID_HOME/network/admin directory for Oracle Grid Infrastructure installations, or the corresponding ORACLE_BASE_HOME/network/admin directory for a read-only Oracle home. Note that if you have installed multiple databases, then the file is created in the Oracle home or Grid home where DBCA or NETCA is run (or the Oracle base home for read-only instances).

The order for checking the tnsnames.ora file is:

  1. The directory specified by the TNS_ADMIN environment variable

  2. If the TNS_ADMIN environment variable is not set or the file is not found in the TNS_ADMIN directory:

    • On Linux and UNIX: The ORACLE_HOME/network/admin directory (or its ORACLE_BASE_HOME/network/admin directory for a read-only Oracle home)

    • On Windows: The ORACLE_HOME\network\admin directory (or its ORACLE_BASE_HOME\network\admin directory for a read-only Oracle home)

  3. For a read-only Oracle home, if the file is not found in the Oracle base home:

    • On Linux and UNIX: The ORACLE_HOME/network/admin directory

    • On Windows: The ORACLE_HOME\network\admin directory

Note:

Related Topics

General Syntax of tnsnames.ora

In this example, you can see the general tnsnames.ora file syntax.

Here, DESCRIPTION contains the connect descriptor, ADDRESS contains the protocol address, and CONNECT_DATA contains database service identification information.

Example 6-1 Basic Format of tnsnames.ora File

net_service_name=
 (DESCRIPTION=
   (ADDRESS=(protocol_address_information))
   (CONNECT_DATA=
     (SERVICE_NAME=service_name)
    )
  )

Using Multiple Descriptions in tnsnames.ora Files

In this example, you can see two connect descriptors with multiple addresses.

A tnsnames.ora file can contain net service names with one or more connect descriptors. Each connect descriptor can contain one or more protocol addresses.

Use the tnsnames.ora parameter DESCRIPTION_LIST to define the list of connect descriptors.

Example 6-2 Net Service Name with Multiple Connect Descriptors in tnsnames.ora

net_service_name=
 (DESCRIPTION_LIST=
  (DESCRIPTION=
 (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
 (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521))
 (CONNECT_DATA=
   (SERVICE_NAME=sales.us.example.com)))
(DESCRIPTION=
(ADDRESS=(PROTOCOL=tcp)(HOST=hr1-svr)(PORT=1521))
(ADDRESS=(PROTOCOL=tcp)(HOST=hr2-svr)(PORT=1521))
(CONNECT_DATA=
  (SERVICE_NAME=hr.us.example.com))))

Note: Oracle Net Manager does not support multiple connect descriptors for a net service name if you use Oracle Connection Manager.

Multiple Address Lists in tnsnames.ora Files

The tnsnames.ora file supports connect descriptors with multiple lists of addresses, each with its own characteristics. Learn how to configure multiple address lists in tnsnames.ora files.

The following example shows two address lists. The first address list features client load balancing and no connect-time failover. These setting apply only to protocol addresses that are within its ADDRESS_LIST. The second protocol address list does not enable client load loading balancing, but the list does enable connect-time failover. These settings affect only protocol addresses that are included in its ADDRESS_LIST. The client first tries the first or second protocol address at random, then it tries protocol addresses number three and four, in that order, and so on.

Example 6-3 Multiple Address Lists in tnsnames.ora Files

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
   (LOAD_BALANCE=on)
   (FAILOVER=off)
   (ADDRESS=(protocol_address_information))
   (ADDRESS=(protocol_address_information)))
  (ADDRESS_LIST=
   (LOAD_BALANCE=off)
   (FAILOVER=on)
   (ADDRESS=(protocol_address_information))
   (ADDRESS=(protocol_address_information)))
  (CONNECT_DATA=
   (SERVICE_NAME=service_name)))

Note:

Connect-Time Failover and Client Load Balancing with Oracle Connection Managers

When tnsnames.ora connect descriptors have at least two protocol addresses for Oracle Connection Manager, you can also include parameters for connect-time failover and load balancing in the file.

Example 6-4 Multiple Oracle Connection Manager Addresses in tnsnames.ora

This example illustrates the failover of multiple Oracle Connection Manager protocol addresses.

sample1=
 (DESCRIPTION=
   (SOURCE_ROUTE=yes)
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))    # 1
     (ADDRESS_LIST=
       (FAILOVER=on)
       (LOAD_BALANCE=off)                               #  2
       (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630))
       (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630)))
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1521)))    #  3
   (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

The previous syntax does the following:

  1. The client connects to the protocol address of the first Oracle Connection Manager as indicated by:

    (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))

  2. Oracle Connection Manager connects to the first protocol address of another Oracle Connection Manager. If the first protocol address fails, then it tries to connect to the second protocol address. This sequence is specified with the following configuration:

    (ADDRESS_LIST= (FAILOVER=on) (LOAD_BALANCE=off) (ADDRESS=(PROTOCOL=tcp)(HOST=host2a)(PORT=1630)) (ADDRESS=(PROTOCOL=tcp)(HOST=host2b)(PORT=1630)))

  3. Oracle Connection Manager connects to the database service using the following protocol address:

    (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(PORT=1521))

Example 6-5 Client Load Balancing in tnsnames.ora

This example illustrates client load balancing among two Oracle Connection Managers and two protocol addresses:

sample2=
 (DESCRIPTION=
   (LOAD_BALANCE=on)                                    # 1
   (FAILOVER=on)
   (ADDRESS_LIST=
     (SOURCE_ROUTE=yes)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=1630))    # 2
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=1521)))
  (ADDRESS_LIST=
     (SOURCE_ROUTE=yes)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=1630))
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=1521)))
   (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))  # 3

The previous syntax does the following:

  1. The client selects an ADDRESS_LIST at random and fails over to the other address if the chosen ADDRESS_LIST fails. This is indicated if you set the LOAD_BALANCE and FAILOVER parameters to on.

  2. When an ADDRESS_LIST is chosen, the client first connects to Oracle Connection Manager using the Oracle Connection Manager protocol address that uses port 1630 as is indicated for the ADDRESS_LIST.

  3. Oracle Connection Manager then connects to the database service using the protocol address that is indicated for the ADDRESS_LIST.

Connect Descriptor Descriptions

Specify connect descriptors using the DESCRIPTION parameter. Identify multiple connect descriptors with the DESCRIPTION_LIST parameter.

DESCRIPTION_LIST

The DESCRIPTION_LIST parameter of the tnsnames.ora file defines a list of connect descriptors for a particular net service name.

Purpose

To define a list of connect descriptors for a particular net service name.

Example 6-6 Example

net_service_name=
(DESCRIPTION_LIST=
 (DESCRIPTION=
  (ADDRESS=...)
  (CONNECT_DATA=(SERVICE_NAME=sales.example.com)))
 (DESCRIPTION=

DESCRIPTION

Use the tnsnames.ora file DESCRIPTION parameter to specify connect descriptor containers.

Purpose

To specify a container for a connect descriptor.

Usage Notes

When using more than one DESCRIPTION parameter, place the parameters under the DESCRIPTION_LIST parameter.

Example 6-7 DESCRIPTION Parameter Example

net_service_name=
(DESCRIPTION=
  (ADDRESS=...)
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

Protocol Addresses

The protocol address section of a tnsnames.ora file specifies listener protocol addresses.

If there is only one listener protocol address, then use the ADDRESS parameter. If there is more than one address, then use the ADDRESS_LIST parameter.

ADDRESS

The tnsnames.ora parameter ADDRESS specifies protocol addresses with the ADDRESS_LIST for multiple addresses or with the DESCRIPTION parameter for one listener.

Purpose

To specify one listener protocol address.

Usage Notes

Put this parameter under either the ADDRESS_LIST parameter or the DESCRIPTION parameter.

ADDRESS Parameter Example

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

HTTPS_PROXY

Learn to use the tnsnames.ora parameter HTTPS_PROXY to specify HTTP proxy host names to tunnel Transport Layer Security (TLS) client connections.

Purpose

To specify HTTP proxy host names for tunneling your TLS client connections.

Usage Notes

Your clients can tunnel secure connections over HTTP proxy using the HTTP CONNECT method. This helps access the public cloud database service because it eliminates the need to open an outbound port on a client-side firewall. This parameter is applicable only to the connect descriptors where PROTOCOL=TCPS. This is similar to the web browser setting for intranet users who want to connect to internet hosts. You can increase the forward web proxy read timeout for requests to a higher value depending on client queries. Otherwise, the forward web proxy closes the connection assuming that no requests are made from the client.

A successful connection depends on your specific proxy configurations. The performance of your data transfers depend on the proxy capacity. Oracle recommends against using this feature in production environments where performance is critical.

Configuring tnsnames.ora for an HTTP proxy may not be secure enough, depending your organization’s network configuration and security policies. For example, some networks require a user name and password for the HTTP proxy.

Oracle Client versions earlier than 18c does not support connections through HTTP proxy.

Contact your network administrator to open outbound connections to hosts that are in the oraclecloud.com domain by using the relevant port, without going through an HTTP proxy. For example, port 1522.

Default

None

Values

An HTTP proxy host name that can make an outbound connection to internet hosts.

Example

HTTPS_PROXY=www-proxy.example.com

HTTPS_PROXY_PORT

Learn how to use the tnsnames.ora parameter HTTPS_PROXY_PORT to specify forward HTTP proxy host ports for tunneling Transport Layer Security (TLS) client connections.

Purpose

To specify forward HTTP proxy host port for tunneling TLS client connections.

Usage Notes

It forwards the HTTP proxy host port that receives the HTTP CONNECT method. Use this parameter with HTTPS_PROXY_PORT. The value for the HTTPS_PROXY_PORT parameter takes effect only when you set SQLNET.USE_HTTPS_PROXY=1 set in your sqlnet.ora file.

Default

none

Values

port number

Example

HTTPS_PROXY_PORT=80

ADDRESS_LIST

The ADDRESS_LIST networking parameter specifies the number of protocol addresses.

Purpose

To define a list of protocol addresses.

Usage Notes

If there is only one listener protocol address, then ADDRESS_LIST is not necessary.

Put this parameter either under the DESCRIPTION parameter or the DESCRIPTION_LIST parameter.

Example

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

Optional Parameters for Description

Use these parameters to configure connect descriptor containers under the DESCRIPTION parameter.

ENABLE

Use the ENABLE parameter to enable the keepalive feature on the supported TCP transports.

Purpose

To allow the caller to detect a terminated remote server; typically it takes 2 hours or more to notice.

Usage Notes

The keepalive feature on the supported TCP transports can be enabled for a net service client by putting (ENABLE=broken) under the DESCRIPTION parameter in the connect string. On the client side, the default for tcp_keepalive is off. Operating system TCP configurables, which vary by platform, define the actual keepalive timing details.

Values

broken

Example

net_service_name=
 (DESCRIPTION=
  (ENABLE=broken)
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))

Although the preceding example has multiple addresses, the ADDRESS_LIST parameter was not used. This is because the ADDRESS_LIST parameter is not mandatory.

EXPIRE_TIME

Use the EXPIRE_TIME parameter to specify how often, in minutes, to verify that the remote server connection is alive.

Purpose

To specify time intervals, in minutes, for how often to verify that the remote server connection is alive.

Usage Notes

Oracle Net Services tunes the TCP keepalive parameters so that probes are sent after an idle activity.

Limitations on using the terminated connection detection feature are:

Default

0

Minimum Value

0

Recommended Value

10

Example

net_service_name=
   (DESCRIPTION=
     (EXPIRE_TIME=10)
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521)))
     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))

FAILOVER

Use the FAILOVER parameter to enable or disable connect-time failover for multiple protocol addresses.

Purpose

To enable or disable connect-time failover for multiple protocol addresses.

Usage Notes

When you set the parameter to on, yes, or true, Oracle Net fails over at connect time to a different address if the first protocol address fails. When you set the parameter to off, no, or false, Oracle Net tries one protocol address.

Put this parameter under the DESCRIPTION_LIST parameter, the DESCRIPTION parameter, or the ADDRESS_LIST parameter.

Note: Do not set the GLOBAL_DBNAME parameter in the SID_LIST_listener_name section of the listener.ora. A statically configured global database name disables connect-time failover.

Default

on for the DESCRIPTION_LIST, DESCRIPTION, and ADDRESS_LIST parameters

Values

Example

net_service_name=
 (DESCRIPTION=
  (FAILOVER=on)
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

LOAD_BALANCE

Use the LOAD_BALANCE parameter to enable or disable client load balancing for multiple protocol addresses.

Purpose

To enable or disable client load balancing for multiple protocol addresses.

Usage Notes

When you set the parameter to on, yes, or true, Oracle Net goes through the list of addresses in a random sequence, balancing the load on the various listener or Oracle Connection Manager protocol addresses. When you set the parameter to off, no, or false, Oracle Net tries the protocol addresses sequentially until one succeeds.

Put this parameter under the DESCRIPTION_LIST parameter, the DESCRIPTION parameter, or the ADDRESS_LIST parameter.

Default

on under DESCRIPTION_LIST

off under DESCRIPTION, ADDRESS_LIST, and ADDRESS

Values

Example

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (LOAD_BALANCE=on)
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)))

RECV_BUF_SIZE

Use the RECV_BUF_SIZE parameter to specify buffer space for session receive operations.

Purpose

To specify, in bytes, the buffer space for receive operations of sessions.

Usage Notes

This parameter is supported by the TCP/IP, TCP/IP with TLS, and SDP protocols.

Put this parameter under the DESCRIPTION parameter or at the end of the protocol address.

Setting this parameter in the connect descriptor for a client overrides the RECV_BUF_SIZE parameter at the client-side sqlnet.ora file.

Note: Additional protocols might support this parameter on certain operating systems. Refer to the operating system-specific documentation for additional information about additional protocols.

Default

The default value for this parameter is specific to the operating system. The default for the Linux 2.6 operating system is 87380 bytes.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521)
        (RECV_BUF_SIZE=11784))
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)
        (RECV_BUF_SIZE=11784))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)))
net_service_name=
 (DESCRIPTION=
   (RECV_BUF_SIZE=11784)
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=hr1-server)(PORT=1521))
     (ADDRESS=(PROTOCOL=tcp)(HOST=hr2-server)(PORT=1521)))
   (CONNECT_DATA=
     (SERVICE_NAME=hr.us.example.com)))

Related Topics

SDU

Use the SDU parameter to configure the session data unit (SDU) size.

Purpose

To instruct Oracle Net to optimize the transfer rate of data packets being sent across the network with a specified SDU size.

Usage Notes

Put this parameter under the DESCRIPTION parameter.

Setting this parameter in the connect descriptor for a client overrides the DEFAULT_SDU_SIZE parameter at client-side sqlnet.ora file.

Default

8192 bytes (8 KB)

Values

512 to 2097152 bytes

Example

net_service_name=
 (DESCRIPTION=
  (SDU=8192)
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521))
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com))

Related Topics

SEND_BUF_SIZE

Use the SEND_BUF_SIZE parameter to specify buffer space for session send operations.

Purpose

To specify, in bytes, the buffer space for send operations of sessions.

Usage Notes

This parameter is supported by the TCP/IP, TCP/IP with TLS, and SDP protocols.

Put this parameter under the DESCRIPTION parameter or at the end of the protocol address.

Setting this parameter in the connect descriptor for a client overrides the SEND_BUF_SIZE parameter at the client-side sqlnet.ora file.

Note: Additional protocols might support this parameter on certain operating systems. Refer to the operating system-specific documentation for information about additional protocols.

Default

The default value for this parameter is operating system specific. The default for the Linux 2.6 operating system is 16 KB.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521)
        (SEND_BUF_SIZE=11784))
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)
        (SEND_BUF_SIZE=11784)))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)))
net_service_name=
 (DESCRIPTION=
   (SEND_BUF_SIZE=11784)
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=hr1-server)(PORT=1521)
     (ADDRESS=(PROTOCOL=tcp)(HOST=hr2-server)(PORT=1521)))
   (CONNECT_DATA=
     (SERVICE_NAME=hr.us.example.com)))

Related Topics

SOURCE_ROUTE

Use the SOURCE_ROUTE parameter to enable routing through multiple protocol addresses.

Purpose

To enable routing through multiple protocol addresses.

Usage Notes

When you set this parameter to on or yes, Oracle Net uses each address in order until the destination is reached.

To use Oracle Connection Manager, an initial connection from the client to Oracle Connection Manager is required, and a second connection from Oracle Connection Manager to the listener is required.

Put this parameter under either the DESCRIPTION_LIST parameter, the DESCRIPTION parameter, or the ADDRESS_LIST parameter.

Default

off

Values

Example

net_service_name=
 (DESCRIPTION=
  (SOURCE_ROUTE=on)
  (ADDRESS=(PROTOCOL=tcp)(HOST=cman-pc)(PORT=1630))
  (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
  (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))

Related Topics

TYPE_OF_SERVICE

Use the TYPE_OF_SERVICE parameter to specify the type of service to use for an Oracle Rdb database.

Purpose

To specify the type of service to use for an Oracle Rdb database.

Usage Notes

This parameter should only be used if the application supports both an Oracle Rdb and Oracle database service, and you want the application to load balance between the two.

Put this parameter under the DESCRIPTION parameter.

Example

net_service_name=
 (DESCRIPTION_LIST=
  (DESCRIPTION=
   (ADDRESS=...)
   (CONNECT_DATA=
    (SERVICE_NAME=generic)
    (RDB_DATABASE=[.mf]mf_personal.rdb)
    (GLOBAL_NAME=alpha5))
   (TYPE_OF_SERVICE=rdb_database))
  (DESCRIPTION=
   (ADDRESS=...)
   (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com))
   (TYPE_OF_SERVICE=oracle11_database)))

Related Topics

USE_SNI

Use the USE_SNI parameter to set Server Name Indication (SNI) value using CONNECT_DATA parameters for TLS connections.

Purpose

To enable or disable setting of SNI value using CONNECT_DATA parameters for TLS connections through connect descriptor.

Usage Notes

When USE_SNI is set and CONNECT_DATA has any of the supported parameters for SNI, then those parameters are used to set the SNI value. This SNI value is then used by the listener to select the appropriate service handler for servicing the request without having to do a TLS handshake with the client. The supported CONNECT_DATA parameters for setting SNI include SERVICE_NAME, INSTANCE_NAME, SERVER and COLOCATION_TAG.

When USE_SNI is set and CONNECT_DATA doesn’t include any of the supported parameters listed above, then SNI value will not be set and the listener will perform the usual TLS handshake with the client to fetch the connect request.

Values

Default Value

OFF

Example

net_service_name=
            (DESCRIPTION=
              (USE_SNI=ON)
              (ADDRESS_LIST=
               (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521))
               (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)))
              (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))

Note: Support for SNI is available in all versions starting 23.7, but not in earlier versions.

Related Topics

Connection Data Section

Learn how to configure network connections with protocol addresses.

A network object is identified by a protocol address. When a connection is made, the client and the receiver of the request (listener or Oracle Connection Manager) are configured with identical protocol addresses. The client uses this address to send the connection request to a particular network object location, and the recipient “listens” for requests on this address, and grants a connection based on its address information matching the client information.

CONNECT_DATA

Use the CONNECT_DATA parameter to define the connection service.

Purpose

To define the service to which you want to connect, such as SERVICE_NAME.

Usage Notes

Put this parameter under the DESCRIPTION parameter. CONNECT_DATA permits additional parameters as listed in Connection Data Section.

Example

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)))

COLOCATION_TAG

Purpose

To direct the listener to route all connections with the same colocation_tag to the same database instance.

Usage Notes

Use this parameter with the CONNECT_DATA parameter.

The parameter value must be an alphanumeric string.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
    (ADDRESS=...)
    (ADDRESS=...))
 (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (COLOCATION_TAG=abc)))

Note: Under certain conditions, such as, when maximum load of an instance is reached or when new instances are added or deleted for a service, the colocation of client connections that have the same colocation_tag to the same database instance may not be consistent.

CONNECTION_ID_PREFIX

Use this parameter to add application specific ID to connection identifier.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
(DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)
     ((CONNECTION_ID_PREFIX=value)))

Note: The CONNECTION_ID_PREFIX value is appended internally to a system generated connection ID value and sent as CONNECTION_ID in connect string. The CONNECTION_ID_PREFIX must be an 8-byte alphanumeric identifier limited to the following [a…z] [A…Z] [0…9] _ character set.

Related Topics

FAILOVER_MODE

Purpose

To instruct Oracle Net to fail over to a different listener if the first listener fails during run time.

Usage Notes

Depending upon the configuration, the session or any SELECT statements which were in progress are automatically failed over.

This type of failover is called Transparent Application Failover (TAF) and should not be confused with the connect-time failover FAILOVER parameter.

Put this parameter under the CONNECT_DATA parameter.

Additional Parameters

FAILOVER_MODE supports the following parameters:

Note: If a callback function is registered, then RETRIES and DELAY parameters are ignored.

Related Topics

GLOBAL_NAME

Purpose

To identify the Oracle Rdb database.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
    (ADDRESS=...)
    (ADDRESS=...))
   (CONNECT_DATA=
    (SERVICE_NAME=generic)
    (RDB_DATABASE=[.mf]mf_personal.rdb)
    (GLOBAL_NAME=alpha5)))

HS

Purpose

To direct Oracle Net to connect to a non-Oracle system through Heterogeneous Services.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Default

None

Values

ok

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
    (SID=sales6)
    )
(HS=ok))

Related Topics

INSTANCE_NAME

Purpose

To identify the database instance to access.

Usage Notes

Set the value to the value specified by the INSTANCE_NAME parameter in the initialization parameter file.

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)
     (INSTANCE_NAME=sales1)))

See Also: Oracle Database Net Services Administrator’s Guide for additional information about the use of INSTANCE_NAME

POOL_BOUNDARY

Use the POOL_BOUNDARY parameter to enable implicit connection pooling with either Database Resident Connection Pooling (DRCP) or Proxy Resident Connection Pooling (PRCP).

Purpose

To enable implicit connection pooling with either DRCP (on the database server side) or PRCP (for Oracle Connection Manager in Traffic Director Mode). This setting specifies a time boundary to release an application session back to the DRCP or PRCP pool. You can set implicit connection pooling at a statement or transaction boundary.

If you omit this parameter setting, then implicit connection pooling is disabled.

Usage Notes

Default

None

Values and Examples

Value Example
STATEMENT: To set implicit connection pooling at a statement boundary

Easy connect string:

sales1-server:1521/sales.us.example.com:pooled?pool_boundary=statement

Connect descriptor in tnsnames.ora:

inst1= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=sales.us.example.com) (SERVER=POOLED) (POOL_BOUNDARY=STATEMENT)) )

TRANSACTION: To set implicit connection pooling at a transaction boundary

Easy connect string: 

sales1-server:1521/sales.us.example.com:pooled?pool_boundary=transaction

Connect descriptor in tnsnames.ora:

inst1= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521)) (CONNECT_DATA= (SERVICE_NAME=sales.us.example.com) (SERVER=POOLED) (POOL_BOUNDARY=TRANSACTION)) )

The following example of a connect descriptor in tnsnames.ora shows how to set implicit connection pooling in different modes:

inst1s=
    (DESCRIPTION=
        (ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))
        (CONNECT_DATA=
            (SERVICE_NAME=sales.us.example.com)
            (SERVER=POOLED)
            (POOL_BOUNDARY=STATEMENT))
    )
inst1t=
    (DESCRIPTION=
        (ADDRESS=(PROTOCOL=tcp)(HOST=proxy-server)(PORT=1522))
        (CONNECT_DATA=
            (SERVICE_NAME=sales.us.example.com)
            (SERVER=POOLED)
            (POOL_BOUNDARY=TRANSACTION))
    )

For the inst1s application instance, POOL_BOUNDARY=STATEMENT specifies that implicit connection pooling applies at a statement boundary. HOST=sales-server and PORT=1521 specify a DRCP connection through the database server.

For the inst1t application instance, POOL_BOUNDARY=TRANSACTION specifies that implicit connection pooling applies at a transaction boundary. HOST=proxy-server and PORT=1522 specify a PRCP connection through Oracle Connection Manager in Traffic Director Mode.

Related Topics

POOL_CONNECTION_CLASS

Use this parameter to explicitly name the connection class for Database Resident Connection Pooling (DRCP) connections.

Usage Notes

Add this parameter in the connect string under CONNECT_DATA section of the connect identifier. This parameter takes precedence and overrides the properties programmatically set by the application using this connect string.

Example

ServerPool =
 (DESCRIPTION=
   (ADDRESS=(PROTOCOL=tcp) (HOST=sales-svr) (PORT=1521))
   (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)(SERVER=POOLED)(POOL_CONNECTION_CLASS=value)))

Related Topics

POOL_NAME

Use the POOL_NAME parameter to specify a pool name for multi-pool Database Resident Connection Pooling (DRCP) connections.

Purpose

To specify a pool name for each connection in multi-pool DRCP. This enables client applications or services to establish connections from specific DRCP pools.

With this setting, DRCP marks the connection against the appropriate pooled server. If you do not set this parameter, then the connection is established from the default pool if it is active.

Usage Notes

Use this parameter under the CONNECT_DATA section of the tnsnames.ora file or directly as part of the command-line connect string.

When the client connects with POOL_NAME=pool_name along with the SERVER=POOLED setting, DRCP checks whether a DRCP pool with the given pool name is added in the database:

Database administrators add a DRCP pool at the PDB or CDB level. Static data dictionary view DBA_CPOOL_INFO contains information about existing DRCP pools. For example, this query lists all the available active pools:

SELECT * FROM DBA_CPOOL_INFO WHERE status='ACTIVE';

Value

DRCP pool name

Default

None

Example

(DESCRIPTION=
  (ADDRESS=
    (PROTOCOL=TCP)
    (HOST=sales-svr)
    (PORT=1522)
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (SERVER=POOLED)
    (POOL_NAME=mypool)
  )
)

Related Topics

POOL_PURITY

Use this parameter to specify if an application needs a new session that is not tainted with any prior session state or to reuse a previous session.

Usage Notes

Starting with Oracle Database 21c, you can configure Database Resident Connection Pooling (DRCP) for specific pluggable databases (PDBs). Add this parameter in the connect string under CONNECT_DATA section of the connect identifier to set purity attributes to a DRCP connection request.

This parameter takes precedence and overrides the properties programmatically set by the application using this connect string.

Values

NEW/SELF

Example

ServerPool =
 (DESCRIPTION=
   (ADDRESS=(PROTOCOL=tcp) (HOST=sales-svr) (PORT=1521))
   (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)(SERVER=POOLED)(POOL_PURITY=value)))

Related Topics

RDB_DATABASE

Purpose

To specify the file name of an Oracle Rdb database.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)
     (RDB_DATABASE= [.mf]mf_personal.rdb)))

SHARDING_KEY

Use the SHARDING_KEY parameter to route the database connection request to an appropriate shard.

Purpose

To specify the value of a sharding key. Based on the value specified during a database connection request, the request is directly routed to the appropriate shard.

Usage Notes

You specify this parameter under the CONNECT_DATA section of a connect string or tnsnames.ora file.

Use the SHARDING_KEY parameter to specify a sharding key in simplified text format. This parameter supports only ASCII character set and not special characters. The following data types are supported for a sharding key:

Use the SHARDING_KEY_B64 parameter to specify the base64-encoded binary representation of a sharding key. This parameter supports these special characters: " quotation mark , comma ( ) close parenthesis + plus sign)

Values

The fields for base64-encoded values (*_B64) start with a header, which is a sequence of space-separated integer values:

(CONNECT_DATA=
  (SHARDING_KEY_B64=
    [version][type][key column 1 type identifier][key column 2 type identifier] ... ,[base64 string],[base64 string],[base64 string],...))...

In the above syntax:

Example 6-8

In the following sample connect string, the SHARDING_KEY parameter value is specified in simplified text format:

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(host=sales-east1)(port=1522))
    (ADDRESS=(host=sales-east2)(port=1522))
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (SHARDING_KEY=40598230)
  )
 )

Example 6-9

In the following sample connect string, the SHARDING_KEY_B64 parameter value is encoded to base64 binary representation:

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(host=sales-east1)(port=1522))
    (ADDRESS=(host=sales-east2)(port=1522))
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (SHARDING_KEY_B64=1 1 2,VVM=,OTQwMDI=)
  )
 )

Related Topics

SHARDING_KEY_ID

Use this parameter to route the database connection request to a shard using the unique SHA-256 ID of a sharding key (instead of a sharding key value).

Purpose

If you are using hashing to encrypt sharding keys, then use this parameter to specify the unique SHA256 hash value assigned to a sharding key. Based on the value specified during the database connection request, the request is directly routed to the appropriate shard.

Usage Notes

You use this parameter for directory-based sharding.

Set this parameter under the CONNECT_DATA section of a connect string or tnsnames.ora file.

Value

SHA256 hash value of a sharding key in simplified text format. This value supports only the RAW data type.

You must enclose the value in single quotation marks.

Default

None

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
    (ADDRESS=(host=sales-east1)(port=1522))
    (ADDRESS=(host=sales-east2)(port=1522))
   )
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)
     (SHARDING_KEY_ID='7E01C6D3F5AF3116668AFB6B2376DAA457165A34020617884C216F1ADAA25C7B')
   )
 )

Related Topics

SUPER_SHARDING_KEY

Use the SUPER_SHARDING_KEY parameter in the case of composite sharding to route the database request to a collection of shards (shardspace).

Purpose

To specify a shardspace key for a collection of shards. A shardspace is set of shards that store data that corresponds to a range or list of key values. Based on the value specified during a database connection request, the request is directly routed to an appropriate shardspace.

Usage Notes

You specify this parameter under the CONNECT_DATA section of a connect string or tnsnames.ora file.

Use the SUPER_SHARDING_KEY parameter to specify a shardspace key for a collection of shards in simplified text format. This parameter supports only ASCII character set and not special characters. The supported data types for a super sharding key are the same as those for a sharding key.

Use the SUPER_SHARDING_KEY_B64 parameter to specify the base64-encoded binary representation of a shardspace key. This parameter supports special characters (such as “ quotation mark , comma ( ) close parenthesis + plus sign).

Values

The fields for base64-encoded values (*_B64) start with a header, which is a sequence of space-separated integer values:

(CONNECT_DATA=(SUPER_SHARDING_KEY_B64=[version] [type] [integer literal] [integer literal] ... ,[base64 binary],[base64 binary],[base64 binary],...))...

For details on each of the base64-encoded header fields, see SHARDING_KEY.

Example 6-10

In the following sample connect string, the SHARDING_KEY and SUPER_SHARDING_KEY parameter values are specified in simplified text format:

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(host=sales-east1)(port=1522))
    (ADDRESS=(host=sales-east2)(port=1522))
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    ((SHARDING_KEY=40598230)(SUPER_SHARDING_KEY=gold))
  )
 )

Example 6-11

In the following sample connect string, the SHARDING_KEY_B64 and SUPER_SHARDING_KEY_B64 parameter values are encoded to base64 binary representation:

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(host=sales-east1)(port=1522))
    (ADDRESS=(host=sales-east2)(port=1522))
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    ((SHARDING_KEY_B64=1 1 2,VVM=,OTQwMDI=)(SUPER_SHARDING_KEY_B64=1 1,BBWEPGRBBDOEMGQW))
  )
 )

Related Topics

SERVER

Purpose

To direct the listener to connect the client to a specific type of service handler.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Values

Note:

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (SERVER=dedicated)))

SERVER_WAIT_TIMEOUT

Use the SERVER_WAIT_TIMEOUT parameter to specify the maximum time a client waits for an available pooled server when using Database Resident Connection Pooling (DRCP).

Purpose

To limit the duration a client waits for a pooled server in DRCP. This prevents indefinite waits and allows the client to handle timeout scenarios appropriately.

The wait interval, in seconds, starts when the client request is placed on the DRCP broker’s wait list and ends when the request is assigned a pooled server or the timeout expires.

Usage Notes

Use this parameter under the CONNECT_DATA section of the tnsnames.ora file or directly as part of the command-line connect string.

When the client configures the SERVER_WAIT_TIMEOUT parameter together with the SERVER=POOLED setting, the client will wait for the specified duration for an available pooled server before timing out. If the timeout period elapses before a pooled server becomes available:

Default

None

Example

(DESCRIPTION=
  (ADDRESS=
    (PROTOCOL=TCP)
    (HOST=sales-svr)
    (PORT=1522)
  )
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)
    (SERVER=POOLED)
    (SERVER_WAIT_TIMEOUT=30)
  )
)

Related Topics

SERVICE_NAME

Purpose

To identify the Oracle Database database service to access.

Usage Notes

Set the value to a value specified by the SERVICE_NAMES parameter in the initialization parameter file.

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)))

Related Topics

TUNNEL_SERVICE_NAME

Set this parameter to identify the client CMAN.

Purpose

The server CMAN listener will route the connection to a gateway that has a tunnel connection to the requested client ID.

Usage Notes

Put this parameter under the CONNECT_DATA parameter.

Example

net_service_name=
(DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=...)
     (ADDRESS=...))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com)
     (TUNNEL_SERVICE_NAME=south)))

Related Topics

Security Section

The security section of the tnsnames.ora file specifies these security-related parameters for use with Oracle security features.

AUTHENTICATION_SERVICE

Use the tnsnames.ora parameter AUTHENTICATION_SERVICE to enable an authentication service.

Purpose

To enable an authentication service. If you have installed authentication, then Oracle recommends that you set AUTHENTICATION_SERVICE to either NONE or to one of the listed authentication methods.

Usage Notes

Default

ALL

Note: When installing Oracle Database with Database Configuration Assistant (DBCA), you can set this parameter to NTS in the sqlnet.ora file.

Values

Authentication methods that are available with Oracle Net Services:

Example

net_service_name=
    (DESCRIPTION=
        (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
        (SECURITY=(AUTHENTICATION_SERVICE=KERBEROS5))
        (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
    )

Related Topics

AZURE_DB_APP_ID_URI

Use the AZURE_DB_APP_ID_URI parameter to specify the application ID URI of the Oracle Database instance, registered with Microsoft Entra ID (previously called Microsoft Azure Active Directory).

Purpose

To specify the application ID URI that uniquely identifies your database instance in Entra ID.

This URI value is used to compose the authorization scope (permission) of your database token request during token-based authentication:

$Scope = "database_app_id_uri/scope"

For example:

$Scope = "https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3/session:scope:connect"

Here, the app ID URI https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3 is part of the scope.

Usage Notes

This parameter is mandatory. You must set it along with the TOKEN_AUTH parameter for the AZURE_INTERACTIVE, AZURE_SERVICE_PRINCIPAL, AZURE_MANAGED_IDENTITY, and AZURE_DEVICE_CODE authentication flows.

For the JDBC-thin clients, you can specify this parameter in the connect string, Easy Connect syntax, tnsnames.ora file, or properties. For the thick clients (OCI and Instant Client) and ODP.NET core and managed database clients, you can specify this parameter in the connect string, sqlnet.ora file, Easy Connect syntax, or tnsnames.ora file. The parameter value specified in the connect string takes precedence.

Default

None

Value

You can get the application ID URI value by logging in to the Azure portal. This is listed as the Application ID URI value on the App registrations - Overview page.

Note that this is the value that you specified while registering your Oracle Database instance with the Entra ID tenancy, as shown in Oracle AI Database Security Guide.

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=AZURE_INTERACTIVE)
          (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
TOKEN_AUTH=AZURE_INTERACTIVE
AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=AZURE_INTERACTIVE&AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3

In these examples, the CLIENT_ID, TENANT_ID, and REDIRECT_URI parameters are not specified. CLIENT_ID and TENANT_ID are required parameters when using the thick clients (OCI and Instant Client). These parameters are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration.

Related Topics

CLIENT_CERTIFICATE

Use the CLIENT_CERTIFICATE parameter to specify the file system path to a client certificate that authenticates your database client application.

Purpose

File system path to a client certificate that authenticates your database client application in Microsoft Entra ID. A client certificate is the digital certificate of an Azure cloud resource, and the client uses this certificate as a credential to prove its identity when requesting an Entra ID access token. This is used for the AZURE_SERVICE_PRINCIPAL token-based authentication flow.

Note: Only the JDBC-thin clients and ODP.NET core and managed database clients (and not the thick clients, such as OCI and Instant Client) support certificate-based authentication.

Usage Notes

Default

None

Value

Full path (including a file name) to the Azure certificate file

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL)
          (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)
          (CLIENT_CERTIFICATE=ORACLE_HOME/.azure/certificates/my-app.pem))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL&AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3&CLIENT_CERTIFICATE=ORACLE_HOME/.azure/certificates/my-app.pem

In these examples, the CLIENT_ID and TENANT_ID parameters are not specified. These parameters are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration.

Related Topics

CLIENT_ID

Use the CLIENT_ID parameter to specify the ID of the database client Microsoft Entra ID app registration.

Purpose

To specify the client ID assigned to your database client during Entra ID app registration. Note that this is not the client ID for the database server. This application is your database client that requests to get an access token for the user during Azure token-based authentication.

Usage Notes

You use this parameter along with the TOKEN_AUTH parameter for the AZURE_INTERACTIVE, AZURE_SERVICE_PRINCIPAL, AZURE_MANAGED_IDENTITY, and AZURE_DEVICE_CODE authentication flows, as follows:

Note that this parameter is mandatory for the OCI and Instant Clients. It is optional only when using the JDBC-thin clients and ODP.NET core and managed database clients.

For the JDBC-thin clients, you can specify this parameter in the connect string, Easy Connect syntax, tnsnames.ora file, or properties. For the thick clients (OCI and Instant Client) and ODP.NET core and managed database clients, you can specify this parameter in the connect string, sqlnet.ora file, Easy Connect syntax, or tnsnames.ora file. The parameter value specified in the connect string takes precedence.

Default

None

Value

You can get the client ID value by logging in to the Azure portal. This is listed as the Application (client) ID value on the App registrations - Overview page.

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=AZURE_INTERACTIVE)
          (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)
          (CLIENT_ID=123ab4cd-1a2b-1234-a12b-aa00123b2cd3)
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
TOKEN_AUTH=AZURE_INTERACTIVE
AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3
CLIENT_ID=123ab4cd-1a2b-1234-a12b-aa00123b2cd3

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=AZURE_INTERACTIVE&AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3&CLIENT_ID=123ab4cd-1a2b-1234-a12b-aa00123b2cd3

In these examples, the TENANT_ID and REDIRECT_URI parameters are not specified. TENANT_ID is required when using the thick clients (OCI and Instant Client). This parameter is optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get this value from the Azure SDK configuration.

Related Topics

IGNORE_ANO_ENCRYPTION_FOR_TCPS

The IGNORE_ANO_ENCRYPTION_FOR_TCPS parameter specifies if the SQLNET.ENCRYPTION_CLIENT parameter should be ignored for this specific TNS alias.

Purpose

To specify if the SQLNET.ENCRYPTION_CLIENT parameter should be ignored for this specific TNS alias.

Usage Notes

If your requirements are that SQLNET.ENCRYPTION_SERVER be set to required, then you can set the IGNORE_ANO_ENCRYPTION_FOR_TCPS parameter in both SQLNET.ENCRYPTION_CLIENT and SQLNET.ENCRYPTION_SERVER to TRUE. This forces the client to ignore the value that is set for the SQLNET.ENCRYPTION_CLIENT parameter for all outgoing TCPS connections.

Default

FALSE

Example 6-12 Example

test_ssl=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=)(PORT=1750))
       (CONNECT_DATA=(SID=^ORACLE_SID^))
       (SECURITY=(IGNORE_ANO_ENCRYPTION_FOR_TCPS=TRUE))
     )

KERBEROS5_CC_NAME

Use the tnsnames.ora parameter KERBEROS5_CC_NAME to specify the complete path name to the Kerberos credentials cache (CC) file.

Purpose

To specify the complete path name to the Kerberos CC file.

Usage Notes

Values and Examples

You can use the following formats to specify a value for KERBEROS5_CC_NAME:

Default

The default value is operating system-dependent, as follows:

Related Topics

KERBEROS5_DELEGATION_MODE

Use the KERBEROS5_DELEGATION_MODE parameter to control whether the Kerberos Ticket Granting Ticket (TGT) is forwarded when authenticating to a remote server for enhanced security.

Purpose

To allow the client to control the forwarding of the TGT to the database server for enhanced security.

Usage Notes

Use this parameter in the SECURITY section of the tnsnames.ora file, or set it in the sqlnet.ora file.

Set this parameter to UNCONSTRAINED to enable forwarding of the client’s TGT. Once a service is granted unconstrained delegation privileges, it can use the user’s credentials to access any service on the network on behalf of the user.

Note:

If the client is on Windows and using MSLSA, Credential Guard blocks TGT forwarding by default. Setting the parameter to UNCONSTRAINED will not change this behavior, and the TGT will not be forwarded.

Set the parameter to CONSTRAINED to disable TGT forwarding to the database server and reduce the risks associated with delegation by limiting the services that can be accessed using a user’s credentials.

Note:

Values

Default

UNCONSTRAINED

Examples

Related Topics

KERBEROS5_PRINCIPAL

Use the KERBEROS5_PRINCIPAL parameter to set the Kerberos principal name associated with the Kerberos credentials cache (CC) file.

Purpose

When you configure Kerberos authentication for an Oracle Database client, you can specify multiple Kerberos principals with a single Oracle Database client.

This is an optional parameter. When specified, it is used to verify if the principal name in the credential cache (specified using KERBEROS5_CC_NAME) matches the parameter value.

Usage Notes

Use this parameter in the SECURITY section of the tnsnames.ora file, or set it in the sqlnet.ora file. Alternatively, you can set KERBEROS5_PRINCIPAL in the connect string along with the KERBEROS5_CC_NAME parameter to connect as a different Kerberos principal.

The parameter value specified in the connect string takes precedence over the value specified in the sqlnet.ora or tnsnames.ora file.

Each Kerberos principal must have a valid credential cache. Oracle Database checks KERBEROS5_PRINCIPAL against the value that is retrieved from the credential cache. If the two values do not match, then the user is not authenticated.

Examples

Note: The connection fails if the principal in the /tmp/krbuser1/krb.cc file does not contain the krbprinc1@example.com value.

Related Topics

OCI_COMPARTMENT

Use the OCI_COMPARTMENT parameter to specify Oracle Cloud Identifier (OCID) of the compartment that holds database instances for client connections.

Purpose

To define the scope of your database token request. This value instructs the database client to initiate a token request to databases within the specified compartment only. You use this parameter while configuring token-based authentication for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users on OCI Database as a Service (DBaaS).

Usage Notes

The OCI_COMPARTMENT parameter is optional if you have not specified the OCI_DATABASE parameter. If you choose to set OCI_DATABASE, then you must also set OCI_COMPARTMENT to limit your token request to the specified database within that compartment.

If you do not set both the OCI_COMPARTMENT and OCI_DATABASE parameters, then the entire tenancy is the scope of your token request.

You can use this parameter along with the PASSWORD_AUTH and TOKEN_AUTH authentication settings:

Use this parameter under the SECURITY section of the tnsnames.ora file, sqlnet.ora file, Easy Connect syntax, or directly as part of the command-line connect string. The parameter value specified in the connect string takes precedence over the other specified values.

Default

None

Value

OCID for the IAM compartment to allow access for the database token. You can get the OCID value for your compartment from the Compartments information page in the OCI console.

The compartment OCID uses this syntax:

OCI_COMPARTMENT=compartment_OCID

For details on the syntax options, see Oracle Cloud IDs (OCIDs).

Examples

In the tnsnames.ora file:

net_service_name=
  (DESCRIPTION=
     (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522))
     (SECURITY=
        (TLS_SERVER_DN_MATCH=TRUE)
        (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
        (PASSWORD_AUTH=OCI_TOKEN)
        (OCI_IAM_URL=https://auth.us-region-
1.example.com/v1/actions/generateScopedAccessBearerToken)
        (OCI_TENANCY=ocid1.tenancy..12345)
        (OCI_COMPARTMENT=ocid1.compartment..12345)
        (OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345))
     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
  )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
PASSWORD_AUTH=OCI_TOKEN
OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken
OCI_TENANCY=ocid1.tenancy..12345
OCI_COMPARTMENT=ocid1.compartment..12345
OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345

In the Easy Connect syntax:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=OCI_INTERACTIVE&OCI_COMPARTMENT=ocid1.compartment..12345&OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345

Related Topics

OCI_CONFIG_FILE

Use the OCI_CONFIG_FILE parameter to specify the directory location where the Oracle Cloud Infrastructure (OCI) configuration file is stored.

Purpose

To specify the directory location of the OCI configuration file. This file stores the client connection information for OCI Identity and Access Management (IAM) users as part of their profile. The SDK, CLI, and other OCI tools use this file to access the IAM user credentials during IAM token-based authentication.

Usage Notes

This is an optional parameter. If you do not set this parameter, then the database client gets the user’s profile from the default configuration file located at C:/user-profile/.oci/config. You can use this parameter to override the default configuration file location. In this case, the database client searches for the profile in the location specified by OCI_CONFIG_FILE.

You can use this parameter along with the TOKEN_AUTH parameter for the OCI_API_KEY and OCI_INTERACTIVE authentication flows:

For JDBC-thin clients, you can specify this parameter in the Easy Connect syntax or tnsnames.ora connect string. For ODP.NET Core classes and ODP.NET Managed Driver classes, you can specify this parameter in the sqlnet.ora file, Easy Connect syntax, or tnsnames.ora connect string. The parameter value specified in the connect string takes precedence.

Default

None

Value

Full path (including a file name) to the OCI configuration file

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=OCI_INTERACTIVE)
          (OCI_CONFIG_FILE=/home/dbuser1/config))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
TOKEN_AUTH=OCI_INTERACTIVE
OCI_CONFIG_FILE=/home/dbuser1/config

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=OCI_INTERACTIVE&OCI_CONFIG_FILE=/home/dbuser1/config

In these examples, the optional OCI_PROFILE parameter is not specified. Thus, the client automatically gets the DEFAULT profile from the specified configuration file directory.

Related Topics

OCI_DATABASE

Use the OCI_DATABASE parameter to specify Oracle Cloud Identifier (OCID) of the database that you want to access for the client connection.

Purpose

To define the scope of your database token request. The database OCID value instructs the database client to initiate a token request to the specified database within your compartment. You use this parameter while configuring token-based authentication for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users on OCI Database as a Service (DBaaS).

Usage Notes

This is an optional parameter. You can set this parameter to limit the access to only a particular database. If you set OCI_DATABASE, then you must also provide specific compartment identifier using the OCI_COMPARTMENT parameter.

You can use this parameter along with the PASSWORD_AUTH and TOKEN_AUTH authentication settings:

Specify this parameter under the SECURITY section of the tnsnames.ora file, sqlnet.ora file, Easy Connect syntax, or directly as part of the command-line connect string. The parameter value specified in the connect string takes precedence.

Default

None

Value

OCID of the database that you want to access for the client connection. You can get the OCID value for your database from the Database details page in the OCI console.

The database OCID uses this syntax:

OCI_DATABASE=database_OCID

For details on the syntax options, see Oracle Cloud IDs (OCIDs).

Examples

In the tnsnames.ora file:

net_service_name=
  (DESCRIPTION=
     (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522))
     (SECURITY=
        (TLS_SERVER_DN_MATCH=TRUE)
        (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
        (PASSWORD_AUTH=OCI_TOKEN)
        (OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken)
        (OCI_TENANCY=ocid1.tenancy..12345)
        (OCI_COMPARTMENT=ocid1.compartment..12345)
        (OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345))
     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
  )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
PASSWORD_AUTH=OCI_TOKEN
OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken
OCI_TENANCY=ocid1.tenancy..12345
OCI_COMPARTMENT=ocid1.compartment..12345
OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345

In the Easy Connect syntax:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=OCI_INTERACTIVE&OCI_COMPARTMENT=ocid1.compartment..12345&OCI_DATABASE=ocid1.autonomousdatabase.oc1.12345

Related Topics

OCI_IAM_URL

Use the OCI_IAM_URL parameter to specify an endpoint URL that the database client must connect with to get the database token for authenticating Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users on OCI Database as a Service (DBaaS).

Purpose

To specify the IAM URL for your REST API requests. The database client connects to this URL to retrieve the database token from IAM.

Usage Notes

You set the OCI_IAM_URL parameter along with the PASSWORD_AUTH and OCI_TENANCY parameters while configuring IAM token-based authentication (using the IAM user name and IAM database password to retrieve the database token). These parameters are mandatory.

With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal.

You can also set the optional OCI_COMPARTMENT and OCI_DATABASE parameters to specify the scope of your token request.

Use this parameter under the SECURITY section of the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter value specified in the connect string takes precedence over the other specified values.

Default

None

Value

OCI IAM endpoint URL that the database client must connect with to get the database token. This URL is specific to your region and uses this syntax:

<authentication_regional_endpoint>/v1/actions/generateScopedAccessBearerToken

You can derive this value by replacing <authentication_regional_endpoint> with the API endpoint URL for your region. To obtain the appropriate API endpoint URL, see Identity and Access Management Data Plane API.

For example, if you want to use the URL as https://auth.us-region-1.example.com, then your OCI_IAM_URL value is:

https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken

Examples

In the tnsnames.ora file:

net_service_name=
  (DESCRIPTION=
     (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522))
     (SECURITY=
        (TLS_SERVER_DN_MATCH=TRUE)
        (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
        (PASSWORD_AUTH=OCI_TOKEN)
        (OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken)
        (OCI_TENANCY=ocid1.tenancy..12345))
     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
  )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
PASSWORD_AUTH=OCI_TOKEN
OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken
OCI_TENANCY=ocid1.tenancy..12345

In these examples, the optional OCI_COMPARTMENT and OCI_DATABASE parameters are not specified and thus the entire tenancy is set as the scope of the token request.

Related Topics

OCI_PROFILE

Use the OCI_PROFILE parameter to specify the profile name for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users.

Purpose

To specify the profile name for IAM users. This profile is the client connection information stored in the OCI configuration file, and is used during IAM token-based authentication.

Usage Notes

Values

Default

DEFAULT

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=OCI_INTERACTIVE)
          (OCI_CONFIG_FILE=/home/dbuser1/config))
          (OCI_PROFILE=ADMIN_USER))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
TOKEN_AUTH=OCI_INTERACTIVE
OCI_CONFIG_FILE=/home/dbuser1/config
OCI_PROFILE=ADMIN_USER

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=OCI_INTERACTIVE&OCI_CONFIG_FILE=/home/dbuser1/config&OCI_PROFILE=ADMIN_USER

Related Topics

OCI_TENANCY

Use the OCI_TENANCY parameter to specify Oracle Cloud Identifier (OCID) of the user’s tenancy.

Purpose

To specify OCID of the user’s tenancy (root compartment).

Usage Notes

You set this parameter along with the mandatory PASSWORD_AUTH and OCI_IAM_URL parameters while configuring token-based authentication for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users on OCI Database as a Service (DBaaS).

With this configuration, the database client can only request an IAM database token using the IAM user name and IAM database password. The client cannot request an IAM database token for an API-key, delegation token, security token, resource principal, service principal, or instance principal.

You can also set the optional OCI_COMPARTMENT and OCI_DATABASE parameters to specify the scope of your token request. If you do not set the OCI_COMPARTMENT and OCI_DATABASE parameter values, then the entire tenancy is the scope of your token request.

Use this parameter under the SECURITY section of the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter value specified in the connect string takes precedence over the other specified values.

Default

None

Value

OCID of the user’s tenancy. You can get the OCID value for your tenancy from the Tenancy information page in the OCI console.

The tenancy OCID uses this syntax:

OCI_TENANCY=tenancy_OCID

For details on the syntax options, see Oracle Cloud IDs (OCIDs).

Examples

In the tnsnames.ora file:

net_service_name=
  (DESCRIPTION=
     (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522))
     (SECURITY=
        (TLS_SERVER_DN_MATCH=TRUE)
        (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
        (PASSWORD_AUTH=OCI_TOKEN)
        (OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken)
        (OCI_TENANCY=ocid1.tenancy..12345))
     (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
  )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
PASSWORD_AUTH=OCI_TOKEN
OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken
OCI_TENANCY=ocid1.tenancy..12345

In these examples, the optional OCI_COMPARTMENT and OCI_DATABASE parameters are not specified and thus the entire tenancy is set as the scope of the token request.

Related Topics

PASSWORD_AUTH

Use the PASSWORD_AUTH parameter to configure an authentication method for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) users on OCI Database as a Service (DBaaS). With this setting, client connections use the IAM user name and IAM database password for logging in users to the database.

Purpose

To configure either IAM database password verifier authentication or IAM token-based authentication, using the IAM user name and IAM database password for the access.

For password verifier authentication, the database server retrieves an IAM database password verifier from IAM. For token-based authentication, the database client requests a database token (db-token) from IAM.

Usage Notes

Note:

You can also use other IAM user credentials (such as API-key, security token, resource principal, service principal, instance principal, or delegation token) to get the db-token. This db-token is a proof-of-possession (PoP) token. In this case, you use a different parameter setting (TOKEN_AUTH=OCI_TOKEN).

Unlike the IAM database password that can only be used by the database client to retrieve the token, these credentials require an application or tool to retrieve the token. See TOKEN_AUTH.

Default

PASSWORD_VERIFIER

Values and Examples

Value Example

For IAM database password verifier authentication:

PASSWORD_AUTH=PASSWORD_VERIFIER

Note: Use of IAM user name and IAM database password with the IAM database password verifier is the default configuration, and you do not need to set any additional parameters for the client.

However, if PASSWORD_AUTH is set to OCI_TOKEN in the client-side sqlnet.ora file, then the client tries to connect with OCI IAM to retrieve a database token using the IAM user name and IAM database password. In this case, you can override this setting for a particular connection using PASSWORD_AUTH=PASSWORD_VERIFIER.

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (PASSWORD_AUTH=PASSWORD_VERIFIER)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

PASSWORD_AUTH=PASSWORD_VERIFIER

For IAM token-based authentication with the IAM user name and IAM database password:

PASSWORD_AUTH=OCI_TOKEN

Note: You must configure the TCPS protocol (PROTOCOL=tcps) and set the TLS_SERVER_DN_MATCH parameter to TRUE for token-based authentication.

In the tnsnames.ora file:

net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (PASSWORD_AUTH=OCI_TOKEN) (OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken) (OCI_TENANCY=ocid1.tenancy..12345)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))  )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE PASSWORD_AUTH=OCI_TOKEN OCI_IAM_URL=https://auth.us-region-1.example.com/v1/actions/generateScopedAccessBearerToken OCI_TENANCY=ocid1.tenancy..12345

In these examples, the optional OCI_COMPARTMENT and OCI_DATABASE parameters are not specified and thus the entire tenancy is set as the scope of the token request.

Related Topics

REDIRECT_URI

Use the REDIRECT_URI parameter to specify the redirect URI, registered for your Microsoft Entra ID client application.

Purpose

To specify the redirect URI (or reply URL), registered for your Entra ID client application. This is used for the AZURE_INTERACTIVE token-based authentication flow. This URL obtains the authorization code from the Entra authentication endpoint and determines which port to use to receive the authorization code.

Usage Notes

This is an optional parameter. If you do not specify this parameter, then it uses the default value of http://localhost, which is the most common redirect URL.

Specify this parameter only if necessary for your use case. The authorization server redirects the user to your specified address only if you have registered the redirect URI for the client application in the Azure portal, as shown in Oracle AI Database Security Guide.

You can specify this parameter along with the TOKEN_AUTH=AZURE_INTERACTIVE setting in the connect string, Easy Connect syntax, or tnsnames.ora file. The parameter value specified in the connect string takes precedence.

Default

The default redirect URI for all clients is:

http://localhost

Value

You can get a redirect URI value by logging in to the Azure portal. All URI values are listed as Redirect URIs on the App registrations - Authentication page of your Entra ID service.

Note that this is the value that you specified while registering your database client application with Entra ID.

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=AZURE_INTERACTIVE)
          (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)
          (REDIRECT_URI=http://localhost:1575))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=AZURE_INTERACTIVE&AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3&REDIRECT_URI=http://localhost:1575

In these examples, the CLIENT_ID and TENANT_ID parameters are not specified. CLIENT_ID and TENANT_ID are required parameters when using the thick clients (OCI and Instant Client). These parameters are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration.

Related Topics

SECURITY

Use the SECURITY parameter to change the security properties of a connection.

Purpose

To change the security properties of a connection.

Usage Notes

Put this parameter under the DESCRIPTION parameter. SECURITY permits additional parameters as listed in Security Section.

Example

net_service_name=
 (DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com))
    (SECURITY=
      (SSL_SERVER_CERT_DN="cn=sales,cn=OracleContext,dc=us,dc=acme,dc=com")))

SEPS_WALLET_LOCATION

Use the SEPS_WALLET_LOCATION parameter to specify the wallet location for secure external password store (SEPS) and to enable the use of specified wallet for authentication.

Purpose

To specify the directory path of the client-side oracle wallet and to configure the client to use secure external password store for authentication purposes. Setting this parameter causes all CONNECT /@db_connect_string statements to use the information in the SEPS wallet at the specified location to authenticate to databases.

Usage Notes

You can set SEPS_WALLET_LOCATION in the sqlnet.ora file to specify a common wallet location for all connections. You can also set it in the connect string or tnsnames.ora file to specify a different wallet location for a particular connection.

Use of SEPS_WALLET_LOCATION in the connect string or tnsnames.ora overrides the sqlnet.ora SEPS_WALLET_LOCATION setting for the specific tnsnames.ora service.

To disable authentication using SEPS, you must unset SEPS_WALLET_LOCATION parameter. You must also unset SQLNET.WALLET_OVERRIDE or set it to FALSE in sqlnet.ora file.

Note: If the SEPS_WALLET_LOCATION parameter is set, the SQLNET.WALLET_OVERRIDE parameter is ignored.

Default

None

Examples

If you created the wallet in $ORACLE_HOME/network/admin and your Oracle home is set to/private/ora_db, then you need to enter the following into your client sqlnet.ora file.

SEPS_WALLET_LOCATION=/private/ora_db/network/admin

You can also set this parameter under the SECURITY section of the tnsnames.ora or directly as part of the command-line connect string. The parameter value specified in the connect string take precedence over the other specified values.

net_service_name=
  (DESCRIPTION=
    (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
    (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
    (SECURITY=(SEPS_WALLET_LOCATION=/private/ora_db/network/admin)))
  )

Related Topics

TLS_CERTIFICATE_ALIAS

Use the sqlnet.ora or tnsnames.ora parameter TLS_CERTIFICATE_ALIAS to specify the certificate alias to use in Transport Layer Security (TLS) connections.

Purpose

To specify the alias that you provided when storing the client or server certificate in an Oracle Database wallet.

When encrypting TLS connections, both the database client and database server need to provide a signed certificate. You can store this certificate in an Oracle Database wallet or Microsoft Certificate Store (MCS). If there is more than one certificate that can be used, the user or application settings can specify the particular certificate to connect with. This choice can be made manually by the user via graphical user interface (GUI) or automatically by the application using a thumbprint or alias name. A thumbprint or alias name can uniquely identify the certificate.

This parameter instructs the client or server to automatically select a particular certificate using the specified alias name. Thus, the user does not need to manually select the correct client certificate from the list available in a wallet.

Usage Notes

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

Use this parameter in the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter values specified in the connect string take precedence over the other specified values.

orapki helps you manage certificates and wallets for Oracle Database. To get the alias name value, run the following command:

orapki wallet display -wallet <wallet directory> -pwd <wallet password> -complete

Value

Certificate alias name

Default

None

Examples

Related Topics

TLS_CERTIFICATE_THUMBPRINT

Use the sqlnet.ora or tnsnames.ora parameter TLS_CERTIFICATE_THUMBPRINT to specify the certificate thumbprint to use in Transport Layer Security (TLS) connections.

Purpose

To specify the thumbprint signature for an X509 certificate. These thumbprints are automatically generated for certificates.

When encrypting TLS connections, both the database client and database server need to provide a signed certificate. You can store this certificate in an Oracle Database wallet or Microsoft Certificate Store (MCS). If there is more than one certificate that can be used, the user or application settings can specify the particular certificate to connect with. This choice can be made manually by the user via graphical user interface (GUI) or automatically by the application using a thumbprint or alias name. A thumbprint or alias name can uniquely identify the certificate.

This parameter instructs the client or server to automatically select a particular certificate using the specified thumbprint. Thus, the user does not need to manually select the correct certificate from the list available in a certificate store.

Usage Notes

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

Use this parameter in the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter values specified in the connect string take precedence over the other specified values.

You can specify both the SHA-1 and SHA-256 thumbprint information for the client certificate.

orapki helps you manage certificates and wallets for Oracle Database. To get the thumbprint value, run the following command:

orapki wallet display -wallet <wallet directory> -pwd <wallet password> -complete

Value

SHA-1 or SHA-256 thumbprint of the client certificate, in the <Algorithm>:<Hash> format

For example:

SHA1:1B:11:01:5A:B1:2C:20:B2:12:34:3E:04:7B:83:47:DE:70:2E:4E:11
SHA256:B3:8A:5B:1A:03:63:83:92:2B:5D:E1:53:61:EE:03:94:0A:56:B4:56:41:7E:41:24:41:9B:88:EB:C6:1E:11:23

or

SHA1:1B11015AB12C20B212343E047B8347DE702E4E11
SHA256:B38A5B1A036383922B5DE15361EE03940A56B456417E4124419B88EBC61E1123

Default

None

Examples

Related Topics

TLS_CLIENT_AUTHENTICATION

Use the TLS_CLIENT_AUTHENTICATION parameter to specify whether the database client is authenticated using Transport Layer Security (TLS).

Purpose

To enable client authentication in a TLS connection. The connection can be one-way or two-way (mutual TLS or mTLS).

Usage Notes

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

When set to TRUE, a two-way TLS connection is initiated. Both the client and server (including the listener) authenticate each other. For example, if you set this parameter to TRUE in the server configuration (server-side sqlnet.ora), then the server attempts to authenticate the client. If you set it to TRUE in the listener configuration (listener.ora), then the listener attempts to authenticate the client.

When set to FALSE, only the client authenticates the server and listener as a one-way TLS connection. For example, if you set this parameter to FALSE in the server configuration, then the server does not authenticate the client. If you set it to FALSE in the listener configuration, then the listener does not authenticate the client.

When set to OPTIONAL, the server behaves as follows:

Ensure that this parameter setting is consistent for the server or listener (on one side) and the client (on the other). Otherwise, the connection may fail. For example, if you enable client authentication in the server or listener configuration, then you must enable it in the client configuration.

Default

TRUE

Values

Example

TLS_CLIENT_AUTHENTICATION=FALSE

Related Topics

TLS_DISABLE_WEAK_EC_CURVES

Use the TLS_DISABLE_WEAK_EC_CURVES parameter to disable the use of weak Elliptic Curve Cryptography (ECC) curves.

Purpose

To disable the use of weak ECC curves with key length less than 256 bits. You can set this parameter in the database server (sqlnet.ora), client (sqlnet.ora or tnsnames.ora connect string), or the listener (listener.ora).

Usage Notes

Note: TLS_DISABLE_WEAK_EC_CURVES is deprecated in favor of TLS_KEY_EXCHANGE_GROUPS parameter starting with Oracle AI Database 26ai. Elliptic Curve Cryptography (ECC) features in Oracle Net Services, such as those used for secure external password stores, have some curves disabled by default. Oracle and other major vendors disable weak elliptic curves by default to protect systems from known cryptographic vulnerabilities, and to enforce modern security standards. These older, weaker curves can be susceptible to a variety of attacks and may present security risks if used. Because Oracle no longer has ECC curves with key length less than 256 bit enabled, this parameter no longer serves a purpose, and will be removed in a future release. Oracle strongly recommends that you review your configurations to ensure that you follow security best practices.

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

By default, this parameter is set to FALSE to enable the use of all ECC curves. If you want to enable the use of only Oracle approved curves with ECC curve key size of 256 bits or higher, then set this parameter to TRUE.

When set to TRUE, you can use only the following ECC curves:

Values

Default

FALSE

Examples

Related Topics

TLS_KEY_EXCHANGE_GROUPS

Use the TLS_KEY_EXCHANGE_GROUPS parameter to enable or disable post-quantum cryptographic (PQC) ML-KEM algorithms and classical Elliptic Curve Diffie-Hellman Ephemeral (ECDHE) groups for TLS connections.

Purpose

To enable selection of classical or quantum-safe key exchange algorithms for TLS connections. You can set this parameter in the database server (sqlnet.ora), client (sqlnet.ora or tnsnames.ora connect string), or the listener (listener.ora).

Usage Notes

This parameter takes a combination of following values as a comma-separated list:

Values

A comma-separated list of one or more of the values below:

The order in which you specify the values in the TLS_KEY_EXCHANGE_GROUPS parameter is honored. If you set TLS_KEY_EXCHANGE_GROUPS to ml-kem,hybrid,ec, then ML-KEM groups are given the highest preference, followed by Hybrid and ECDHE groups.

The following table shows the results of TLS negotiations based on the TLS_KEY_EXCHANGE_GROUPS values from the DB26ai client and the DB26ai server.

Server-Side Value Client-Side Value Result
Not set Not set Hybrid
ec,ml-kem ec,ml-kem ECDHE
ec,ml-kem ml-kem ML-KEM
ml-kem ec,ml-kem ML-KEM
ml-kem ml-kem ML-KEM
ec ec ECDHE
ml-kem,hybrid ml-kem,hybrid ML-KEM
ml-kem,hybrid Not set Hybrid
Not set ml-kem,ec ML-KEM

Default

hybrid, ec, weak, and ml-kem are enabled by default, in that order.

If you do not explicitly set the TLS_KEY_EXCHANGE_GROUPS parameter, then by default, TLS connections are negotiated with Hybrid TLS groups (if both the server and client support Hybrid PQC). However, if either the server or client does not support Hybrid PQC, the TLS connections will fallback to ECDHE groups transparently.

Examples

Related Topics

TLS_SERVER_CERT_DN

Use the TLS_SERVER_CERT_DN parameter to specify the distinguished name (DN) of the database server.

Purpose

To specify the DN of the database server for DN matching. DN matching adds another client-side check on the listener and server certificates to ensure that the certificates are the correct ones that the client expects.

Usage Notes

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

Value

Database server DN

Example

finance=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL = tcps) (HOST = finance)
     (PORT = 1575)))
   (CONNECT_DATA=
     (SERVICE_NAME=finance.us.example.com))
   (SECURITY=
     (TLS_SERVER_CERT_DN="cn=finance,cn=OracleContext,c=us,o=example")))

Related Topics

TLS_SERVER_DN_MATCH

Use the TLS_SERVER_DN_MATCH parameter to enforce server-side certificate validation through distinguished name (DN) matching.

Purpose

To enforce server-side certificate validation through DN matching.

The purpose of adding this DN matching parameter for the client is to further improve security on a Transport Layer Security (TLS) connection. A TLS connection relies on the client to verify if the database server certificate is valid and signed by a trusted root certificate. The listener and server certificate DN matching adds another client-side check on the listener and server certificates to ensure that the certificates are the correct ones that the client expects.

Usage Notes

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

Default

NO

Values

Note:

Oracle recommends setting TLS_SERVER_DN_MATCH=YES unless you have a compelling, well-understood business case that requires disabling it.

Below are the potential risks when TLS_SERVER_DN_MATCH=NO:

If host name matching must be disabled, ensure that robust alternative controls are in place:

Example

TLS_SERVER_DN_MATCH=YES

Related Topics

TLS_VERSION

Use the TLS_VERSION parameter to define valid Transport Layer Security (TLS) versions to be used for connections.

Purpose

To define the version of TLS that must run on the systems with which the database server communicates. By default, the database server and client negotiate the strongest security protocol. Oracle does not recommend modifying this parameter, unless your security requirements mandate the usage of certain protocol versions.

Usage Notes

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

Values

undetermined | TLSv1.2 | TLSv1.3

Default

undetermined

Syntax and Examples

Related Topics

TENANT_ID

Use the TENANT_ID parameter to specify the ID of your Microsoft Entra ID tenant.

Purpose

To specify the ID of the Entra ID tenant in which your Entra ID application is registered. This is the Azure tenancy ID that uniquely identifies your database instance in Entra ID.

Usage Notes

Default

None

Value

You can get the tenant ID value by logging in to the Azure portal. This is listed as Tenant ID on the Tenant Properties page.

Examples

In the tnsnames.ora file:

net_service_name=
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521))
       (SECURITY=
          (TLS_SERVER_DN_MATCH=TRUE)
          (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext")
          (TOKEN_AUTH=AZURE_INTERACTIVE)
          (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)
          (TENANT_ID=1a123ab1-a1b1-1a2b-a1b2-a12bcdab0123)
          (REDIRECT_URI=http://localhost:1575))
       (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com))
     )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE
TOKEN_AUTH=AZURE_INTERACTIVE
AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3
TENANT_ID=1a123ab1-a1b1-1a2b-a1b2-a12bcdab0123
REDIRECT_URI=http://localhost:1575

In the Easy Connect string:

tcps:sales-svr:1521/sales.us.example.com?TOKEN_AUTH=AZURE_INTERACTIVE&AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3&TENANT_ID=1a123ab1-a1b1-1a2b-a1b2-a12bcdab0123&REDIRECT_URI=http://localhost:1575

In these examples, the CLIENT_ID parameter is not specified. CLIENT_ID is required when using the thick clients (OCI and Instant Client). This parameter is optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get this value from the Azure SDK configuration.

Related Topics

TOKEN_AUTH

Use the TOKEN_AUTH parameter to configure token-based authentication for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) or Microsoft Azure users of Microsoft Entra ID (previously called Microsoft Azure Active Directory).

Purpose

Token-based access enforces strong authentication, which enables a more secure access to the database. IAM users can connect to OCI Database as a Service (DBaaS) databases, and Azure users can connect to Oracle Databases (cloud or on-premises).

With this setting, when a / (slash) login is used, the Oracle Database client either looks for a token file or directly gets the token using single-sign on (SSO) credentials.

Use this parameter under the SECURITY section of the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter value specified in the connect string takes precedence over the other specified values.

Usage Notes for IAM

Note:

You can also use another IAM credential, IAM database password, to request the db-token from IAM. This db-token is a bearer token and does not come with a private key. You can configure the database client to request this token using your IAM user name and IAM database password. An application cannot pass this type of db-token to the client. In this case, you use a different parameter setting (PASSWORD_AUTH=OCI_TOKEN).

Unlike the API-key, security token, resource principal, service principal, instance principal, and delegation token that require an application or tool to get a token, the IAM database password can only be used by the database client to retrieve the token. See PASSWORD_AUTH.

Default Setting for IAM

None

Table 1 Values and Examples for IAM

Value Example
TOKEN_AUTH=OCI_TOKEN

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_TOKEN)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_TOKEN

In these examples, the optional TOKEN_LOCATION parameter is not specified. Thus, the client automatically gets the db-token and private key from the default token location.

TOKEN_AUTH=OCI_INTERACTIVE

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_INTERACTIVE)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_INTERACTIVE

In these examples, the optional OCI_CONFIG and OCI_PROFILE parameters are not specified. Thus, the client automatically gets the DEFAULT profile from the default configuration file directory.

TOKEN_AUTH=OCI_API_KEY

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_API_KEY)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_API_KEY

In these examples, the optional OCI_CONFIG and OCI_PROFILE parameters are not specified. Thus, the client automatically gets the API-key value from the DEFAULT profile stored in the default configuration file directory.

TOKEN_AUTH=OCI_INSTANCE_PRINCIPAL

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_INSTANCE_PRINCIPAL)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_INSTANCE_PRINCIPAL
TOKEN_AUTH=OCI_DELEGATION_TOKEN

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_DELEGATION_TOKEN)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_DELEGATION_TOKEN
TOKEN_AUTH=OCI_RESOURCE_PRINCIPAL

In the tnsnames.ora file:

net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_RESOURCE_PRINCIPAL)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_RESOURCE_PRINCIPAL

Usage Notes for Entra ID

Default Setting for Entra ID

None

Table 2 Values and Examples for Entra ID

Value Example
TOKEN_AUTH=OAUTH

  • If the token file is named token, TOKEN_AUTH=OAUTH, and TOKEN_LOCATION="token_file_directory":

    In the tnsnames.ora file:
    net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OAUTH) (TOKEN_LOCATION="/home/dbuser1/access-token")) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

In the sqlnet.ora file:

TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OAUTH  TOKEN_LOCATION="/home/dbuser1/access-token"

In these examples, the token file name is token. Thus, only the directory path (/home/dbuser1/access-token) is specified. The client automatically looks for the token file in the specified path and gets the access token.

  • If the token file name is different from token, TOKEN_AUTH=OAUTH, and TOKEN_LOCATION="token_file_directory/token_filename":

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OAUTH) (TOKEN_LOCATION="/home/dbuser1/access-token/mytoken")) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OAUTH  TOKEN_LOCATION="/home/dbuser1/access-token/mytoken"

    In these examples, the token file name is mytoken. Thus, both the file name and directory path (/home/dbuser1/access-token) are specified. The client gets the access token from the mytoken file in the specified path.

    • TOKEN_AUTH=AZURE_INTERACTIVE

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=AZURE_INTERACTIVE) (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3) (REDIRECT_URI=http://localhost:1575)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=AZURE_INTERACTIVE AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3 REDIRECT_URI=http://localhost:1575

    In these examples, the CLIENT_ID and TENANT_ID parameters are not specified. These parameters are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration. The thick clients (OCI and Instant Client) must specify these parameters.

    TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL) (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=AZURE_SERVICE_PRINCIPAL AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3

    In these examples, the CLIENT_ID, TENANT_ID, and CLIENT_CERTIFICATE parameters are not specified. CLIENT_ID and TENANT_ID are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration. The thick clients (OCI and Instant Client) must specify these parameters.

    TOKEN_AUTH=AZURE_MANAGED_IDENTITY

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=AZURE_MANAGED_IDENTITY) (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=AZURE_MANAGED_IDENTITY AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3

    In these examples, the CLIENT_ID parameter is not specified. This parameter is optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get this value from the Azure SDK configuration. The thick clients (OCI and Instant Client) must specify this parameter.

    TOKEN_AUTH=AZURE_DEVICE_CODE

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=AZURE_DEVICE_CODE) (AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3)) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=AZURE_DEVICE_CODE AZURE_DB_APP_ID_URI=https://application.example.com/123ab4cd-1a2b-1234-a12b-aa00123b2cd3

    In these examples, the CLIENT_ID and TENANT_ID parameters are not specified. These parameters are optional for the JDBC-thin and ODP.NET core and managed database clients, which can automatically get these values from the Azure SDK configuration. The thick clients (OCI and Instant Client) must specify these parameters.

    Related Topics

    TOKEN_LOCATION

    Use the TOKEN_LOCATION parameter to specify the directory location where token file is stored for token-based authentication.

    Purpose

    To specify the token file directory location. You use this parameter while configuring token-based authentication for Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) or Microsoft Azure users of Microsoft Entra ID. The database client gets the token from this location and sends it to the database server. For Entra ID, you can also specify the token file name along with the directory location.

    Use this parameter along with the TOKEN_AUTH parameter in the tnsnames.ora file, sqlnet.ora file, or directly as part of the command-line connect string. The parameter values specified in the connect string take precedence over the other specified values.

    Usage Notes for IAM

    The TOKEN_LOCATION parameter is optional for IAM token-based authentication. You can use this parameter along with the TOKEN_AUTH parameter to override the default directory where the db-token and private key are stored. This location is used by the database client to retrieve the db-token and private key.

    When an IAM user initiates a connection using /@connect_identifier (and TOKEN_AUTH is set to OCI_TOKEN), the database client retrieves the db-token and private key from either the default directory or the location specified by TOKEN_LOCATION. The client then signs the db-token using the private key and sends the db-token to the database server.

    Default Setting for IAM

    Values and Examples for IAM

    Value Example
    TOKEN_LOCATION="token_file_directory"

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION = (ADDRESS=(PROTOCOL=tcps)(HOST=sales-svr)(PORT=1521)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OCI_TOKEN) (TOKEN_LOCATION="/home/oracle/.oci/db-token")) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OCI_TOKEN TOKEN_LOCATION="/home/oracle/.oci/db-token"

    Usage Notes for Entra ID

    The TOKEN_LOCATION parameter is mandatory for Azure token-based authentication. You must use this parameter along with the TOKEN_AUTH parameter to specify the directory location where the Entra ID OAuth2 access token is stored. This location is used by the database client to get the access token.

    If your token file is named token, then specify only the directory path. If the token file name is different from token, then you must use the file name along with the directory path.

    When an Azure user initiates a connection using /@connect_identifier, the database client retrieves the access token from the location specified by TOKEN_LOCATION and sends the token to the database server.

    Default Setting for Entra ID

    None

    Values and Examples for Entra ID

    Value Example

    If the token file is named token:

    TOKEN_LOCATION="token_file_directory"

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522)) (SECURITY= (TLS_SERVER_DN_MATCH=TRUE) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OAUTH)(TOKEN_LOCATION="/home/dbuser1/access-token")) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OAUTH  TOKEN_LOCATION="/home/dbuser1/access-token"

    In these examples, the token file name is token. Thus, only the directory path (/home/dbuser1/access-token) is specified. The client automatically looks for the token file in the specified path and gets the access token.

    If the token file name is different from token:

    TOKEN_LOCATION="token_file_directory/token_filename"

    In the tnsnames.ora file:

    net_service_name= (DESCRIPTION= (ADDRESS=(PROTOCOL=tcps)(HOST=salesserver1)(PORT=1522)) (SECURITY= (TLS_SERVER_DN_MATCH=ON) (TLS_SERVER_CERT_DN="C=US,O=example,CN=OracleContext") (TOKEN_AUTH=OAUTH) (TOKEN_LOCATION="/home/dbuser1/access-token/mytoken")) (CONNECT_DATA=(SERVICE_NAME=sales.us.example.com)) )

    In the sqlnet.ora file:

    TLS_SERVER_DN_MATCH=TRUE TOKEN_AUTH=OAUTH  TOKEN_LOCATION="/home/dbuser1/access-token/mytoken"

    In these examples, the token file name is mytoken. Thus, both the file name and directory path (/home/dbuser1/access-token) are specified. The client gets the access token from the mytoken file in the specified path.

    Related Topics

    WALLET_LOCATION

    Use the WALLET_LOCATION parameter in the tnsnames.ora file to specify different locations where Oracle wallets are stored.

    Purpose

    This parameter denotes a connection specific wallet. You can use this parameter when different connections need to use different wallets on the client side.

    Usage Notes

    Default

    None

    Examples

    net_service_name=
 (DESCRIPTION=
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
   (CONNECT_DATA=
     (SERVICE_NAME=sales.us.example.com))
      (SECURITY=(wallet_location=/home/oracle/wallets/databases)))
    ssl_certs1 =
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=shobeen.us.example.com) (PORT=1750))
       (CONNECT_DATA=(SID=sales_pdb))
       (SECURITY=(WALLET_LOCATION=/oracle/wallets/certificates/sales_cert))
     )
ssl_certs2 =
    (DESCRIPTION =
       (ADDRESS=(PROTOCOL=tcps)(HOST=shobeen.us.example.com) (PORT=1750))
       (CONNECT_DATA=(SID=marketing_pdb))
       (SECURITY=(WALLET_LOCATION=/oracle/wallets/certificates/marketing_cert))
     )

    Related Topics

    Timeout Parameters

    The timeout section of the tnsnames.ora file provides the ability to specify timeout and retry configuration through the TNS connect string.

    The following parameters can be set at the DESCRIPTION level of a connect string:

    CONNECT_TIMEOUT

    Use the tnsnames.ora parameter CONNECT_TIMEOUT to specify the amount of time, in milliseconds, seconds, or minutes, in which clients must establish Oracle Net connections to database instances.

    Purpose

    To specify the timeout duration in ms or msec (milliseconds), sec (seconds), or min (minutes) for a client to establish an Oracle Net connection to Oracle Database.

    Usage Notes

    Examples

    net_service_name=
 (DESCRIPTION=
  (CONNECT_TIMEOUT=10 ms)(RETRY_COUNT=3)
  (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=
   (SERVICE_NAME=sales.us.example.com)))

    Related Topics

    RETRY_COUNT

    Use the tnsnames.ora parameter RETRY_COUNT to specify the number of times an ADDRESS list is traversed before terminating the connection attempt.

    Purpose

    To specify the number of times an ADDRESS list is traversed before the connection attempt is terminated.

    Usage Notes

    Put this parameter under the DESCRIPTION parameter.

    When a DESCRIPTION_LIST is specified, each DESCRIPTION is traversed multiple times based on the specified number of retries.

    Example

    net_service_name=
(DESCRIPTION_LIST=
 (DESCRIPTION=
  (CONNECT_TIMEOUT=10)(RETRY_COUNT=3)
  (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1a-svr)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1b-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales1.example.com)))
 (DESCRIPTION=
  (CONNECT_TIMEOUT=60)(RETRY_COUNT=1)
  (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2a-svr)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2b-svr)(PORT=1521)))
  (CONNECT_DATA=(SERVICE_NAME=sales2.us.example.com))))

    RETRY_DELAY

    Use the tnsnames.ora parameter RETRY_DELAY to specify the delay between connection retries.

    Purpose

    To specify the delay between subsequent retries for a connection in units of ms or msec (milliseconds), sec (seconds), or min (minutes). This parameter works in conjunction with the RETRY_COUNT parameter.

    Usage Notes

    Example

    net_service_name=
(DESCRIPTION_LIST=
  (DESCRIPTION=
   (CONNECT_TIMEOUT=10)(RETRY_COUNT=3)(RETRY_DELAY=800ms)
   (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=myhost1)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=myhost2)(PORT=1521)))
   (CONNECT_DATA=(SERVICE_NAME=example1.com)))
  (DESCRIPTION=
   (CONNECT_TIMEOUT=60)(RETRY_COUNT=1)(RETRY_DELAY=5sec)
   (ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=tcp)(HOST=myhost3)(PORT=1521))
    (ADDRESS=(PROTOCOL=tcp)(HOST=myhost4)(PORT=1521)))
   (CONNECT_DATA=(SERVICE_NAME=example2.com))))

    Related Topics

    TRANSPORT_CONNECT_TIMEOUT

    Use the tnsnames.ora parameter TRANSPORT_CONNECT_TIMEOUT to specify the transport connect timeout duration, in milliseconds, seconds, or minutes.

    Purpose

    To specify the transport connect timeout duration in ms or msec (milliseconds), sec (seconds), or min (minutes) for a client to establish an Oracle Net connection to Oracle Database.

    Usage Notes

    Example

    net_service_name =
  (DESCRIPTION=
    (TRANSPORT_CONNECT_TIMEOUT=10 ms)
    (ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
      (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
    (CONNECT_DATA=
      (SERVICE_NAME=sales.us.example.com)))

    Related Topics

    RECV_TIMEOUT

    Use the tnsnames.ora parameter RECV_TIMEOUT to specify the duration of time that a database client or server should wait for data from a peer after establishing a connection.

    Purpose

    To specify the time duration in ms or msec (milliseconds), sec (seconds), min (minutes), or hr (hours) for a database client or server to wait for data from the peer after establishing a connection. The peer must send data within the time interval that you specify.

    Usage Notes

    Default Value

    None

    Minimum Value

    1 ms

    Allowed Range

    Any number greater than the minimum value of 1 ms up to 4294967295 ms.

    Examples

    net_service_name=
 (DESCRIPTION=
  (CONNECT_TIMEOUT=10ms)(RETRY_COUNT=3)(RECV_TIMEOUT=10ms)
  (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-svr)(PORT=1521))
   (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-svr)(PORT=1521)))
  (CONNECT_DATA=
   (SERVICE_NAME=sales.us.example.com)))

    Related Topics

    Compression Parameters

    The compression section of the tnsnames.ora file provides the ability to enable compression and specify compression levels. These parameters can be set at the DESCRIPTION level of a connect string.

    COMPRESSION

    The tnsnames.ora file’s compression parameter enables or disables the data compression.

    Purpose

    To enable or disable data compression.

    Usage Notes

    Put this parameter under the DESCRIPTION parameter.

    Setting this parameter in the connect descriptor for a client overrides the SQLNET.COMPRESSION parameter in the client-side sqlnet.ora file.

    Default

    off

    Values

    Example

    net_service_name=
 (DESCRIPTION=
   (COMPRESSION=on)
      (ADDRESS_LIST=
         (ADDRESS= (PROTOCOL=tcp) (HOST=sales1-server) (PORT=1521))
         (ADDRESS= (PROTOCOL=tcp) (HOST=sales2-server) (PORT=1521)))
   (CONNECT_DATA=
       (SERVICE_NAME=sales.us.example.com)))

    Related Topics

    COMPRESSION_LEVELS

    The COMPRESSION_LEVELS parameter of the tnsnames.ora file specifies the compression level.

    Purpose

    To specify the compression level.

    Usage Notes

    The compression levels are used at the time of negotiation to verify which levels are used at both ends, and select one level. Put this parameter under the DESCRIPTION parameter.

    This parameter is used with the COMPRESSION parameter. Setting this parameter in the connect descriptor for a client overrides the SQLNET.COMPRESSION_LEVELS parameter in the client-side sqlnet.ora file.

    Default

    low

    Values

    Example

    net_service_name=
 (DESCRIPTION=
  (COMPRESSION=on)
  (COMPRESSION_LEVELS=(LEVEL=low)(LEVEL=high))
   (ADDRESS_LIST=
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales1-server)(PORT=1521))
     (ADDRESS=(PROTOCOL=tcp)(HOST=sales2-server)(PORT=1521)))
  (CONNECT_DATA=
    (SERVICE_NAME=sales.us.example.com)))

    Related Topics