1. Developer's Guide
  2. Installing and Configuring Oracle Data Provider for .NET
  3. Centralized Configuration Providers for Deployments

Centralized Configuration Providers for Deployments

Managed ODP.NET and ODP.NET Core can store and retrieve connection string configuration values securely from a centralized provider. Centralizing ODP.NET connection configuration information makes managing user credentials easier in an app deployment. Ensuring connection strings are stored securely is necessary since they can contain sensitive information, such as passwords.

This configuration provider is available for ODP.NET cloud deployments and on-premises deployments and work with any Oracle database version ODP.NET supports. It can be stored in the following locations:

  • Microsoft Azure: Store database connection information in Azure App Configuration and Azure Key Vault.

  • Oracle Cloud Infrastructure (OCI): Store database connection information in OCI Object Storage and OCI Vault.

  • Local file system: Store database connection information on the local file system for web and desktop apps.

Since centralized configuration providers are often used for cloud deployments, local file system access is disabled by default when the connection string is populated with an URL. To enable local access, set OracleConnection.RemoteConfigurationFiltering to false.

Connection String URLs

The connection string URL is different from the traditional ODP.NET connection string format. To access the Azure, OCI, or local file centralized configuration provider, ODP.NET apps specify a URL in the OracleConnection ConnectionString property in place of the traditional ODP.NET connection string. This URL contains the centralized configuration provider type, that is, Azure, and its configuration storage name, as well as authentication and connection configuration parameter values, if applicable. The traditional connection string values, such as User Id and Min Pool Size are stored within the centralized configuration provider itself.

Nonetheless, it remains simple moving from a traditional ODP.NET connection string to the centralized configuration provider model. The traditional ODP.NET connection string attributes and values are moved over to Azure App Configuration, OCI Object Storage, or local directory. Then, the ConnectionString property is set to the connection string URL instead of a traditional ODP.NET connection string.

Sensitive information, such as passwords, can be stored in secure stores, such Azure Key Vault and OCI Vault, or be encoded. The centralized configuration providers do not support storing plain text passwords in the connection string.

If using pooling, ODP.NET caches the connection string URL. Changing the configuration values in the centralized storage after the pool populates will not change the connection pool properties until the application is restarted.

If pooling is disabled, the connection string URL is not cached. Changes to the connection configuration is then possible for subsequent connection requests without an application restart.

Connection strings begin with the format config-<provider type> where the provider type is azure, ociobject, or file, depending on the deployment location.

Azure Centralized Configuration Provider

The Azure configuration provider can use Azure App Configuration and Azure Key Vault store to store Oracle database connection information. The Azure Centralized Configuration Provider connection string URL syntax is:

config-azure://{Config Name}[?Key=Prefix&Label=Value&Option1=Value1&Option2=Value2...]

  • (Required) Config Name: The Azure App Configuration name

  • (Optional) Key: a key prefix to identify the connection. Ending the key prefix with a separator, such as ":", “/” or ".", improves readability, but is not a technical requirement. If a key is not specified, a top-level connection is implied.

  • (Optional) Label: The Azure App Configuration label name

  • (Optional) Options and Values: The Azure authentication and change notification options and information to use when connecting to the Azure App Configuration service. If no authentication information is provided, ODP.NET uses Azure Default Credential to access the Azure App Configuration. More information about Azure change notification is in the Connection URL Caching documentation.

Azure Authentication Options

ODP.NET uses the Azure SDK for .NET credential classes to provide authorization and authentication to Azure App Configuration and Key Vault services. This dependency can be resolved by having your project incorporate the Oracle.ManagedDataAccess.Azure package available on NuGet Gallery when Azure authentication is required.

Developers set the Azure authentication option to “Authentication” in the ODP.NET URL connection string. The possible values for this option are listed in the following table.

Note:

These options and values are case insensitive. The required parameters can be set alternatively as environment variables

Table 2-10 Azure Authentication Methods and their Values

Authentication Method Authentication Option Values Required Parameters for This Option Value Optional Parameters for This Option Value

Default Azure Credential

AZURE_DEFAULT or Empty String

AZURE_TENANT_ID

AZURE_MANAGED_IDENTITY_CLIENT_ID

Service Principal with client secret*

AZURE_SERVICE_PRINCIPAL

AZURE_CLIENT_ID

AZURE_CLIENT_SECRET

AZURE_TENANT_ID

Service Principal with client certificate*

AZURE_SERVICE_PRINCIPAL

AZURE_CLIENT_ID

AZURE_CLIENT_CERTIFICATE_PATH

AZURE_TENANT_ID

AZURE_CLIENT_CERTIFICATE_PASSWORD

Managed Identity

AZURE_MANAGED_IDENTITY

AZURE_CLIENT_ID - required only if user assigned

Interactive Browser OAuth token flow

AZURE_INTERACTIVE

AZURE_CLIENT_ID

AZURE_REDIRECT_URL

* The Azure service principal with client secret overrides Azure service principal with client certificate.

The ODP.NET connection string URL provides more connection configuration options, including:

  • AZURE_MAX_RETRIES

  • AZURE_RETRY_TIMEOUT

  • AZURE_MANAGED_IDENTITY_CLIENT_ID - only available when using DefaultAzureCredential and for user assigned.

  • AZURE_TENANT_ID

  • AZURE_AUTHORITY_HOST

The following code sample provides an ODP.NET connection string URL that specifies an Azure App configuration store name called MyConfig. The prefix key for the connection in MyConfig is MyConnection and the Azure App Configuration label name is production. The code sample uses Azure Managed Identity authentication to connect and supplies that id value. The code sample then sets the connection string URL using OracleConnection constructor. ODP.NET obtains the connection string from the Azure App Configuration store implicitly when opening the connection. 

       {
        // This ODP.NET URL uses Azure Managed Identity authentication
        string connectionString = "config-azure://MyConfig?key=
          MyConnection/&Label=production&Authentication=Azure_Managed_Identity&
          Azure_Managed_Identity_Client_Id=111abccd8-18cc-4fa0-bf7b-d894e5981c67";      
        OracleConnection conn = new OracleConnection();
        conn.ConnectionString = connectionString;
        conn.Open();
 	}

See Also:

DefaultAzureCredential Class for more information about Azure identity and authentication.

OCI Centralized Configuration Provider

The Oracle Cloud Infrastructure configuration provider uses OCI Object Storage and OCI Vault to store database connection information in a JSON configuration file. The connection string URL syntax is:

config-ociobject://{Object-Url}[?key=name&option1=value1&option2=value2...]

  • (Required) Object-Url: The object URL path in OCI Object Storage. This value can be obtained in the OCI Web Console in the Object Details of the Object Storage / Buckets / Object menu. Two examples of Object-Urls are:

    https://namespace.objectstorage.us-ashburn-1.oci.customer-oci.com/n/namespace/b/bucket1/o/odp.json

    and,

    https://objectstorage.us-ashburn-1.orclecloud.com/n/namespace/b/bucket1/o/odp.json.

  • (Optional) Key: The connection key name identity. If a key is not specified, a top-level connection is implied.

  • (Optional) Options: The Oracle Cloud authentication and change notification options and information to use when connecting to OCI Object Storage. If no authentication is provided, then the provider uses OCI API Key-Based Authentication to access OCI Object Storage. More information about Oracle Cloud change notification is in the Connection URL Caching documentation.

OCI Authentication Options

ODP.NET OCI authentication has a dependency on OCI SDK for authorization and authentication to the OCI Object Storage and Vault services. This dependency can be resolved by having your project incorporate the Oracle.ManagedDataAccess.Oci package available on NuGet Gallery when OCI authentication is required.

The authentication parameters are provided via the connection string URL.

Developers set the OCI authentication option to Authentication in the ODP.NET URL connection string. The possible values for this option are listed in the following table.

Note:

These options and values are case insensitive. The required parameters can be set alternatively as environment variables

Table 2-11 OCI Authentication Methods and their Values

Authentication Method Authentication Option Values Optional Configuration Optional Parameters

API Key-Based Authentication

OCI_DEFAULT or Empty String

(~/.oci/config),

(~/.oraclebmc/config), or

environment variable OCI_CONFIG_FILE

OCI_PROFILE

OCI_TENANCY

OCI_USER

OCI_FINGERPRINT

OCI_KEY_FILE

OCI_PASS_PHRASE

Instance Principal Authentication

OCI_INSTANCE_PRINCIPAL

Resource Principal Authentication

OCI_RESOURCE_PRINCIPAL

The following code sample provides an ODP.NET connection string URL that specifies an OCI Object Store object URL. The connection key name identity is MyConnection. The code sample uses OCI's API key-based authentication, OCI_DEFAULT, and the optional parameter, OCI_PROFILE, to specify the connection profile configuration. The code sample then sets the connection string URL using OracleConnection ConnectionString property. ODP.NET obtains the connection string from the JSON configuration file stored in OCI Object Storage Service when opening the connection. 

      {
        //This URL will use default OCI authentication, which requires no authentication parameters
        string connectionString = "config-ociobject://https://objectstorage.us-ashburn-1.
          oraclecloud.com/n/namespace/b/bucket1/o/odp.json?key=MyConnection&authentication
          =OCI_DEFAULT&OCI_PROFILE=MyProfile";
        OracleConnection conn = new OracleConnection(connectionString);
        conn.Open();
      }

See Also:

OCI SDK Authentication Methods for more information.

Local File Centralized Configuration Provider

The file config provider stores Oracle database connection information in a JSON configuration file on the local file system. The ODP.NET file connection string URL syntax is:

config-file://{File Path}[?Key=name&tns_admin=filepath]

  • (Required) File Path: JSON config file path and name, which can be an absolute or relative path. For relative paths, ODP.NET will use the TNS_ADMIN value as the base path.

  • (Optional) Key: The connection key name identity. If a key is not specified, a top-level connection is implied.

  • (optional) tns_admin: the filename base path or prefix to locate the JSON config file.

The following code sample provides an ODP.NET connection string URL that specifies a local file, odpconfig.json, and directory location. The connection key name identity is MyConnection. This code sample then sets the connection string URL using OracleConnection constructor. ODP.NET obtains the connection string from the local JSON config file when opening the connection. 

      {
        //This URL will retrieve the c:\configs\odpconfig.json from the file system
        //The connection key is "MyConnection" 
        string connectionString = "config-file://c:/configs/odpconfig.json?key=MyConnection";

        OracleConnection conn = new OracleConnection(connectionString);
        conn.Open();
      }

The file config provider relies on Oracle.ManagedDataAccess.ConfigFile package available on NuGet Gallery.

JSON Configuration File Search Order

ODP.NET can use the absolute directory and file name value, that is, c:/configs/myconfig.json, set in the local file centralized configuration provider connection string URL to locate its JSON configuration file. It can also use a relative directory with a file name. In this case, it will append the relative directory and file to the settings in the following order to locate the JSON file.

  1. Current working directory

  2. Directory set in OracleConnection.TnsAdmin property

  3. Directory set for the Tns_Admin connection string attribute

  4. Directory set in the tns_admin attribute of the configuration provider URL

  5. Directory set in OracleConfiguration.TnsAdmin property

  6. TNS_ADMIN directory setting in .NET configuration file -- managed ODP.NET only

  7. TNS_ADMIN directory setting of the Windows environment variable or container environment variable

  8. Directory set in the Windows Registry key, HKLM\SOFTWARE\Oracle\ODP.NET.Managed\<version>\TNS_ADMIN -- managed ODP.NET only

    Note:

    32-bit apps use the Registry key HKLM\SOFTWARE\Wow6432Node\Oracle\ODP.NET.Managed\<version>\TNS_ADMIN

  9. %ORACLE_HOME%\network\admin directory

Vault Providers

Database passwords, proxy passwords, wallets, JSON configuration are sensitive database information that can be stored in Azure Key Vault or OCI Vault services as secret. These vault providers are included with the Oracle.ManagedDataAccess.Azure and Oracle.ManagedDataAccess.Oci NuGet packages, respectively.

ODP.NET provides a secured way to access this sensitive information from vaults using a predefined URL, secret-URL. The secret-URL must be prefixed with vault-azure or vault-oci for ODP.NET to access the user provided information in either Azure Key Vault or OCI Vault services, respectively. The user-provided URL must conform to the ODP.NET defined syntax below.

Azure Key Vault

Use the following URL syntax to access Azure Key Vault secrets:

config-azurevault://{Secret Identifier}[?key=name&Option1=Value1&Option2=Value2…]

Applications need to provide the following information in the URL:

  • (Required) Secret Identifier: The Azure secret identifier obtained from the Azure portal

  • (Optional) Key: The connection identifier. If a key is not specified, then it is a top level connection. This option is only used when a JSON configuration file is in Azure Key Vault.

  • (Optional) Authentication Options: The Azure Key Vault authentication connection information. If authentication information is not provided, ODP.NET uses Azure Default Credential to access secrets in Azure Key Vault service. The authentication options are the same as the Azure Authentication Options.

OCI Vault

Use the following URL syntax to access OCI Vault secrets:

config-ocivault://{Secret OCID}[?VersionNumber=Value1&Stage=Value2&key=name&Option3=Value3&Option4=Value4...]

Applications need to provide the following information in the URL:

  • (Required) Secret OCID: The OCI secret identifier (OCID) obtained from the OCI portal

  • (Optional) VersionNumber: The OCI secret version. If the version is not specified, the latest secret version is retrieved by default.

  • (Optional) Stage: The secret's rotation stage. If stage is not specified, the secret's current stage is retrieved by default.

  • (Optional) Key: The connection identifier. If a key is not specified, then it is a top level connection. The option is only used when a JSON configuration file is in the OCI Vault.

  • (Optional) Options: The OCI Vault authentication connection information. If authentication information is not provided, ODP.NET uses the API Key-Based authentication to access secrets in OCI Vault service. The authentication options are the same as the OCI Authentication Options.

Vault Connection String URLs

Similarly for centralized configuration providers, vault URLs can be passed as a connection string to the OracleConnection class through a constructor connection string property or an OracleConnection ConnectionString property.

Here is an example for Azure Vault:

new OracleConnection("config-azurevault://https://vault1.vault.azure.net/secrets/ODPConnStr/
abc69352e1d040e59wd7b83ffcdaf123");

The Vault can contain a standard connection string or a JSON config string.

Standard connection string example:

user id = scott; password = tiger; data source = inst1; pooling = false

JSON config example:

{
    "Connection1": {
        "ODP": {
            "User Id": "scott",
            "Password":"tiger",
            "Data Source": "inst1",
            "Pooling": "false"
        }
    }
}

Note:

The connection/JSON config strings should be uploaded as clear text.

Vault Passwords

Instead of storing the entire connection string, developers have the option to store only the password or proxy password in a cloud vault. To do this, the application provides the vault URL value in the password or proxy password connection string attribute value.

For example, the ODP.NET connection string for Azure Vault could be:

"User ID = HR; Data Source = mydb; 
password=config-azurevault://https://vault1.vault.azure.net/secrets/ODPConnStr/
abc69352e1d040e59wd7b83ffcdaf123"

Vault Wallets and Tokens

An application can store wallets and tokens in cloud vault services securely by providing the vault URL in the ODP.NET wallet and token location properties. The application must store the wallet or token file data in the cloud vault as a base64 string.

Note:

For OCI vault, although wallet and token have to be converted to base64 string, they must be uploaded to OCI vault as "plain-text" type secret.

ODP.NET connection strings can use the Wallet_Location and Token_Location properties, respectively, to store wallets and tokens. For example, the ODP.NET connection string for accessing a wallet stored in Azure Vault could be: 

"User ID = HR; password = <PASSWORD>; Data source = mydb; 
Wallet_Location=config-azurevault://https://vault1.vault.azure.net/secrets/HRWallet/ 
abc69352e1d040e59wd7b83ffcdaf123”

The OracleConnection WalletLocation and TokenLocation properties can be set to a vault URL or file path location. These OracleConnection properties have precedence over the wallet and token location attributes in the connection string. Here's sample code to use these properties with Azure Vault: 

OracleConnection conn = new OracleConnection();
conn.WalletLocation = "config-azurevault://https://vault1.vault.azure.net/secrets/HRWallet/abc693...";
conn.TokenLocation = "config-azurevault://https://vault1.vault.azure.net/secrets/HRToken/abc3ffc...";

Note:

Secure External Password Store is not supported for cloud wallet locations.

ODP.NET supports Microsoft identity platform tokens v1.0 for Microsoft Entra ID-only applications and v2.0 for applications that support consumer accounts. ODP.NET 23.5 and higher check the roles (roles) and user principal name (UPN) claims in v2.0 tokens to verify at least one is present. If both claims are missing, then the provider will report an error.

Provider Configuration

Provider Configuration Keys

The local file and OCI centralized configuration providers both use a JSON format to specify connection information. They both use the same JSON configuration.

ODP.NET uses the values in the provider configuration keys to construct a connection string to an Oracle database. Configuration keys generally map to an existing ODP.NET connection string and Oracle connection properties. Some keys are generic to all Oracle data access drivers. Those properties are:

  • user: database user/schema name

  • password: database password

  • connect_descriptor: ODP.NET data source

  • config_time_to_live: cached connection information retention time in seconds

In Azure App Configuration, the ODP.NET specific configuration keys are prefixed with ODP/ to indicate intent to be used for ODP.NET only. For example, MyConnection/ODP/Pooling key specifies the ODP.NET's Pooling connection string attribute.

For OCI and local file providers, the ODP.NET specific configuration keys are specially identified in the JSON configuration. These keys use the "ODP" key. For example, "ODP": {"Max Pool Size": "500", "Pooling": true } specifies the Max Pool Size and Pooling connection string attributes for MyConnection property in the following example. 

{ 
                "MyConnection": {
                                "ODP": {"Max Pool Size": "500", "Pooling" : true },
                "password": 
                {
                                "type":"ocivault",
                               "value":"ocid1.vaultsecret.oc1.phx.example",
                                "authentication": 
                               {
                                               "method" : "OCI_DEFAULT",
                                                "OCI_PROFILE" : "<PROFILE>"
                                }     
                }
                "user": "HR",
                "connect_descriptor": "(description= .......)"
}

Generally, ODP.NET configuration keys are case insensitive. However, the ODP/ section in Azure App configuration and the ODP section in OCI and local configuration, including the keys and their values, are case-sensitive.

Connection Attributes

The ConnectionString key is an ODP.NET specific key in the configuration provider. It allows defining complete or partial ODP.NET connection strings. ODP.NET apps can continue to use the OracleConnection ConnectionString property and are not required to use the configuration provider's ConnectionString key.

All the connection string attributes defined in OracleConnection ConnectionString are supported as is used in the traditional connection string except the following attribute:

  • Tns_Admin: Not supported.

ODP.NET also supports the following OracleConnection properties in the provider configuration:

  • BindByName

  • CommandTimeout

  • ChunkMigrationConnectionTimeout

  • ConnectionIdPrefix

  • DatabaseEditionName

  • DrcpConnectionClass

  • FetchSize

  • MaxStatementCacheSize

  • OciCompartment

  • OciDatabase

  • OciIamUrl

  • OciTenancy

  • PasswordAuthentication

  • Pipelining

  • ServiceRelocationConnectionTimeout

  • TokenAuthentication

  • UseClientInitiatedCQN

  • Wallet_Location: Wallet that is stored in local system file is not supported. Wallet that is stored as Base64 string in Azure App Configuration, Azure Vault, or OCI vault is supported. For JSON configuration, Wallet_Location must be specified using Password JSON object.

  • Token_Location: Token that is stored in local system file is not supported. Token that is stored as Base64 string in Azure App Configuration, Azure Vault, or OCI vault is supported. For JSON configuration, Token_Location must be specified using Password JSON object.

If a non-supported attribute is specified in the provider configuration under the ODP JSON property or ODP/ Azure App Configuration section, then ODP.NET throws an exception.

The following example contains three connections: sales_app, hr_app, and sh_app using various configuration key types. 

{
  "sales_app":
  {
    "connect_descriptor": "(description=(address=(protocol=tcps)(port=1521)(host=<HOSTNAME>
    (connect_data=(service_name=<SERVICE NAME>))(security=(ssl_server_dn_match=yes)))",
    "user": "sales",
    "password": { 
      "type": "ocivault",
      "value": "<VAULT LOCATION>",
      "authentication": {
        "method": "OCI_INSTANCE_PRINCIPAL"
      }
    },
    "ODP": {
      "Connection Timeout": 30,
      "pooling": “true”,
      "max pool size": 100
    }
  },
  "hr_app":
  {
    "password": { 
      "type": "azurevault",
      "value": "<VAULT LOCATION>",
      "authentication": {
        "method": "AZURE_DEFAULT"
      }
    },
    "ODP": {
      "user": "hr",
      "data source”: "oracle”,
      "max pool size": 100
    }
  },
  "sh_app":
  {
    "ODP": {
      "ConnectionString": "user id = sh; data source = oracle; max pool size = 100",
      "BindByName": "false"
    }
    "password": { 
      "type": "ocivault",
      "value": "<SECRET OCID>",
      "authentication": {
        "method": "OCI_INSTANCE_PRINCIPAL",
        "OCI_PROFILE": "DEFAULT"
      }
    }
  }
}

Within the configuration provider, ConnectionString key has precedence over other keys, such as connect_descriptor, with the same prefix key. Thus, if the User Id attribute is not included in the ConnectionString, then ODP.NET uses the user key that has the same prefix key. If the Data Source attribute is not included in the ConnectionString, then it will use the value of the connect_descriptor key that has the same prefix key. Similar behavior applies for all the ConnectionString attributes.

The precedence order for constructing the ODP.NET connection string from higher precedence to lower is as follows:

  1. ODP.NET ConnectionString centralized configuration provider key

  2. ODP.NET OracleConnection ConnectionString attributes, OracleConnection properties, provider configuration file, and ODP.NET connection parameters, such as ODP/Pooling, ODP/Connection Timeout, and ODP/OciCompartment. All of these have equal precedence.

  3. Oracle common driver attributes in provider configuration file, such as user, password, and connect_descriptor.

Password Connection Attributes

For the OCI and local file providers, passwords, wallet locations, and token locations must be specified must be specified as password JSON objects. Password JSON objects are supported with Azure Vault as well, but not Azure App Configuration.

The Oracle user password has the following format and properties in the configuration providers:

Property Required or Optional Possible Values and Notes

type

Required

  • Base64

  • azurevault

  • ocivault

value

Required

  • Base64 encoded password (base64)

  • Azure Key Vault URI (azurevault)

  • OCID of the secret (ocivault)

authentication

Optional

  • Authentication type

  • Optional parameters

This property has the same possible values and defaults as described in the Azure and OCI Centralized Configuration Provider sections.

versionNumber

Optional

Applicable to OCI Vault only

stage

Optional

Applicable to OCI Vault only

Sample OCI password configuration:

    "password": { 
      "type": "ocivault",
      "value": "<SECRET OCID>",
      "authentication": {
	"method": "OCI_INSTANCE_PRINCIPAL",
	"OCI_PROFILE": "DEFAULT"
      }
    }

Sample Azure password configuration:

    "password": { 
      "type": "azurevault",
      "value": "<AZURE KEY VAULT URI>",
     "authentication": {
        "method": "AZURE_SERVICE_PRINCIPAL",
        "AZURE_CLIENT_ID": "<AZURE CLIENT ID>",
        "AZURE_CLIENT_CERTIFICATE_PATH": "<AZURE CLIENT CERTIFICATE PATH>",
        "AZURE_TENANT_ID": "<AZURE TENANT ID>"
      }
    }

Sample Base64 password configuration

{
    "type": "base64",
    "value": "<BASE64 ENCODED PASSWORD>"
}

ODP.NET ignores plain text passwords in the OCI Object Store or local file centralized configuration provider file for security reasons. The Azure centralized configuration provider accepts plain text passwords in password keys and the connection string since Azure provides secure means to access the app configuration.

While Base64 format is allowed in the password JSON object, it is not considered secure and should only be used in development environments.

If Persist Security Info is false (default) in the ODP.NET connection string, then the Password value is not returned with the connection string value to protect the sensitive password information. In the Azure case, the following sensitive authentication information is also removed from the connection string:

  • AZURE_CLIENT_SECRET

  • AZURE_CLIENT_CERTIFICATE

  • AZURE_CLIENT_CERTIFICATE_PASSWORD

In the OCI case, the following sensitive authentication information is also removed from the connection string:

  • OCI_FINGERPRINT

  • OCI_PRIVATE_KEY

  • OCI_PASS_PHRASE

Automatic Password Refresh

Administrators often set up password expiration policies so that the passwords become invalid at a regular cadence and replaced with new ones. For existing connection pools, this can result in ORA-01017 errors (invalid username/password; logon denied) and having to rebuild the connection pool.

ODP.NET supports the ability to automatically refresh the existing connection pool with the new password. This feature eliminates end users experiencing connection errors and forcing apps to rebuild their pool after each password refresh.

Using this feature requires:

  • ODP.NET connection with pooling enabled

  • An URL connection string stored in a centralized configuration provider

  • One of the following locations to specify the password:

    • “ODP/ConnectionString” key

    • “ODP/Password” key

    • “ODP/ProxyPassword” key

    • “Password” key

Note:

ODP.NET does not currently support password refresh using cloud key vaults.

When ODP.NET encounters an invalid password, it retrieves the latest configuration provider values and checks for the following conditions:

  • The new password(s) must use the same key(s) as the expired password(s).

    • If the original configuration used the “ODP/Password” key, but the refreshed configuration uses the “Password” key, the original connection error will be thrown.

    • If the original configuration used the “ODP/Password” and “ODP/ProxyPassword” keys, but the refreshed configuration only uses the “ODP/Password” key, the original connection error will be thrown.

  • The password value must be different between the original and updated passwords.

    • If both the password and proxy password are used, then at least one of them must be different.

  • All non-password related keys must be identical between the original and updated values.

If any part of this process does not meet the stated conditions, then ODP.NET returns the original connection error.

For end users and administrators, this automated password refresh experience provides a seamless and error free experience.

Connection URL Caching

Since connection information retrieval takes longer retrieving from a cloud resource than local disk, ODP.NET can cache connection information. Cache updates can occur using a polling or change notification model.

Connection URL Polling Updates

The polling model uses the config_time_to_live key. This property sets the duration in seconds for ODP.NET to keep the connection information cached.

By default, config_time_to_live is 86,400 seconds (24 hours). The maximum value is Int64.MaxValue. If it is set to a non-positive value, ODP.NET will never expire the cache.

When the cache expires, ODP.NET retrieves the connection information from the configuration provider again. Once retrieved, ODP.NET refreshes the cache and uses the new configuration for the duration of the config_time_to_live setting.

Note:

If pooling is enabled, then only the password and proxy password can be updated. If pooling is disabled, then all the connection information will be refreshed.

When config_time_to_live expires, the configuration is considered "softly expired". ODP.NET attempts to refresh the cache with every connection request. If a new configuration cannot be retrieved, ODP.NET continues to open new connections with the "softly expired" configuration for up to 30 minutes. After that, the configuration fully expires. No new connections can be made with these old credentials. Existing “softly expired” connections will continue to work until closed or disposed.

Connection URL Change Notification Updates

The change notification model provides real time connection information updates. When data on the cloud is modified, ODP.NET receives the notification almost immediately instead of waiting for config_time_to_live to expire. The relevant cache entries are evicted, and the latest values are retrieved the next time they are needed.

Connection URL change notifications are available for Azure App Configuration and OCI Object Storage only at this time.

Similarly to config_time_to_live, if connection pooling is disabled, then change notification can monitor and update all connection configuration provider settings. If pooling is enabled, only the password and proxy password are monitored and updated.

Developers register their apps for change notification using the options in the connection string URL.

To unregister from change notification, developers call the OracleConnection.UnregisterCloudConfigNotification(OracleConnection con) method. If pooling is enabled, the method unregisters all connections that reside in the same pool as the connection passed into the method.

Change notification updates do not reset the config_time_to_live timer.

Azure App Configuration Setup for Change Notification

ODP.NET Azure-based change notifications require Azure Event Grid and Azure Service Bus. Azure Event Grid watches the Azure App Configuration for changes. When a change is detected, it sends a notification message to Azure Service Bus. Service Bus forwards the message to the ODP.NET application, prompting the application to refresh the values associated with the update notification upon their next use.

Azure Service Bus

Azure Service Bus is a fully managed enterprise message broker with message queues and publish-subscribe topics. ODP.NET change notification can use the Service Bus message entities, Queues and Topics. Queues follow a one-to-one model, where one sender delivers messages to one receiver. Topics follow a one-to-many model, where one sender delivers messages to multiple receivers.

Topics are used when multiple ODP.NET applications register for change notification on the same Azure App Configuration. Otherwise, Queues are sufficient. Azure Service Bus pricing varies depending on the usage and feature set the change notification app required.

Azure Service Bus Setup

  1. On the Azure portal, navigate to the Service Bus page.

  2. Start a new Service Bus resource setup by selecting a pricing tier appropriate for the intended use and budget.

  3. Once the Service Bus resource is created, select it, and go to the Overview tab. Remember the "Host name"

    • It will look like: <Service Bus Name>.servicebus.windows.net

    Next, you will need to set up either Service Bus queue or topic, not both.

Azure Service Bus Queue Setup

  1. On the Azure portal Service Bus page, navigate to the Queues and create a new Queue.

    • The default options can be used or be modified. It will not affect compatibility with ODP.NET change notifications.

  2. Name the Queue and remember the Queue name.

Azure Service Bus Topic Setup

  1. On the Azure portal Service Bus page, navigate to the Topics and create a new Topic.

    • The default options can be used or be modified. It will not affect compatibility with ODP.NET change notifications.

  2. Name the Topic and remember the Topic name.

  3. Navigate to the created topic.

  4. Create a new subscription.

    • The default options can be used with ODP.NET change notifications.

  5. Name the Subscription and remember the Subscription name.

  6. Repeat Steps 4 and 5 if there are multiple ODP.NET Applications that will receive change notifications from the same Azure App Configuration. Each application should use a separate subscription.

Azure Event Grid Setup

To connect the App Configuration to Service Bus, an Event Grid resource is required.

  1. On the Azure portal, search or navigate to the Event Grid page.

  2. Go to the "System topics" tab and create a new Event Grid System Topic.

  3. For "Topic Types", search for and select Microsoft Azure App Configuration

  4. Have the System Topic point to the App Configuration to be watched.

  5. Navigate to your new System Topic and create a new subscription.

  6. For "Event Schema", select "Event Grid Schema" from the drop-down menu.

  7. For "Filter to Event Types", select both "Key-Value Modified" and "Key-Value Deleted".

  8. For "Endpoint Type", select "Service Bus Topic" or “Service Bus Queue” depending on whether you are using a topic or queue.

  9. For the "Endpoint", select the topic or queue created earlier.

    • For the other options, you may use the default values.

ODP.NET Setup for Azure Change Notifications

To enroll ODP.NET in change notifications, the following options in the URL connection string are required for Service Bus queues:

Service Bus Option Description

SERVICE_BUS_HOST

Service Bus host URL

SERVICE_BUS_QUEUE

Service Bus queue name

All options are required values for queues and all are string values.

URL Connection String format for Azure queues

string connStr = "config-azure://myAppConfig?key=test/&SERVICE_BUS_HOST=<Service Bus Host>
&SERVICE_BUS_QUEUE=<Queue Name>";

For Service Bus topics, the following options in the ODP.NET URL connection string are required:

Service Bus Option Description

SERVICE_BUS_HOST

Service Bus host URL

SERVICE_BUS_TOPIC

Service Bus topic name

SERVICE_BUS_SUBSCIPTION

Subscription name within the Service Bus topic

All options are required values for topics and all are string values.

URL Connection String format for Azure topics

string connStr = "config-azure://myAppConfig?key=test/&SERVICE_BUS_HOST=
<Service Bus Host>&SERVICE_BUS_TOPIC=<Topic Name>&SERVICE_BUS_SUBSCRIPTION=
<Subscription Name>";

You have now completed change notification setup for Azure App Configuration.

OCI Object Storage Event Notification for Change Notification

ODP.NET OCI Object Storage-based change notifications require Oracle Cloud Infrastructure Events Service and Notifications service to establish a communication channel that publishes messages using topics and subscriptions. When a change is detected, it sends a notification message to the HTTPS endpoint. The OCI event listener of the ODP.NET application receives the message, prompting the application to refresh the values associated with the update notification upon their next use.

To use OCI Object Storage event notifications, you must configure the OCI Object Storage, OCI Notifications service, event rules, an event listener, and ODP.NET to use OCI event notifications. Let's walk through each of these setup topics.

OCI Object Storage Setup

The first step is to setup the OCI JSON configuration file in OCI Object Storage and then connect to the Oracle database using the file.

  1. Create a bucket in Object Storage and enable "Emit Object Events" for that bucket. Existing buckets can enable "Emit Object Events" in the "Bucket Details" > " Bucket Information" section.

  2. Upload your OCI JSON configuration file to this bucket.

OCI Event Listener Setup

ODP.NET's OCI Event Listener uses HTTPS protocol to receive notification messages, and it has two requirements. First, OCI Notifications service requires a publicly accessible URL with a certificate authority issued certificate. It also must accept POST calls. The OCI API Gateway can be set up to fulfill this requirement through setting up a route. A gateway route is the mapping between a path, one or more methods, and a back-end service.

Second, the host running ODP.NET application must be able to receive the HTTPS message. This usually requires the host to have a port open to the traffic of the notifications service. If your application is running in an OCI Compute Instance and are using OCI API Gateway, you can modify the virtual cloud network's ingress rules security list to permit an open port to OCI API Gateway for the OCI Notifications service. Remember the network path and port you are forwarding into. You will use it in your ODP.NET connection string URL.

OCI Notifications Service

When the JSON configuration file in the OCI Object Storage bucket is updated, OCI Notifications service can emit an event. The event can publish a notification and use the notification to update to the latest configuration version.

OCI Notifications service supports alarms, event rules, and connectors to emit human-readable messages through supported endpoints, including email, SMS, and Slack messages with an HTTPS payload. Additionally, you can automate tasks through custom HTTPS endpoints and OCI Functions, as well as directly publish messages.

The notifications service can be enabled to set up communication channels for publishing messages using topics and subscriptions. A topic is a communication channel for sending messages to subscriptions. When a message is published to a topic, the notifications service sends the message to all the topic's subscriptions. A subscription is a topic endpoint.

Setup OCI Notification Topic and Subscription

A notification topic allows creating a set of notification subscriptions that can be tied together by an event. Here's how to setup a topic and subscription.

  1. Navigate to your OCI tenancy compartment's Notifications service management web page. The page title should be "Topics in <Compartment Name> Compartment".

  2. Click the Create Topic button.

  3. Give the topic an identifiable name. It can be helpful to include bucket/configuration file name and subscription protocols in the name.

  4. Click on the newly created topic name in the list. Now, let's create the subscription.

  5. Click the Create Subscription button.

  6. Select HTTPS (Custom URL) as the communication protocol and add the URL for HTTPS.

  7. Confirm your subscription. For HTTPS, you will receive a payload like the following:

    {"ConfirmationURL":"https://cell1.notification.us-phoenix-1.oci.oraclecloud.com/
20181201/subscriptions/ocid1.onssubscription.oc1.phx.../confirmation?token=MDA...&
protocol=CUSTOM_HTTPS"}

After confirming your subscription, its status will change from "Pending" to "Active". You can test your subscription by publishing a test message.

Setup OCI Notification Event Rules

Rules trigger actions for specified event conditions. Let's create a rule to trigger a notification when the config file is modified.

  1. Navigate to your OCI tenancy compartment's event service rules web page. The page title should be "Rules in <Compartment Name> Compartment".

  2. Click the Create Rule button.

  3. Give the rule an identifiable display name.

  4. Under the rule conditions section, set the following values:

    • Condition: Event Type

    • Service Name: Object Storage

    • Event Type: Object – Update

    These settings indicate whenever there is an Object Storage object update, an action is triggered. Since update can occur for any object in any bucket, let's add more conditions to narrow it down.

  5. Click the Another Condition button to add more conditions.

    1. Create a condition with the following attributes:

      • Condition: Attribute

      • Attribute Name: <Bucket Name or ID>

      • Attribute Value: <Configuration File Bucket Name/OCID>

    2. Create a second condition with the following attributes:

      • Condition: Attribute

      • Attribute Name: <Resource Name or ID>

      • Attribute Value: <Configuration File Name/OCID>

  6. In the Actions section, set the following values:

    • Action Type: Notifications

    • Notifications Compartment: <Compartment Name of the Notification Topic>

    • Topic: <Topic Name>

  7. Click the Create Rule button.

  8. Click the Validate Rule button to test whether the rule works. A notification message should be sent.

    1. In the Example Events section, use a code editor to change the following settings to the matching values you just set for the event rules.

      • <Compartment Name of the Notification Topic>

      • <Resource Name>

      • <Bucket Name>

    2. Click the Check If Example Event Matches Rule button.

    That completes the OCI setup. Let's complete the ODP.NET setup for OCI notifications.

ODP.NET Setup for OCI Notifications

For OCI Object Storage notifications, the ODP.NET connection string URL requires the OCI profile name in the JSON configuration file and the OCI event listener path and port. The connection string URL syntax is:

@config-ociobject:{object-url}[?key=name&option1=value1&option2=value2...]

To enable OCI change notification, the following options in the URL connection string are required:

OCI Event Listener Option Description

Event_Listener_Path

network path listener listens on for notifications

Event_Listener_Port

network port listener listens on for notifications

In our setup, the connection string URL will also include the OCI_PROFILE name that you created earlier for the OCI configuration file. Your ODP.NET connection string will look similar to the following.

Sample Code: ODP.NET OCI change notification connection string URL 

OracleConnection conn = new OracleConnection("@config-ociobject:https://objectstorage
.us-ashburn-1.oraclecloud.com/…/Connection.json?KEY=myconn&authentication=OCI_DEFAULT 
&EVENT_LISTENER_PATH=<HOSTNAME/DIRECTORY>&EVENT_LISTENER_PORT=80")

You have now completed change notification setup for OCI Object Storage.