Connection Configuration Restriction

ODP.NET has many ways to configure and secure connections to the Oracle database. This flexibility provides numerous options for how apps prefer to connect. In some situations, apps may want to restrict other connection methods that it does not use, have not been tested, and to limit possible unauthorized entry when they get deployed.

ODP.NET connection configuration restriction allows developers to globally set restrictions for how an app can connect. For example, a SaaS app can allow using MY_WALLET_LOCATION, WALLET_LOCATION, and TOKEN_LOCATION to set a wallet and token directory location. ODP.NET apps would then be allowed to connect with any of these settings in the Data Source connection string value, which is generally either a connect descriptor, Easy Connect string, or TNS alias.

If any other data source parameter is not on the allowed list, the connection request is rejected, and an error is thrown. The error is an "ORA-50122: The following configuration parameters are not allowed to be set:" followed by a parameter name list used but not allowed.

This feature is available in managed ODP.NET and ODP.NET Core only.

Connection configuration uses an allow list, which details to ODP.NET which connection options are allowed. The app can supply the list as a string or file so that code changes are not necessary.

Connection Configuration Restriction Methods

To use connection configuration restriction, a developer can call the following OracleConfiguration methods to set or unset the restrictions:

EnableConnectionStringAllowedProperties(FileInfo, bool)

This method accepts a file path to an allowed parameter list in a JSON file. The file should be named ODPConnectionStringAllowedProperties.json. Developers may configure whether to enforce allowed parameters on the TNS alias by setting the Boolean argument.
EnableConnectionStringAllowedProperties(string, bool)

This method accepts an allowed parameter list in a JSON string format. Developers may configure whether to enforce allowed parameters on the TNS alias by setting the Boolean argument. If both overloaded methods are set, this JSON string method will override using the JSON file.
DisableConnectionStringAllowedProperties

This method disables using any prior list of allowed parameters. Connections are no longer subject to configuration restrictions.

Data Source Allowed Parameters

The connection configuration JSON format to allow parameters is:

{
  "DataSource" : {
        "<property_name1>" : true/false, 
        "<property_name2>" : true/false, 
        "<property_name3>" : true/false
    }
}

This sample JSON file lists all properties that can be disallowed. Each of the properties set to true is allowed. Properties set to false are restricted. Connections using those restricted properties will be rejected.

All properties not set are false by default.

If there are duplicate property names, then the last property name is used.

The JSON strings are case insensitive.

ODP.NET Connection Configuration JSON Sample

{
     "DataSource" : {
        "CLIENT_ID" : true,
        "COLOCATION_TAG" : true,
        "CONNECT_TIMEOUT" : true,
        "CONNECTION_ID_PREFIX" : true,
        "ENABLE" : true,
        "EXPIRE_TIME" : true,
        "FAILOVER" : true,
        "HOST" : true,
        "HTTPS_PROXY" : true,
        "HTTPS_PROXY_PORT" : true,
        "IGNORE_ANO_ENCRYPTION_FOR_TCPS" : true,
        "INSTANCE_NAME" : true,
        "LOAD_BALANCE" : true,
        "PASSWORD_AUTH " : true,
        "POOL_BOUNDARY" : true,
        "POOL_CONNECTION_CLASS" : true,
        "POOL_NAME" : true,
        "POOL_PURITY" : true,
        "PORT" : true,
        "PROTOCOL" : true,  
        "RECV_BUF_SIZE" : true,
        "RECV_TIMEOUT" : true,
        "RETRY_COUNT" : true,
        "RETRY_DELAY" : true,
        "SDU" : true,
        "SEND_BUF_SIZE" : true,
        "SERVER" : true,
        "SERVICE_NAME" : true,
        "SHARDING_KEY" : true,
        "SHARDING_KEY_ID" : true,
        "SOURCE_ROUTE" : true,
        "SSL_CERTIFICATE_THUMBPRINT" : true,
        "SSL_SERVER_CERT_DN" : true,
        "SSL_SERVER_DN_MATCH" : true,
        "SSL_VERSION" : true,
        "SUPER_SHARDING_KEY" : true,
        "TRANSPORT_CONNECT_TIMEOUT" : true,
        "BACKUP" : true,
        "TYPE" : true,
        "METHOD" : true,
        "TRANSACTION" : true,
        "RETRIES" : true,
        "DELAY" : true,
        "COMMIT_OUTCOME" = true,
        "MY_WALLET_LOCATION" : false,
        "OCI_COMPARTMENT" : false,
        "OCI_DATABASE" : false,
        "OCI_PROFILE " : false,
        "OCI_TENANCY " : false,
        "TUNNEL_SERVICE_NAME" : false,
        "TENANT_ID" : false,
        "TOKEN_AUTH " : false,
        "TOKEN_LOCATION" : false,
        "WALLET_LOCATION" : false
     }
}

Code Sample

using System;
using Oracle.ManagedDataAccess.Client;

class Example
{
  static void Main()
  {
    
   string allowedParameters = “{
   “DataSource” : {
    "CLIENT_ID" : true,
    "COLOCATION_TAG" : true,
    "CONNECT_TIMEOUT" : true,
    "CONNECTION_ID_PREFIX" : true,
    "ENABLE" : true,
    "EXPIRE_TIME" : true,
    "FAILOVER" : true,
    "HOST" : true,
    "HTTPS_PROXY" : true,
    "HTTPS_PROXY_PORT" : true,
    "IGNORE_ANO_ENCRYPTION_FOR_TCPS" : true,
    "INSTANCE_NAME" : true,
    "LOAD_BALANCE" : true,
    "PASSWORD_AUTH " : true,
    "POOL_BOUNDARY" : true,
    "POOL_CONNECTION_CLASS" : true,
    "POOL_NAME" : true,
    "POOL_PURITY" : true,
    "PORT" : true,
    "PROTOCOL" : true,  
    "RECV_BUF_SIZE" : true,
    "RECV_TIMEOUT" : true,
    "RETRY_COUNT" : true,
    "RETRY_DELAY" : true,
    "SDU" : true,
    "SEND_BUF_SIZE" : true,
    "SERVER" : true,
    "SERVICE_NAME" : true,
    "SHARDING_KEY" : true,
    "SHARDING_KEY_ID" : true,
    "SOURCE_ROUTE" : true,
    "SSL_CERTIFICATE_THUMBPRINT" : true,
    "SSL_SERVER_CERT_DN" : true,
    "SSL_SERVER_DN_MATCH" : true,
    "SSL_VERSION" : true,
    "SUPER_SHARDING_KEY" : true,
    "TRANSPORT_CONNECT_TIMEOUT" : true,
    "BACKUP" : true,
    "TYPE" : true,
    "METHOD" : true,
    "TRANSACTION" : true,
    "RETRIES" : true,
    "DELAY" : true,
    "COMMIT_OUTCOME" = true,
    "MY_WALLET_LOCATION" : false,
    "OCI_COMPARTMENT" : false,
    "OCI_DATABASE" : false,
    "OCI_PROFILE " : false,
    "OCI_TENANCY " : false,
    "TUNNEL_SERVICE_NAME" : false,
    "TENANT_ID" : false,
    "TOKEN_AUTH " : false,
    "TOKEN_LOCATION" : false,
    "WALLET_LOCATION" : false
     }
    }”;
    OracleConfiguration.EnableConnectionStringAllowedProperties(allowedParameters, enforceOnAlias: false);
    // Supply the connection string and open a connection
    OracleConnection con = new OracleConnection(<connection string>);
    con.Open();
  }
}

Connection Configuration Usage and Validation

For pooled connections, allowed properties validation occurs only once during each pool's first connection creation. Changing the JSON settings will not change the existing pool settings unless either ClearPool() or ClearAllPools() is invoked. Then, the next connection open will use the new settings.

Newly created pools use the latest updated JSON settings.

In non-pooled connection scenarios, validation executes for each connection request with the latest supplied allowed properties version.