7 Centralized Configuration Provider Naming Parameters

This chapter describes the parameters for configuring the Centralized Configuration Provider naming method.

7.1 Overview of the Centralized Configuration Provider Naming

Azure App Configuration and Oracle Cloud Infrastructure (OCI) Object Storage provide services to centrally manage configuration data.

Instead of storing connect descriptors on a client in the tnsnames.ora file, you can store them in a Centralized Configuration Provider. This centralizes network service names and addresses in a single location, facilitating administration (addition, deletion, or modification) of connect descriptors. This also enables you to centrally manage password change policies for all stored database user names and passwords.

  • Azure App Configuration Store:

    In the Azure App Configuration store, you organize connect descriptors and other details under a prefix. A Centralized Configuration Provider connect identifier takes this prefix from the Azure App Configuration endpoint and uses it to locate the connect descriptor, database user name and password, and other Oracle Call Interface configuration parameters.

  • JSON File in the OCI Object Storage:

    In the OCI Object Storage, you organize connect descriptors and other details in a JSON file. A Centralized Configuration Provider connect identifier refers to JSON objects with specific names for resolving connect identifiers to connect descriptors.

7.2 Allowed Parameter Names and Values in Connect Descriptors

These are the restrictions on the parameter names and values that can appear in the connect descriptor, when using the Centralized Configuration Provider naming method.

7.2.1 Naming-Restricted Parameter Names

This is a list of all left-hand side naming parameters (before =) allowed in a connect_descriptor value, which you specify in the Azure App Configuration store or Oracle Cloud Infrastructure (OCI) Object Storage JSON file.

All parameters that can potentially access the file-system are restricted to avoid errors, especially in multi-tenant, middle-tier environments. This is because a tenant may potentially add references to a wallet of another tenant. All the parameters that may cause process-level changes or issues with unintended resource usage are also restricted.

Parameter

ADDRESS

ADDRESS_LIST

BACKUP

COLOCATION_TAG

COMPRESSION

COMPRESSION_LEVELS

CONNECT_DATA

CONNECTION_ID_PREFIX

CONNECT_TIMEOUT

DELAY

DESCRIPTION

DESCRIPTION_LIST

ENABLE

EXPIRE_TIME

FAILOVER

FAILOVER_MODE

GLOBAL_NAME

HOST

HS

HTTPS_PROXY

HTTPS_PROXY_PORT

IGNORE_ANO_ENCRYPTION_FOR_TCPS

INACTIVITY_TIMEOUT

INCREMENT

INSTANCE_NAME

LOAD_BALANCE

LOB_PREFETCH_SIZE

MAX

MAX_LIFETIME_SESSION

MAX_USE_SESSION

METHOD

MIN

OCI

POOL_BOUNDARY

POOL_CONNECTION_CLASS

POOL_NAME

POOL_PURITY

PORT

PREFETCH_ROWS

PROTOCOL

RDB_DATABASE

RECV_BUF_SIZE

RECV_TIMEOUT

RESTORE

RETRIES

RETRY_COUNT

RETRY_DELAY

SDU

SECURITY

SEND_BUF_SIZE

SERVER

SERVICE_NAME

SERVICE_TAG

SESSION_POOL

SHARDING_KEY

SID

SSL_SERVER_CERT_DN

SSL_SERVER_DN_MATCH

STATEMENT_CACHE_SIZE

SUPER_SHARDING_KEY

TRANSPORT_CONNECT_TIMEOUT

TYPE_OF_SERVICE

WALLET_LOCATION

7.2.2 Naming-Restricted Parameter Values

For some of the naming-restricted parameter names, some values are not allowed on the right-hand side (after =).

Note these restrictions on the values that you can specify:

Parameter Restriction

PROTOCOL

BEQ or Fork capability is not allowed.

The allowed values are:
  • TCP

  • TCPS

  • WSS

  • EXADIRECT

WALLET_LOCATION

Only SYSTEM is allowed.

For the METHOD sub-parameter, the allowed values are:
  • OCIVAULT

  • AZUREVAULT

  • BASIC

  • PRECONNECT

Note:

To disable these naming restrictions, set the sqlnet.ora parameter or environment variable NAMES.CLOUD_NAMING_RESTRICTIONS to FALSE. The default value for this parameter is TRUE.

7.3 Authentication Parameters for Azure App Configuration Store

These are the authentication parameters that you specify in the connect identifier (using the option=value syntax) to access the Azure App Configuration store.

7.3.1 AUTHENTICATION

Use the AUTHENTICATION parameter to specify the authentication method that you want to use for accessing the Azure App Configuration store.

Purpose

To control how the Centralized Configuration Provider component authenticates with the Azure App Configuration store.

This is an optional parameter. If you do not set authentication method, then the default setting (AUTHENTICATION=AZURE_DEFAULT) is used to provide the Azure Service Principal flow. Set this parameter only if you want to override this default flow.

Usage Notes

Specify this parameter in the connect identifier string at the command line using the option=value syntax. Depending on the specified authentication method, you must additionally set the corresponding authentication parameters in the same string as given below:

  • AZURE_DEFAULT provides the default token credential authentication using the Azure Service Principal (or OAuth 2.0 Client Credential) flow.

    This authenticates to Azure Active Directory (Azure AD) as a service principal using either a client secret or an X509 client certificate assigned during App Registration.

    The client driver evaluates the following credential types (if enabled) in an order:

    1. Azure Service Principal with Client Secret Credentials:
      1. The driver checks if the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET parameters are set at the command line.
      2. If the preceding parameters are not set, then it tries the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET environment variables. If configured, then the driver authenticates as a service principal using client secret. Otherwise, the driver proceeds to the next step.
    2. Azure Service Principal with Client Certificate Credentials:
      1. The driver checks if the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_CERTIFICATE_PATH parameters are set at the command line.
      2. If the preceding parameters are not set, then it tries the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_CERTIFICATE_PATH environment variables. If configured, then the driver authenticates as a service principal using client certificate.

    Note:

    For both of these flows, if all the environment variables are set (that is, AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET, and AZURE_CLIENT_CERTIFICATE_PATH), then the driver first attempts AZURE_TENANT_ID, AZURE_CLIENT_ID and AZURE_SECRET_ID values.
  • AZURE_SERVICE_PRINCIPAL provides the Azure Service Principal flow.

    Similar to the default flow, this authenticates the request as a service principal using either the client secret or client certificate assigned during App Registration. However, here the driver looks only at the command line parameters, as follows:
    1. The driver first tries the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET parameters set at the command line.

    2. If client secret is not set, then the driver looks for client certificate by trying the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_CERTIFICATE_PATH parameters.

      Note:

      If both the AZURE_CLIENT_SECRET and AZURE_CLIENT_CERTIFICATE_PATH parameters are set, then this flow uses client certificate for authentication.
  • AZURE_MANAGED_IDENTITY provides either the Azure Managed Identity flow or the Azure Managed User Identity flow.

    This method works for Azure Virtual Machines, App Service, Azure Functions applications, and the Azure Cloud Shell. This attempts authentication to Azure AD using a managed identity assigned to the deployment environment.

    If you want to use a "user-assigned" managed identity for authentication, then you must additionally specify the AZURE_MANAGED_IDENTITY_CLIENT_ID authentication parameter.

Values

  • AZURE_DEFAULT to enable the default token credential authentication flow

  • AZURE_SERVICE_PRINCIPAL to enable authentication using client credentials set at the command line

  • AZURE_MANAGED_IDENTITY to enable authentication using managed identity or managed user identity credentials

Default

AZURE_DEFAULT

Example

AUTHENTICATION=AZURE_SERVICE_PRINCIPAL

7.3.2 AZURE_CLIENT_ID

Use the CLIENT_ID parameter to specify the ID of the Microsoft Azure Active Directory (Azure AD) application.

Purpose

To specify the client ID associated with Azure App Registration for authenticating to Azure AD.

You use this parameter for the AZURE_DEFAULT and AZURE_SERVICE_PRINCIPAL authentication flows to access the Azure App Configuration store.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

Client (application) ID of an App Registration in the tenant. You can get this value from the registered application essentials page in the Azure portal.

Example

AZURE_CLIENT_ID=123ab4cd-1a2b-1234-a12b-aa00123b2cd3

7.3.3 AZURE_TENANT_ID

Use the AZURE_TENANT_ID parameter to specify the tenant ID associated with the Microsoft Azure Active Directory (Azure AD) subscription.

Purpose

To specify the tenant ID associated with the Azure AD subscription. Azure AD is trusted to authenticate users, services, and devices for the subscription.

You use this parameter for the AZURE_DEFAULT and AZURE_SERVICE_PRINCIPAL authentication flows to access the Azure App Configuration store.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

Azure AD tenant ID associated with Azure subscription. You can get this value from the Overview page under Basic information in the Azure portal.

Example

AZURE_TENANT_ID=1a123ab1-a1b1-1a2b-a1b2-a12bcdab0123

7.3.4 AZURE_CLIENT_SECRET

Use the AZURE_CLIENT_SECRET parameter to specify a client secret for your Microsoft Azure Active Directory (Azure AD) application.

Purpose

To specify a client secret associated with Azure App Registration for authenticating to Azure AD. This credential enables confidential applications to identify themselves to the authentication service, when receiving tokens at a web address location (using an HTTPS scheme).

You use this parameter for the AZURE_DEFAULT and AZURE_SERVICE_PRINCIPAL authentication flows to access the Azure App Configuration store.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

Client secret generated during App Registration. This value appears on the Certificates and Secrets page when you create a new client secret in the Azure portal.

Example

AZURE_CLIENT_SECRET=a1abcd12abcd1abc1abc1abc12a

7.3.5 AZURE_CLIENT_CERTIFICATE_PATH

Use the AZURE_CLIENT_CERTIFICATE_PATH parameter to specify a client certificate of the Microsoft Azure Active Directory (Azure AD) application.

Purpose

To enable authentication to Azure AD as a service principal, using an X509 certificate assigned during App Registration.

You use this parameter for the AZURE_DEFAULT and AZURE_SERVICE_PRINCIPAL authentication flows to access the Azure App Configuration store.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

File system path to a PEM or PKCS12 certificate file including the private key. This certificate file must have a private key without password. Ensure that you protect this certificate with necessary file permissions.

Example

AZURE_CLIENT_CERTIFICATE_PATH=ORACLE_HOME/.azure/certificates/my-app.pem

7.3.6 AZURE_MANAGED_IDENTITY_CLIENT_ID

Use the AZURE_MANAGED_IDENTITY_CLIENT_ID parameter to specify a user-assigned managed identity for authentication with Microsoft Azure Active Directory (Azure AD).

Purpose

To specify a user-assigned managed identity if you are using the Managed User Identity authentication flow for accessing the Azure App Configuration store. This managed identity acts as a standalone Azure AD resource.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax, along with the AUTHENTICATION=AZURE_MANAGED_IDENTITY setting.

For example:
sqlplus /@"config-azure://dbclient-appconfig?key=/database/hr/&authentication=azure_managed_identity&azure_managed_identity_client_id=b1c1234-1a12-1234-ab12-3a1a1bc12a"

Default

None

Value

Client ID for a user-assigned managed identity. You can get this value from the Managed Identities - Overview page in the Azure portal.

Example

AZURE_MANAGED_IDENTITY_CLIENT_ID=b1c1234-1a12-1234-ab12-3a1a1bc12a

7.3.7 HTTPS_PROXY

Use the HTTPS_PROXY parameter to specify the HTTPS proxy host name when the client is behind a corporate HTTPS proxy.

Purpose

To specify the HTTPS proxy host name for tunneling Transport Layer Security (TLS) client connections, when the client is behind a corporate HTTPS proxy.

Default

None

Value

HTTPS proxy host name

Examples

HTTPS_PROXY=www-proxy.example.com

7.3.8 HTTPS_PROXY_PORT

Use the HTTPS_PROXY_PORT parameter to specify the HTTPS proxy port when the client is behind a corporate HTTPS proxy.

Purpose

To specify the HTTPS proxy port for tunneling TLS client connections, when the client is behind a corporate HTTPS proxy.

Default

None

Value

HTTPS proxy port number

Example

HTTPS_PROXY_PORT=80

7.3.9 TIMEOUT

Use the TIMEOUT parameter to specify the duration to complete each HTTP call.

Purpose

To specify the duration to complete each HTTP call. Set this parameter to avoid long network delays or indefinite waiting for a server's response.

Value

Timeout on each HTTP call, in seconds

Default

None

Example

TIMEOUT=60

7.4 Authentication Parameters for OCI Object Storage

These are the authentication parameters that you specify in the connect identifier (using the option=value syntax) to access the Oracle Cloud Infrastructure (OCI) Object Storage JSON file.

7.4.1 AUTHENTICATION

Use the AUTHENTICATION parameter to specify the authentication method that you want to use for accessing the Oracle Cloud Infrastructure (OCI) Object Storage JSON file.

Purpose

To control how the Centralized Configuration Provider component authenticates with the OCI Object Storage JSON file.

This is an optional parameter. If you do not set authentication method, then the default setting (AUTHENTICATION=OCI_DEFAULT) is used to provide the OCI API Key flow. Set this parameter only if you want to override this default flow.

Usage Notes

Specify this parameter in the connect identifier using the option=value syntax. Depending on the specified authentication method, you must additionally set the corresponding authentication parameters in the same string as given below:

  • OCI_DEFAULT provides the default profile-based OCI authentication using the OCI API Key flow. This flow enables authentication to OCI using API key-related values.

    The client driver evaluates the following credential types (if enabled) in an order:
    1. It first checks if the OCI_TENANCY, OCI_USER, OCI_FINGERPRINT, and OCI_KEY_FILE parameters are set at the command line.

    2. If the preceding parameters are not set, then it checks for these parameters in the OCI configuration file present at the default location (~/.oci/config) or at the location specified by the OCI_CONFIG_FILE environment variable.

      The driver then checks if the file is present at the location configured by the OCI_PROFILE_PATH parameter.

      Finally, the driver checks if the file contains a profile matching the name configured by the OCI_PROFILE parameter or the default name (DEFAULT).

  • OCI_INSTANCE_PRINCIPAL provides the OCI Instance Principal flow. This flow enables authentication to OCI using VM instance credentials running on OCI.

  • OCI_RESOURCE_PRINCIPAL provides the OCI Resource Principal flow. This flow enables authentication to OCI using OCI resource principals.

Default

OCI_DEFAULT

Values

  • OCI_DEFAULT to enable the default profile-based OCI authentication using API key-related values

  • OCI_INSTANCE_PRINCIPAL to enable authentication using VM instance credentials

  • OCI_RESOURCE_PRINCIPAL to enable authentication using OCI resource principals

Example

AUTHENTICATION=OCI_RESOURCE_PRINCIPAL

7.4.2 OCI_PROFILE

Use the OCI_PROFILE parameter to specify the profile file section name.

Purpose

To specify the profile file section name. This profile is the client connection information stored in your Oracle Cloud Infrastructure (OCI) configuration file.

You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

DEFAULT

Value

Profile file section name to use for authentication to OCI.

Example

OCI_PROFILE=ADMIN_USER

7.4.3 OCI_PROFILE_PATH

Use the OCI_PROFILE_PATH parameter to override the default Oracle Cloud Infrastructure (OCI) configuration file location.

Purpose

To override the default OCI configuration file location. You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

If you do not set this parameter, then the client driver looks for the OCI configuration file either at the default location (~/.oci/config) or at the location specified by the OCI_CONFIG_FILE environment variable.

Default

None

Value

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

Example

OCI_PROFILE_PATH=/app/myociprofile/config

7.4.4 OCI_TENANCY

Use the OCI_TENANCY parameter to specify the tenant ID associated with Oracle Cloud Infrastructure (OCI) subscription.

Purpose

To specify the tenant ID associated with OCI subscription. OCI ID is trusted to authenticate users, services, and devices for the subscription.

You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

Tenancy's Oracle Cloud Identifier (OCID). You can get this value from the Tenancy Details page under Tenancy Information in the OCI console.

Example

OCI_TENANCY=1a123ab1-a1b1-1a2b-a1b2-a12bcdab0123

7.4.5 OCI_USER

Use the OCI_USER parameter to specify the user ID associated with Oracle Cloud Infrastructure (OCI) subscription.

Purpose

To specify the user ID associated with OCI subscription. You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

User's Oracle Cloud Identifier (OCID). You can get this value from the User Details page under User Information in the OCI console.

Example

OCI_USER=ocid1.user.oc1..aa1abcd12bc1abcd1abcdf1abcdfg12abcd

7.4.6 OCI_KEY_FILE

Use the OCI_KEY_FILE parameter to specify location of the Oracle Cloud Infrastructure (OCI) private key file.

Purpose

To specify location of the OCI private key file. You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

If you want to make API requests, then you must obtain an RSA public key in PEM format (minimum 2048 bits) added to your OCI Identity Access Management (IAM) user profile and sign the API requests with the corresponding private key.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

OCI private key file location. This value must be corresponding to the public key added to the IAM user profile.

Example

OCI_KEY_FILE=~/.oci/oci_api_key.pem

7.4.7 OCI_FINGERPRINT

Use the OCI_FINGERPRINT parameter to specify the fingerprint of the Oracle Cloud Infrastructure (OCI) Identity and Access Management (IAM) profile key.

Purpose

To specify the fingerprint of the key added to the OCI IAM profile. You use this parameter for the OCI API Key authentication flow to access the OCI Object Storage JSON file.

Usage Notes

Set this parameter at the command line in the connect identifier using the option=value syntax.

Default

None

Value

Key's fingerprint. You can get this value from the User Details page under API Keys in the OCI console.

Example

OCI_FINGERPRINT=a1:12:a1:1a:01:12:23:34:ab:12:ab:0a:12:a1:

7.4.8 HTTPS_PROXY

Use the HTTPS_PROXY parameter to specify the HTTPS proxy host name when the client is behind a corporate HTTPS proxy.

Purpose

To specify the HTTPS proxy host name for tunneling Transport Layer Security (TLS) client connections, when the client is behind a corporate HTTPS proxy.

Default

None

Value

HTTPS proxy host name

Examples

HTTPS_PROXY=www-proxy.example.com

7.4.9 HTTPS_PROXY_PORT

Use the HTTPS_PROXY_PORT parameter to specify the HTTPS proxy port when the client is behind a corporate HTTPS proxy.

Purpose

To specify the HTTPS proxy port for tunneling TLS client connections, when the client is behind a corporate HTTPS proxy.

Default

None

Value

HTTPS proxy port number

Example

HTTPS_PROXY_PORT=80

7.4.10 TIMEOUT

Use the TIMEOUT parameter to specify the duration to complete each HTTP call.

Purpose

To specify the duration to complete each HTTP call. Set this parameter to avoid long network delays or indefinite waiting for a server's response.

Value

Timeout on each HTTP call, in seconds

Default

None

Example

TIMEOUT=60