デプロイメントのための一元化された構成プロバイダ

管理対象ODP.NETおよびODP.NET Coreは、一元化されたプロバイダとの間で接続文字列構成値を安全に格納および取得できます。ODP.NET接続構成情報を一元化すると、アプリケーション・デプロイメントでのユーザー資格証明の管理が容易になります。接続文字列にはパスワードなどの機密情報が含まれている可能性があるため、安全な格納が必要です。

この構成プロバイダは、ODP.NETクラウド・デプロイメントおよびオンプレミス・デプロイメントで使用でき、ODP.NETでサポートされる任意のOracleデータベース・バージョンで動作します。次の場所に格納できます。

Microsoft Azure: データベース接続情報をAzure App ConfigurationおよびAzure Key Vaultに格納します。
Oracle Cloud Infrastructure (OCI): データベース接続情報をOCIオブジェクト・ストレージおよびOCI Vaultに格納します。
ローカル・ファイル・システム: データベース接続情報をWebおよびデスクトップ・アプリケーションのローカル・ファイル・システムに格納します。

一元化された構成プロバイダはクラウド・デプロイメントに使用されることが多いため、接続文字列にURLが移入されると、ローカル・ファイル・システム・アクセスはデフォルトで無効になります。ローカル・アクセスを有効にするには、OracleConnection.RemoteConfigurationFilteringをfalseに設定します。

接続文字列URL

接続文字列URLは、従来のODP.NET接続文字列形式とは異なります。Azure、OCIまたはローカル・ファイルの一元化された構成プロバイダにアクセスするために、ODP.NETアプリケーションでは、従来のODP.NET接続文字列のかわりにOracleConnection ConnectionStringプロパティにURLを指定します。このURLには、一元化された構成プロバイダ・タイプ(Azure)と、その構成ストレージの名前、および該当する場合は認証と接続構成パラメータ値が含まれます。User IdやMin Pool Sizeなどの従来の接続文字列値は、一元化された構成プロバイダ自体に格納されます。

しかし、従来のODP.NET接続文字列から一元化された構成プロバイダ・モデルには簡単に移行できます。従来のODP.NET接続文字列の属性および値は、Azure App Configuration、OCIオブジェクト・ストレージまたはローカル・ディレクトリに移動されます。次に、ConnectionStringプロパティは、従来のODP.NET接続文字列ではなく、接続文字列URLに設定されます。

パスワードなどの機密情報は、Azure Key VaultやOCI Vaultなどの安全なストアに格納するか、エンコードできます。一元化された構成プロバイダでは、接続文字列へのプレーン・テキスト・パスワードの格納をサポートしていません。

プーリングを使用している場合は、ODP.NETで接続文字列URLがキャッシュされます。プールの移入後に、一元化されたストレージの構成値を変更しても、アプリケーションが再起動されるまで接続プールのプロパティは変更されません。

プーリングが無効な場合、接続文字列URLはキャッシュされません。接続構成の変更は、アプリケーションを再起動しなくても後続の接続リクエストに対して可能になります。

接続文字列は、config-<プロバイダ・タイプ>の形式で始まります。プロバイダ・タイプは、デプロイメントの場所に応じてazure、ociobjectまたはfileになります。

Azureの一元化された構成プロバイダ

Azure構成プロバイダは、Azure App ConfigurationおよびAzure Key Vaultストアを使用して、Oracleデータベース接続情報を格納できます。Azureの一元化された構成プロバイダの接続文字列URLの構文を次に示します。

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

(必須) Config Name: Azure App Configurationの名前
(オプション) Key: 接続を識別するためのキー接頭辞。:、/、.などのセパレータをキー接頭辞の最後に付けると判読性が向上しますが、技術的な要件ではありません。キーを指定しないと、最上位の接続が暗黙的に使用されます。
(オプション) Label: Azure App Configurationのラベル名
(オプション) OptionsおよびValues: Azure認証および変更通知オプションおよびAzure App Configurationサービスへの接続時に使用する情報。認証情報が指定されていない場合、ODP.NETはAzureのデフォルト資格証明を使用してAzure App Configurationにアクセスします。Azure変更通知の詳細は、接続URLキャッシングのドキュメントを参照してください。

Azure認証オプション

ODP.NETでは、Azure SDK for .NET資格証明クラスを使用して、Azure App ConfigurationおよびKey Vaultサービスに認可および認証を提供します。この依存性を解決するには、Azure認証が必要な場合に、NuGetギャラリで入手可能なOracle.ManagedDataAccess.Azureパッケージをプロジェクトに組み込みます。

開発者は、ODP.NET URL接続文字列でAzure認証オプションを「Authentication」に設定します。このオプションに使用可能な値を次の表に示します。

ノート:

これらのオプションおよび値では、大文字と小文字は区別されません。必要なパラメータを環境変数として設定することもできます

表2-10 Azureの認証方法とその値

認証方法	認証オプションの値	このオプション値の必須パラメータ	このオプション値のオプション・パラメータ
デフォルトのAzure資格証明	`AZURE_DEFAULT`または空の文字列		`AZURE_TENANT_ID` `AZURE_MANAGED_IDENTITY_CLIENT_ID`
クライアント・シークレットが指定されたサービス・プリンシパル^*	`AZURE_SERVICE_PRINCIPAL`	`AZURE_CLIENT_ID` `AZURE_CLIENT_SECRET` `AZURE_TENANT_ID`
クライアント証明書が指定されたサービス・プリンシパル^*	`AZURE_SERVICE_PRINCIPAL`	`AZURE_CLIENT_ID` `AZURE_CLIENT_CERTIFICATE_PATH` `AZURE_TENANT_ID`	`AZURE_CLIENT_CERTIFICATE_PASSWORD`
管理対象アイデンティティ	`AZURE_MANAGED_IDENTITY`	`AZURE_CLIENT_ID` - ユーザーが割り当てた場合のみ必須
対話型ブラウザOAuthトークン・フロー	`AZURE_INTERACTIVE`	`AZURE_CLIENT_ID` `AZURE_REDIRECT_URL`

^*クライアント・シークレットが指定されたAzureサービス・プリンシパルは、クライアント証明書が指定されたAzureサービス・プリンシパルをオーバーライドします。

ODP.NETは、ユーザーが作成したウォレットに格納されているクライアント・シークレットによるAzureサービス・プリンシパルをサポートします。ODP.NETは、最初にODP.NET Azureトークン・クライアント・シークレットまたは接続文字列URL Azureクライアント・シークレットの値を使用しようとします。どちらも値が含まれていない場合、ODP.NETはウォレットに格納されているクライアント・シークレットを使用します。ウォレット・パスは、azure_credentialsプロパティで指定されます。このプロパティは、TNS記述子またはsqlnet.oraで設定できます。

このプロパティを指定すると、ODP.NETは、oracle.security.azure.credential.{CLIENT_ID}形式の構成済ウォレット・エントリに対応するシークレットを使用してAzureでの認証を試みます。ここで、{CLIENT_ID}はAzure AD登録済クライアント識別子です。

AzureTokenAuthenticationクラスを使用してクライアント・シークレット・プロパティが指定されている場合、azure_credentialsプロパティは無視されます。

ODP.NET接続文字列URLには、次のような追加の接続構成オプションがあります。

AZURE_MAX_RETRIES
AZURE_RETRY_TIMEOUT
AZURE_MANAGED_IDENTITY_CLIENT_ID - DefaultAzureCredentialを使用していて、ユーザーが割り当てられている場合にのみ使用できます。
AZURE_TENANT_ID
AZURE_AUTHORITY_HOST

次のコード・サンプルは、MyConfigというAzure App Configurationストア名を指定するODP.NET接続文字列URLを示しています。MyConfigの接続の接頭辞キーはMyConnectionで、Azure App Configurationのラベル名はproductionです。コード・サンプルでは、AzureマネージドID認証を使用して接続し、そのID値を指定します。コード・サンプルでは、次にOracleConnectionコンストラクタを使用して接続文字列URLを設定します。ODP.NETは、接続をオープンするときにAzure App Configurationストアから接続文字列を暗黙的に取得します。

       {
        // 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();
 	}

OCIの一元化された構成プロバイダ

Oracle Cloud Infrastructure構成プロバイダは、OCIオブジェクト・ストレージおよびOCI Vaultを使用して、データベース接続情報をJSON構成ファイルに格納します。接続文字列URLの構文を次に示します。

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

(必須) Object-URL: OCIオブジェクト・ストレージのオブジェクトURLパス。この値は、OCI Webコンソールの「オブジェクト・ストレージ」/「バケット」/「オブジェクト」メニューの「オブジェクトの詳細」で取得できます。オブジェクトURLの例を2つ示します:

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

および

https://objectstorage.us-ashburn-1.orclecloud.com/n/namespace/b/bucket1/o/odp.json。
(オプション) Key: 接続キー名ID。キーを指定しないと、最上位の接続が暗黙的に使用されます。
(オプション) Options: OCI Object Storageへの接続時に使用するOracle Cloud認証および変更通知オプションおよび情報。認証が指定されていない場合、プロバイダはOCI APIキーベースの認証を使用してOCIオブジェクト・ストレージにアクセスします。Oracle Cloud変更通知の詳細は、接続URLキャッシングのドキュメントを参照してください。

OCI認証オプション

ODP.NET OCI認証では、OCIオブジェクト・ストレージおよびVaultサービスへの認可および認証をOCI SDKに依存しています。この依存性を解決するには、OCI認証が必要な場合に、NuGetギャラリで入手可能なOracle.ManagedDataAccess.Ociパッケージをプロジェクトに組み込みます。

認証パラメータは、接続文字列URLを介して提供されます。

開発者は、ODP.NET URL接続文字列でOCI認証オプションをAuthenticationに設定します。このオプションに使用可能な値を次の表に示します。

ノート:

これらのオプションおよび値では、大文字と小文字は区別されません。必要なパラメータを環境変数として設定することもできます

表2-11 OCIの認証方法とその値

認証方法認証オプションの値オプションの構成オプションのパラメータ

認証方法	認証オプションの値	オプションの構成	オプションのパラメータ
APIキーベース認証	`OCI_DEFAULT`または空の文字列	`(~/.oci/config)`、 `(~/.oraclebmc/config)`または環境変数`OCI_CONFIG_FILE`	`OCI_PROFILE` `OCI_TENANCY` `OCI_USER` `OCI_FINGERPRINT` `OCI_KEY_FILE` `OCI_PASS_PHRASE`
インスタンス・プリンシパル認証	`OCI_INSTANCE_PRINCIPAL`
リソース・プリンシパル認証	`OCI_RESOURCE_PRINCIPAL`

APIキーベース認証

OCI_DEFAULTまたは空の文字列

(~/.oci/config)、

(~/.oraclebmc/config)または

環境変数OCI_CONFIG_FILE

OCI_PROFILE

OCI_TENANCY

OCI_USER

OCI_FINGERPRINT

OCI_KEY_FILE

OCI_PASS_PHRASE

インスタンス・プリンシパル認証

OCI_INSTANCE_PRINCIPAL

リソース・プリンシパル認証

OCI_RESOURCE_PRINCIPAL

次のコード・サンプルは、OCIオブジェクト・ストアのオブジェクトURLを指定するODP.NET接続文字列URLを示しています。接続キー名IDはMyConnectionです。コード・サンプルでは、OCIのAPIキーベース認証OCI_DEFAULTおよびオプションのパラメータOCI_PROFILEを使用して、接続プロファイル構成を指定します。コード・サンプルでは、次にOracleConnection ConnectionStringプロパティを使用して接続文字列URLを設定します。ODP.NETは、接続をオープンするときにOCIオブジェクト・ストレージ・サービスに格納されているJSON構成ファイルから接続文字列を取得します。

      {
        //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();
      }

ローカル・ファイルの一元化された構成プロバイダ

ファイル構成プロバイダは、Oracleデータベース接続情報をローカル・ファイル・システムのJSON構成ファイルに格納します。ODP.NETファイル接続文字列URLの構文を次に示します。

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

(必須) File Path: JSON構成ファイルのパスおよび名前。絶対または相対パスにできます。相対パスの場合、ODP.NETはベース・パスとしてTNS_ADMIN値を使用します。
(オプション) Key: 接続キー名ID。キーを指定しないと、最上位の接続が暗黙的に使用されます。
(オプション) tns_admin: JSON構成ファイルを検索するファイル名のベース・パスまたは接頭辞。

次のコード・サンプルは、ローカル・ファイルodpconfig.jsonおよびディレクトリの場所を指定するODP.NET接続文字列URLを示しています。接続キー名IDはMyConnectionです。このコード・サンプルでは、次にOracleConnectionコンストラクタを使用して接続文字列URLを設定します。ODP.NETは、接続をオープンするときにローカルJSON構成ファイルから接続文字列を取得します。

      {
        //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();
      }

ファイル構成プロバイダは、NuGetギャラリで入手可能なOracle.ManagedDataAccess.ConfigFileパッケージに依存します。

JSON構成ファイルの検索順序

ODP.NETでは、JSON構成ファイルを見つけるためにローカル・ファイルの一元化された構成プロバイダ接続文字列URLに設定された絶対ディレクトリおよびファイル名の値(c:/configs/myconfig.json)を使用できます。ファイル名を持つ相対ディレクトリを使用することもできます。この場合、JSONファイルを検索するために、次の順序で設定に相対ディレクトリとファイルを追加します。

現行作業ディレクトリ
OracleConnection.TnsAdminプロパティで設定されたディレクトリ
Tns_Admin接続文字列属性用に設定されたディレクトリ
構成プロバイダURLのtns_admin属性に設定されたディレクトリ
OracleConfiguration.TnsAdminプロパティで設定されたディレクトリ
.NET構成ファイルのTNS_ADMINディレクトリ設定 -- 管理対象ODP.NETのみ
Windows環境変数またはコンテナ環境変数のTNS_ADMINディレクトリ設定
Windowsレジストリ・キーHKLM\SOFTWARE\Oracle\ODP.NET.Managed\<version>\TNS_ADMINで設定されたディレクトリ -- 管理対象ODP.NETのみ

ノート:

32ビット・アプリケーションはレジストリ・キーHKLM\SOFTWARE\Wow6432Node\Oracle\ODP.NET.Managed\<version>\TNS_ADMINを使用します
%ORACLE_HOME%\network\adminディレクトリ

ボールト・プロバイダ

データベース・パスワード、プロキシ・パスワード、ウォレット、JSON構成は、機密性の高いデータベース情報であり、Azure Key VaultまたはOCI Vaultサービスにシークレットとして格納できます。これらのボールト・プロバイダは、それぞれOracle.ManagedDataAccess.AzureおよびOracle.ManagedDataAccess.Oci NuGetパッケージに含まれています。

ODP.NETは、事前定義されたURLであるシークレットURLを使用して、ボールトからこの機密情報にアクセスするためのセキュアな方法を提供します。Azure Key VaultまたはOCI Vaultサービスのいずれかでユーザーが指定した情報にアクセスするには、ODP.NETのシークレットURLにvault-azureまたはvault-OCIの接頭辞を付ける必要があります。ユーザー指定のURLは、次のODP.NET定義構文に準拠している必要があります。

ODP.NETボールト・プロバイダでは、クラウド・ボールト内のシングル・サインオン(.sso)・ウォレットおよびPKCS #12 (.p12)ウォレットがサポートされています。

Azure Key Vault

すべてのODP.NETシークレットは、Azure Vaultシークレットとして格納できます。Azure Key Vaultシークレットにアクセスするには、次のURL構文を使用します:

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

アプリケーションでは、URLに次の情報を指定する必要があります:

(必須)シークレット識別子: Azureポータルから取得されたAzureシークレット識別子
(オプション)キー: 接続識別子。キーを指定しないと、それがトップ・レベルの接続になります。このオプションは、JSON構成ファイルがAzure Key Vaultにある場合にのみ使用されます。
(オプション)認証オプション: Azure Key Vault認証接続情報。認証情報が指定されていない場合、ODP.NETはAzureのデフォルト資格証明を使用してAzure Key Vaultサービスのシークレットにアクセスします。認証オプションは、Azure認証オプションと同じです。

OCI Vault

すべてのODP.NETシークレットは、OCI Vaultシークレットとして格納できます。OCI Vaultシークレットにアクセスするには、次のURL構文を使用します:

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

アプリケーションでは、URLに次の情報を指定する必要があります:

(必須)シークレットOCID: OCIポータルから取得したOCIシークレット識別子(OCID)
(オプション) VersionNumber: OCIシークレット・バージョン。バージョンを指定しない場合、最新のシークレット・バージョンがデフォルトで取得されます。
(オプション)ステージ: シークレットのローテーション・ステージ。ステージを指定しない場合、シークレットの現在のステージがデフォルトで取得されます。
(オプション)キー: 接続識別子。キーを指定しないと、それがトップ・レベルの接続になります。このオプションは、JSON構成ファイルがOCI Vaultにある場合にのみ使用されます。
(オプション)オプション: OCI Vault認証接続情報。認証情報が指定されていない場合、ODP.NETはAPIキーベース認証を使用してOCI Vaultサービスのシークレットにアクセスします。認証オプションは、OCI認証オプションと同じです。

ボールト接続文字列URL

同様に、一元化された構成プロバイダの場合、ボールトURLは、コンストラクタ接続文字列プロパティまたはOracleConnection ConnectionStringプロパティを介してOracleConnectionクラスに接続文字列として渡すことができます。

Azure Vaultの例を次に示します:

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

Vaultには、標準接続文字列またはJSON構成文字列を含めることができます。

標準接続文字列の例:

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

JSON構成の例:

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

ノート:

接続/JSON構成文字列は、クリア・テキストとしてアップロードする必要があります。

ボールト・パスワード

開発者は、接続文字列全体を保存するかわりに、パスワードまたはプロキシ・パスワードのみをクラウド・ボールトに格納できます。これを行うために、アプリケーションでは、パスワードまたはプロキシ・パスワード接続文字列属性値にボールトURL値を指定します。

たとえば、Azure VaultのODP.NET接続文字列は次のようになります:

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

ボールトのウォレットとトークン

アプリケーションは、ODP.NETウォレットおよびトークンの場所のプロパティにボールトURLを指定することで、ウォレットおよびトークンをクラウド・ボールト・サービスに安全に格納できます。アプリケーションは、ウォレットまたはトークン・ファイル・データをクラウド・ボールトにbase64文字列として格納する必要があります。

ノート:

OCI Vaultの場合、ウォレットおよびトークンはbase64文字列に変換する必要がありますが、プレーン・テキスト・タイプ・シークレットとしてOCI Vaultにアップロードする必要があります。

ODP.NET接続文字列では、Wallet_LocationおよびToken_Locationプロパティをそれぞれ使用してウォレットおよびトークンを格納できます。たとえば、Azure Vaultに格納されているウォレットにアクセスするためのODP.NET接続文字列は次のようになります:

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

OracleConnection WalletLocationおよびTokenLocationプロパティは、ボールトURLまたはファイル・パスの場所に設定できます。これらのOracleConnectionプロパティは、接続文字列のウォレットおよびトークンの場所属性よりも優先されます。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...";

ノート:

クラウド・ウォレットの場所では、セキュアな外部パスワード・ストアはサポートされていません。

ODP.NETでは、Microsoft Entra ID専用アプリケーションに対してはMicrosoft IDプラットフォーム・トークンv1.0、コンシューマ・アカウントをサポートするアプリケーションに対してはv2.0をサポートしています。ODP.NET 23.5以上では、v2.0トークンのロール(roles)およびユーザー・プリンシパル名(UPN)クレームをチェックして、少なくとも1つが存在することを確認します。両方の要求がない場合、プロバイダはエラーを報告します。

プロバイダ構成

プロバイダ構成キー

ローカル・ファイル構成プロバイダとOCIの一元化された構成プロバイダは、どちらもJSON形式を使用して接続情報を指定します。両方とも同じJSON構成を使用します。

ODP.NETは、プロバイダ構成キーの値を使用して、Oracleデータベースへの接続文字列を作成します。通常、構成キーは既存のODP.NET接続文字列およびOracle接続プロパティにマップされます。一部のキーは、すべてのOracleデータ・アクセス・ドライバに対して汎用です。該当するプロパティは次のとおりです。

user: データベース・ユーザー/スキーマ名
password: データベース・パスワード
connect_descriptor: ODP.NETデータ・ソース
config_time_to_live: キャッシュされた接続情報の保存時間(秒)

Azure App Configurationでは、ODP.NETのみに使用する意図を示すために、ODP.NET固有の構成キーの先頭にはODP/が付きます。たとえば、MyConnection/ODP/Poolingキーは、ODP.NETのプーリング接続文字列属性を指定します。

OCIおよびローカル・ファイル・プロバイダの場合、ODP.NET固有の構成キーはJSON構成で特別に識別されます。これらのキーは、"ODP"キーを使用します。たとえば、次の例のMyConnectionプロパティの"ODP": {"Max Pool Size": "500", "Pooling": true }は、Max Pool SizeおよびPooling接続文字列属性を指定します。

{ 
                "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= .......)"
}

通常、ODP.NET構成キーでは、大/小文字は区別されません。ただし、Azure App ConfigurationのODP/セクション、およびOCI構成とローカル構成のODPセクションでは、キーとその値を含めて、大/小文字が区別されます。

接続の属性

構成プロバイダでは、ConnectionStringキーはODP.NET固有のキーです。これにより、完全または部分的なODP.NET接続文字列を定義できます。ODP.NETアプリケーションはOracleConnection ConnectionStringプロパティを引き続き使用できるため、構成プロバイダのConnectionStringキーを使用する必要はありません。

OracleConnection ConnectionStringで定義されているすべての接続文字列属性は、次の属性を除き、従来の接続文字列で使用されるものと同様にサポートされます:

Tns_Admin: サポートされていません。

ODP.NETでは、プロバイダ構成で次のOracleConnectionプロパティもサポートしています。

AutoProxy
BindByName
CommandTimeout
ChunkMigrationConnectionTimeout
ConnectionIdPrefix
DatabaseEditionName
DrcpConnectionClass
FetchSize
HttpsProxy
HttpsProxyPort
MaxStatementCacheSize
OciCompartment
OciDatabase
OciIamUrl
OciTenancy
PasswordAuthentication
Pipelining
PoolName
ServiceRelocationConnectionTimeout
SSLVersion
SSLServerCertDN
SSLServerDNMatch
SuppressGetDecimalInvalidCastException
SqlNetEncryptionClient
SqlNetEncryptionTypesClient
SqlNetCryptoChecksumClient
SqlNetCryptoChecksumTypesClient
TokenAuthentication
UseClientInitiatedCQN
UseSNI
Wallet_Location: ローカル・システム・ファイルに格納されたWalletはサポートされていません。.p12ファイルと.ssoファイルでは、Azure App Configuration、Azure VaultまたはOCI VaultにBase64文字列として格納されているウォレットがサポートされています。JSON構成の場合、Wallet_Locationは、Password JSONオブジェクトを使用して指定する必要があります。
Wallet_Password: 暗号化されたPKCS #12ウォレットの場合。
Token_Location: ローカル・システム・ファイルに格納されているトークンはサポートされていません。Azure App Configuration、Azure VaultまたはOCI VaultにBase64文字列として格納されているトークンがサポートされています。JSON構成の場合、Password JSONオブジェクトを使用してToken_Locationを指定する必要があります。

ODP JSONプロパティまたはODP/ Azure App Configurationセクションで、サポートされていない属性がプロバイダ構成に指定されている場合、ODP.NETは例外をスローします。

次の例は、様々な構成キー・タイプを使用したsales_app、hr_appおよびsh_appの3つの接続を示しています。

{
  "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"
      }
    }
  }
}

構成プロバイダでは、ConnectionStringキーは、同じ接頭辞キーを持つconnect_descriptorなどの他のキーよりも優先されます。したがって、User Id属性がConnectionStringに含まれていない場合、ODP.NETでは、同じ接頭辞キーを持つuserキーが使用されます。Data Source属性がConnectionStringに含まれていない場合は、同じ接頭辞キーを持つconnect_descriptorキーの値が使用されます。同様の動作がすべてのConnectionString属性に適用されます。

ODP.NET接続文字列を作成する際の優先順位(高い優先順位から低い優先順位)は、次のとおりです。

ODP.NET ConnectionStringキー(一元化された構成プロバイダ・キー)
ODP.NET OracleConnection ConnectionString属性、OracleConnectionプロパティ、プロバイダ構成ファイルおよびODP.NET接続パラメータ(ODP/Pooling、ODP/Connection Timeout、ODP/OciCompartmentなど)。これらはすべて同じ優先順位です。
user、password、connect_descriptorなど、プロバイダ構成ファイル内のOracle共通のドライバ属性。

パスワード接続の属性

OCIおよびローカル・ファイル・プロバイダの場合、パスワード、ウォレットの場所およびトークンの場所をパスワードJSONオブジェクトとして指定する必要があります。パスワードJSONオブジェクトはAzure Vaultでもサポートされますが、Azure App Configurationではサポートされません。

構成プロバイダでは、Oracleユーザー・パスワードに次の形式およびプロパティがあります。

プロパティ	必須/オプション	使用可能な値とノート
`type`	必須	`Base64` `azurevault` `ocivault`
`value`	必須	Base64エンコード・パスワード(`base64`) Azure Key Vault URI (`azurevault`) シークレットのOCID (`ocivault`)
`authentication`	オプション	認証タイプオプションのパラメータこのプロパティに使用可能な値およびデフォルトは、AzureおよびOCIの一元化された構成プロバイダの項で説明したものと同じです。
`versionNumber`	オプション	OCI Vaultにのみ適用可能
`stage`	オプション	OCI Vaultにのみ適用可能

OCIパスワード構成のサンプル:

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

Azureパスワード構成のサンプル:

    "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>"
      }
    }

Base64パスワード構成のサンプル

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

ODP.NETでは、セキュリティ上の理由から、OCIオブジェクト・ストアまたはローカル・ファイルの一元化された構成プロバイダ・ファイルのプレーン・テキスト・パスワードを無視します。Azureではアプリケーション構成にアクセスするための安全な手段が提供されるため、Azureの一元化された構成プロバイダは、パスワード・キーおよび接続文字列のプレーン・テキスト・パスワードを受け入れます。

Base64形式はパスワードJSONオブジェクトで使用できますが、セキュアとはみなされず、開発環境でのみ使用する必要があります。

ODP.NET接続文字列のPersist Security Infoがfalse (デフォルト)の場合は、機密パスワード情報を保護するために、接続文字列値にはPassword値は含まれません。Azureの場合、次の機密認証情報も接続文字列から削除されます。

AZURE_CLIENT_SECRET
AZURE_CLIENT_CERTIFICATE
AZURE_CLIENT_CERTIFICATE_PASSWORD

OCIの場合、次の機密認証情報も接続文字列から削除されます。

OCI_FINGERPRINT
OCI_PRIVATE_KEY
OCI_PASS_PHRASE

パスワードの自動更新

管理者は多くの場合、パスワードの有効期限ポリシーを設定して、パスワードが定期的に無効になり、新しいパスワードに置き換えられるようにします。既存の接続プールの場合は、これにより、ORA-01017エラー(無効なユーザー名/パスワード、ログオン拒否)が発生し、接続プールを再構築する必要があります。

ODP.NETでは、既存の接続プールを新しいパスワードで自動的にリフレッシュする機能がサポートされています。この機能により、エンド・ユーザー側で接続エラーが発生し、パスワードがリフレッシュされるたびにアプリケーションがプールの再構築を強制されることがなくなります。

この機能を使用するには、次のものが必要です:

プーリングが有効なODP.NET接続
一元化された構成プロバイダに格納されているURL接続文字列
パスワードを指定するための、次のいずれかの場所:
- "ODP/ConnectionString"キー
- "ODP/Password"キー
- "ODP/ProxyPassword"キー
- "Password"キー

ノート:

ODP.NETでは、現在、クラウド・キー・ボールトを使用したパスワード・リフレッシュはサポートされていません。

ODP.NETは、無効なパスワードを検出すると、最新の構成プロバイダ値を取得し、次の条件をチェックします:

新しいパスワードは、期限切れのパスワードと同じキーを使用する必要があります。
- 元の構成で"ODP/Password"キーが使用されていても、リフレッシュされた構成で"Password"キーが使用されている場合は、元の接続エラーがスローされます。
- 元の構成で"ODP/Password"キーと"ODP/ProxyPassword"キーが使用されていても、リフレッシュされた構成で"ODP/Password"キーのみが使用されている場合は、元の接続エラーがスローされます。
パスワードの値は、元のパスワードと更新されたパスワードの間で異なる必要があります。
- パスワードとプロキシ・パスワードの両方を使用する場合、少なくとも1つのパスワードは異なる必要があります。
パスワード以外の関連するキーはすべて、元の値と更新された値の間で同一である必要があります。

このプロセスのいずれかの部分が指定された条件を満たさない場合、ODP.NETは元の接続エラーを返します。

エンド・ユーザーと管理者にとって、この自動化されたパスワード・リフレッシュにより、シームレスでエラーのないエクスペリエンスが提供されます。

接続URLキャッシング

接続情報の取得は、ローカル・ディスクよりもクラウド・リソースからの取得に時間がかかるため、ODP.NETは接続情報をキャッシュできます。キャッシュの更新は、ポーリングまたは変更通知モデルを使用して行うことができます。

接続URLポーリングの更新

ポーリング・モデルでは、config_time_to_liveキーが使用されます。このプロパティは、ODP.NETが接続情報をキャッシュしておく期間を秒単位で設定します。

デフォルトでは、config_time_to_liveは86,400秒(24時間)です。最大値はInt64.MaxValueです。正でない値に設定されている場合、ODP.NETはキャッシュを期限切れにしません。

キャッシュが期限切れになると、ODP.NETは構成プロバイダから接続情報を再度取得します。取得後、ODP.NETはキャッシュをリフレッシュし、config_time_to_live設定の間、新しい構成を使用します。

ノート:

プーリングが有効になっている場合は、パスワードおよびプロキシ・パスワードのみを更新できます。プーリングが無効になっている場合、すべての接続情報がリフレッシュされます。

config_time_to_liveが期限切れになると、構成は"ソフト期限切れ"とみなされます。ODP.NETは、すべての接続リクエストでキャッシュのリフレッシュを試みます。新しい構成を取得できない場合、ODP.NETは"ソフト期限切れ"構成で新しい接続を最大30分間オープンし続けます。その後、構成は完全に期限切れになります。これらの古い資格証明を使用して新しい接続を行うことはできません。既存の"ソフト期限切れ"接続は、クローズまたは廃棄されるまで引き続き機能します。

接続URL変更通知の更新

変更通知モデルは、リアルタイムの接続情報更新を提供します。クラウド上のデータが変更されると、ODP.NETは、config_time_to_liveの期限切れを待機するのではなく、ほぼすぐに通知を受信します。関連するキャッシュ・エントリは削除され、最新の値は次回必要なときに取得されます。

接続URL変更通知は、現時点ではAzure App ConfigurationおよびOCIオブジェクト・ストレージでのみ使用できます。

config_time_to_liveと同様に、接続プーリングが無効になっている場合、変更通知はすべての接続構成プロバイダ設定をモニターおよび更新できます。プーリングが有効になっている場合、パスワードおよびプロキシ・パスワードのみが監視および更新されます。

開発者は、接続文字列URLのオプションを使用して、変更通知用にアプリケーションを登録します。

変更通知から登録を解除するために、開発者はOracleConnection.UnregisterCloudConfigNotification(OracleConnection con)メソッドをコールします。プーリングが有効な場合、メソッドはメソッドに渡される接続と同じプールにあるすべての接続を登録解除します。

変更通知の更新では、config_time_to_liveタイマーはリセットされません。

変更通知のAzure App Configuration設定

ODP.NET Azureベースの変更通知には、Azure Event GridおよびAzure Service Busが必要です。Azure Event Gridは、Azure App Configurationの変更を監視します。変更が検出されると、Azure Service Busに通知メッセージが送信されます。Service Busは、メッセージをODP.NETアプリケーションに転送し、次回の使用時に更新通知に関連付けられた値をリフレッシュするようアプリケーションに要求します。

Azure Service Bus

Azure Service Busは、メッセージ・キューとパブリッシュ/サブスクライブ・トピックを含む完全管理型のエンタープライズ・メッセージ・ブローカです。ODP.NET変更通知では、Service Busメッセージ・エンティティ、キューおよびトピックを使用できます。キューは、1つの送信者が1つの受信者にメッセージを配信する1対1モデルに従います。トピックは、1つの送信者が複数の受信者にメッセージを配信する1対多モデルに従います。

トピックは、複数のODP.NETアプリケーションが、同じAzure App Configurationの変更通知に登録する場合に使用されます。それ以外の場合は、キューで十分です。Azure Service Busの価格は、必要な変更通知アプリケーションの使用状況および機能セットによって異なります。

Azure Service Busの設定

Azureポータルで、Service Busのページに移動します。
目的の使用および予算に適した価格設定階層を選択して、新しいService Busリソース設定を開始します。
Service Busリソースが作成されたら、そのリソースを選択して「Overview」タブに移動します。"ホスト名"を記憶します
- 次のようになります: <Service Bus Name>.servicebus.windows.net
次に、Service Busキューまたはトピックのいずれか(両方ではなく)を設定する必要があります。

Azure Service Busキューの設定

Azure portalのService Busページで、「Queues」に移動し、新しいキューを作成します。
- デフォルト・オプションを使用または変更できます。ODP.NET変更通知との互換性には影響しません。
キューに名前を付け、キュー名を記憶します。

Azure Service Busトピックの設定

Azure portalのService Busページで、「Topics」に移動し、新しいトピックを作成します。
- デフォルト・オプションを使用または変更できます。ODP.NET変更通知との互換性には影響しません。
トピックに名前を付け、トピック名を覚えておきます。
作成したトピックにナビゲートします。
新規サブスクリプションを作成します。
- デフォルト・オプションは、ODP.NET変更通知で使用できます。
サブスクリプションに名前を付け、サブスクリプション名を記憶します。
同じAzure App Configurationから変更通知を受信する複数のODP.NETアプリケーションがある場合は、ステップ4と5を繰り返します。アプリケーションごとに個別のサブスクリプションを使用する必要があります。

Azure Event Gridの設定

App ConfigurationをService Busに接続するには、Event Gridリソースが必要です。

Azure portalで、Event Gridのページを検索するか、ナビゲートします。
「System topics」タブに移動し、新しいEvent Gridシステム・トピックを作成します。
「Topic Types」で、「Microsoft Azure App Configuration」を検索して選択します。
監視するApp Configurationをシステム・トピックが指すようにします。
新規システム・トピックにナビゲートし、新規サブスクリプションを作成します。
「Event Schema」で、ドロップダウン・メニューから「Event Grid Schema」を選択します。
「Filter to Event Types」で、「Key-Value Modified」と「Key-Value Deleted」の両方を選択します。
「Endpoint Type」で、トピックまたはキューのどちらを使用しているかに応じて、「Service Bus Topic」または「Service Bus Queue」を選択します。
「Endpoint」で、前に作成したトピックまたはキューを選択します。
- その他のオプションには、デフォルト値を使用できます。

Azure変更通知のODP.NET設定

変更通知にODP.NETを登録するには、Service BusキューにURL接続文字列の次のオプションが必要です。

Service Busオプション	説明
`SERVICE_BUS_HOST`	Service BusホストURL
`SERVICE_BUS_QUEUE`	Service Busキュー名

すべてのオプションはキューの必須値であり、すべて文字列値です。

AzureキューのURL接続文字列形式

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

Service Busのトピックの場合、ODP.NET URL接続文字列の次のオプションが必要です:

Service Busオプション	説明
`SERVICE_BUS_HOST`	Service BusホストURL
`SERVICE_BUS_TOPIC`	Service Busトピック名
`SERVICE_BUS_SUBSCIPTION`	Service Busトピック内のサブスクリプション名

すべてのオプションはトピックの必須値であり、すべて文字列値です。

AzureトピックのURL接続文字列形式

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

これで、Azure App Configurationの変更通知設定が完了しました。

変更通知のOCIオブジェクト・ストレージ・イベント通知

ODP.NETのOCIオブジェクト・ストレージベースの変更通知では、Oracle Cloud Infrastructureのイベント・サービスおよび通知サービスで、トピックおよびサブスクリプションを使用してメッセージを公開する通信チャネルを確立する必要があります。変更が検出されると、HTTPSエンドポイントに通知メッセージが送信されます。ODP.NETアプリケーションのOCIイベント・リスナーがメッセージを受信し、次回の使用時に更新通知に関連付けられた値をリフレッシュするようアプリケーションに要求します。

OCIオブジェクト・ストレージのイベント通知を使用するには、OCIイベント通知を使用するようにOCIオブジェクト・ストレージ、OCI通知サービス、イベント・ルール、イベント・リスナーおよびODP.NETを構成する必要があります。これらの各設定トピックについて説明します。

OCIオブジェクト・ストレージの設定

最初のステップは、OCIオブジェクト・ストレージでOCI JSON構成ファイルを設定し、そのファイルを使用してOracleデータベースに接続することです。

オブジェクト・ストレージにバケットを作成し、そのバケットのオブジェクト・イベントの出力を有効にします。既存のバケットでは、バケット詳細>バケット情報セクションでオブジェクト・イベントの出力を有効にできます。
OCI JSON構成ファイルをこのバケットにアップロードします。

OCIイベント・リスナー設定

ODP.NETのOCIイベント・リスナーは、HTTPSプロトコルを使用して通知メッセージを受信します。これには2つの要件があります。まず、OCI通知サービスには、認証局が発行した証明書を含むパブリックにアクセス可能なURLが必要です。また、POSTコールを受け入れる必要があります。OCI APIゲートウェイは、ルートを設定することで、この要件を満たすように設定できます。ゲートウェイ・ルートは、パス、1つ以上のメソッド、およびバックエンド・サービス間のマッピングです。

次に、ODP.NETアプリケーションを実行しているホストがHTTPSメッセージを受信できる必要があります。通常、このためには、ホストが通知サービスのトラフィックに対してポートを開いている必要があります。アプリケーションがOCIコンピュート・インスタンスで実行されていて、OCI API Gatewayを使用している場合は、仮想クラウド・ネットワークのイングレス・ルール・セキュリティ・リストを変更して、OCI通知サービスのOCI API Gatewayへのオープン・ポートを許可できます。転送先のネットワーク・パスとポートを覚えておいてください。これは、ODP.NET接続文字列のURLで使用します。

OCI通知サービス

OCIオブジェクト・ストレージ・バケットのJSON構成ファイルが更新されると、OCI通知サービスはイベントを発行できます。イベントは通知を発行し、その通知を使用して最新の構成バージョンに更新できます。

OCI通知サービスは、アラーム、イベント・ルールおよびコネクタをサポートし、HTTPSペイロードを含む電子メール、SMS、Slackメッセージなど、サポートされているエンドポイントを通じて、人間が読めるメッセージを発信します。また、カスタムHTTPSエンドポイントやOCI関数を通じてタスクを自動化し、メッセージを直接公開することもできます。

通知サービスは、トピックおよびサブスクリプションを使用するメッセージをパブリッシュするための通信チャネルを設定するために有効にすることができます。トピックは、サブスクリプションにメッセージを送信するための通信チャネルです。メッセージがトピックにパブリッシュされると、通知サービスによってそのメッセージがすべてのトピックのサブスクリプションに送信されます。サブスクリプションはトピック・エンドポイントです。

OCI通知トピックおよびサブスクリプションの設定

通知トピックを使用すると、イベントで結び付けることができる一連の通知サブスクリプションを作成できます。トピックとサブスクリプションの設定方法を次に示します。

OCIテナンシ・コンパートメントの通知サービス管理Webページに移動します。ページ・タイトルは、「<コンパートメント名>コンパートメントのトピック」である必要があります。
「トピック」ボタンをクリックします。
トピックに識別可能な名前を付けます。名前にバケット/構成ファイル名およびサブスクリプション・プロトコルを含めると役立ちます。
リストで新しく作成したトピック名をクリックします。サブスクリプションを作成しましょう。
サブスクリプションの作成ボタンをクリックします。
通信プロトコルとしてHTTPS (カスタムURL)」を選択し、HTTPSのURLを追加します。

サブスクリプションを確認します。HTTPSの場合、次のようなペイロードを受け取ります:

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

サブスクリプションを確認すると、ステータスは「保留中」から「アクティブ」に変わります。テスト・メッセージを発行してサブスクリプションをテストできます。

OCI通知イベント・ルールの設定

ルールによって、指定されたイベント条件のアクションがトリガーされます。構成ファイルの変更時に通知をトリガーするルールを作成します。

OCIテナンシ・コンパートメントのイベント・サービス・ルールWebページに移動します。ページ・タイトルは「<コンパートメント名>コンパートメントのルール」である必要があります。
「ルールの作成」ボタンをクリックします。
ルールに識別可能な表示名を指定します。
ルール条件セクションで、次の値を設定します:
- 条件: イベント・タイプ
- サービス名: オブジェクト・ストレージ
- イベント・タイプ: オブジェクト – 更新
これらの設定は、オブジェクト・ストレージ・オブジェクトが更新されるたびにアクションがトリガーされることを示します。どのバケット内のオブジェクトでも更新が発生する可能性があるため、さらに条件を追加して絞り込みます。
別の条件ボタンをクリックして、さらに条件を追加します。
1. 次の属性を使用して表領域を作成します:
  - 条件: 属性
  - 属性名: <バケット名またはID>
  - 属性値: <構成ファイル・バケット名/OCID>
2. 次の属性を使用して2番目の条件を作成します:
  - 条件: 属性
  - 属性名: <リソース名またはID>
  - 属性値: <構成ファイル名/OCID>
「アクション」セクションで、次の値を設定します:
- アクション・タイプ: 通知
- 通知コンパートメント: <通知トピックのコンパートメント名>
- トピック: <トピック名>
「ルールの作成」ボタンをクリックします。
ルールの検証ボタンをクリックして、ルールが機能するかどうかをテストします。通知メッセージが送信されます。
1. イベントの例セクションで、コード・エディタを使用して、イベント・ルールに設定した一致する値に次の設定を変更します。
  - <通知トピックのコンパートメント名>
  - <リソース名>
  - <バケット名>
2. イベントの例がルールに一致するかどうかを確認するボタンをクリックします。
これでOCIの設定は完了です。OCI通知のODP.NET設定を完了しましょう。

OCI通知のODP.NET設定

OCIオブジェクト・ストレージ通知の場合、ODP.NET接続文字列のURLには、JSON構成ファイル内のOCIプロファイル名、およびOCIイベント・リスナーのパスとポートが必要です。接続文字列URLの構文を次に示します。

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

OCI変更通知を有効にするには、URL接続文字列に次のオプションが必要です:

OCIイベント・リスナーのオプション	説明
`Event_Listener_Path`	通知をリスニングするネットワーク・パス・リスナー
`Event_Listener_Port`	通知をリスニングするネットワーク・ポート・リスナー

この設定では、接続文字列URLに、OCI構成ファイル用に以前に作成したOCI_PROFILE名も含まれています。ODP.NET接続文字列は次のようになります。

サンプル・コード: ODP.NET OCI変更通知接続文字列の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")

これで、OCIオブジェクト・ストレージの変更通知設定が完了しました。