ASP.NET Core の構成プロバイダーの Azure Key VaultAzure Key Vault Configuration Provider in ASP.NET Core

By Andrew Stanton-看護師By Andrew Stanton-Nurse

このドキュメントでは、 Azure Key Vault 構成プロバイダーを使用して、Azure Key Vault シークレットからアプリ構成値を読み込む方法について説明します。This document explains how to use the Azure Key Vault Configuration Provider to load app configuration values from Azure Key Vault secrets. Azure Key Vault は、アプリとサービスで使用される暗号化キーとシークレットを保護するのに役立つクラウドベースのサービスです。Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. ASP.NET Core アプリで Azure Key Vault を使用する一般的なシナリオは次のとおりです。Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • 機密性の高い構成データへのアクセスを制御する。Controlling access to sensitive configuration data.
  • 構成データを格納するときに、FIPS 140-2 Level 2 で検証されたハードウェアセキュリティモジュール (HSM) の要件を満たしている。Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

パッケージPackages

パッケージ参照を Azure.Extensions.AspNetCore.Configuration に追加します。シークレット パッケージ。Add a package reference to the Azure.Extensions.AspNetCore.Configuration.Secrets package.

サンプル アプリSample app

サンプルアプリは、 #define Program.cs ファイルの先頭にあるステートメントによって決定される2つのモードのいずれかで実行されます。The sample app runs in either of two modes determined by the #define statement at the top of the Program.cs file:

  • Certificate: Azure Key Vault クライアント ID と x.509 証明書を使用して、Azure Key Vault に格納されているシークレットにアクセスする方法を示します。Certificate: Demonstrates the use of an Azure Key Vault Client ID and X.509 certificate to access secrets stored in Azure Key Vault. このバージョンのサンプルは、Azure App Service、または ASP.NET Core アプリを提供できる任意のホストにデプロイされている任意の場所から実行できます。This version of the sample can be run from any location, deployed to Azure App Service or any host capable of serving an ASP.NET Core app.
  • Managed: Azure リソースの管理対象 id を使用して、アプリのコードまたは構成に格納されている資格情報を使用せずに Azure AD 認証で Azure Key Vault するようにアプリを認証する方法を示します。Managed: Demonstrates how to use Managed identities for Azure resources to authenticate the app to Azure Key Vault with Azure AD authentication without credentials stored in the app's code or configuration. マネージ id を使用して認証を行う場合、Azure AD アプリケーション ID とパスワード (クライアントシークレット) は必要ありません。When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. Managedサンプルのバージョンは、Azure にデプロイする必要があります。The Managed version of the sample must be deployed to Azure. Azure リソースの管理対象 id の使用 」セクションのガイダンスに従ってください。Follow the guidance in the Use the Managed identities for Azure resources section.

プリプロセッサディレクティブ () を使用してサンプルアプリケーションを構成する方法の詳細につい #define ては、「」を参照してください ASP.NET Core の概要For more information on how to configure a sample app using preprocessor directives (#define), see ASP.NET Core の概要.

開発環境でのシークレットストレージSecret storage in the Development environment

シークレットマネージャーツールを使用してローカルにシークレットを設定します。Set secrets locally using the Secret Manager tool. 開発環境のローカルコンピューターでサンプルアプリを実行すると、シークレットはローカルユーザーシークレットストアから読み込まれます。When the sample app runs on the local machine in the Development environment, secrets are loaded from the local user secrets store.

Secret Manager ツールでは、 <UserSecretsId> アプリのプロジェクトファイルにプロパティが必要です。The Secret Manager tool requires a <UserSecretsId> property in the app's project file. プロパティ値 ( {GUID} ) を任意の一意の GUID に設定します。Set the property value ({GUID}) to any unique GUID:

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

シークレットは、名前と値のペアとして作成されます。Secrets are created as name-value pairs. 階層値 (構成セクション) では、 : ASP.NET Core 構成 キー名の区切り記号として (コロン) を使用します。Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

シークレットマネージャーは、プロジェクトの コンテンツルートに開かれたコマンドシェルから使用され {SECRET NAME} ます。ここで、は名前、 {SECRET VALUE} は値です。The Secret Manager is used from a command shell opened to the project's content root, where {SECRET NAME} is the name and {SECRET VALUE} is the value:

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

プロジェクトの コンテンツルート からコマンドシェルで次のコマンドを実行して、サンプルアプリのシークレットを設定します。Execute the following commands in a command shell from the project's content root to set the secrets for the sample app:

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

これらのシークレットが Azure Key Vault セクションを 含む運用環境のシークレットストレージ の Azure Key Vault に格納されている場合、 _dev サフィックスはに変更され _prod ます。When these secrets are stored in Azure Key Vault in the Secret storage in the Production environment with Azure Key Vault section, the _dev suffix is changed to _prod. サフィックスは、構成値のソースを示すビジュアルキューをアプリの出力に提供します。The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Azure Key Vault を使用した運用環境のシークレットストレージSecret storage in the Production environment with Azure Key Vault

クイックスタートに記載されている手順 : Azure CLI トピックを使用して Azure Key Vault からシークレットを設定して取得 する方法については、Azure Key Vault の作成とサンプルアプリで使用するシークレットの保存に関するページを参照してください。The instructions provided by the Quickstart: Set and retrieve a secret from Azure Key Vault using Azure CLI topic are summarized here for creating an Azure Key Vault and storing secrets used by the sample app. 詳細については、「」を参照してください。Refer to the topic for further details.

  1. Azure portalの次のいずれかの方法を使用して、Azure Cloud shell を開きます。Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • コード ブロックの右上隅にある [使ってみる] を選択します。Select Try It in the upper-right corner of a code block. テキストボックス内の検索文字列 "Azure CLI" を使用します。Use the search string "Azure CLI" in the text box.
    • [ Cloud Shell の起動 ] ボタンを使用して、ブラウザーで Cloud Shell を開きます。Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • Azure portal の右上隅にあるメニューの [ Cloud Shell ] ボタンを選択します。Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    詳細については、「 Azure Cloud Shell の Azure CLIと概要」を参照してください。For more information, see Azure CLI and Overview of Azure Cloud Shell.

  2. まだ認証されていない場合は、コマンドを使用してサインインし az login ます。If you aren't already authenticated, sign in with the az login command.

  3. 次のコマンドを使用してリソースグループを作成 {RESOURCE GROUP NAME} します。は、新しいリソースグループのリソースグループ名で、 {LOCATION} は Azure リージョン (datacenter) です。Create a resource group with the following command, where {RESOURCE GROUP NAME} is the resource group name for the new resource group and {LOCATION} is the Azure region (datacenter):

    az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  4. 次のコマンドを使用して、リソースグループにキーコンテナーを作成します。ここで、 {KEY VAULT NAME} は新しい key vault の名前、 {LOCATION} は Azure リージョン (datacenter) です。Create a key vault in the resource group with the following command, where {KEY VAULT NAME} is the name for the new key vault and {LOCATION} is the Azure region (datacenter):

    az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  5. 名前と値のペアとして、キーコンテナーにシークレットを作成します。Create secrets in the key vault as name-value pairs.

    Azure Key Vault のシークレット名は、英数字とダッシュに限定されます。Azure Key Vault secret names are limited to alphanumeric characters and dashes. 階層値 (構成セクション) -- は、区切り記号として (2 つのダッシュ) を使用します。Hierarchical values (configuration sections) use -- (two dashes) as a separator. ASP.NET Core 構成でサブキーからセクションを区切るために通常使用されるコロンは、key vault のシークレット名では許可されていません。Colons, which are normally used to delimit a section from a subkey in ASP.NET Core configuration, aren't allowed in key vault secret names. そのため、シークレットがアプリの構成に読み込まれるときに、2つのダッシュが使用され、コロンにスワップされます。Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    サンプルアプリで使用するシークレットは次のとおりです。The following secrets are for use with the sample app. 値には、 _prod _dev 開発環境で読み込まれたサフィックス値とユーザーシークレットから区別するためのサフィックスが含まれます。The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. は、 {KEY VAULT NAME} 前の手順で作成したキーコンテナーの名前に置き換えます。Replace {KEY VAULT NAME} with the name of the key vault that you created in the prior step:

    az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
    az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
    

Azure でホストされていないアプリにアプリケーション ID と x.509 証明書を使用するUse Application ID and X.509 certificate for non-Azure-hosted apps

アプリが Azure の外部でホストされている場合 に、AZURE ACTIVE DIRECTORY アプリケーション ID と x.509 証明書を使用して Key Vault に対する認証を行うように Azure AD、Azure Key Vault、アプリを構成します。Configure Azure AD, Azure Key Vault, and the app to use an Azure Active Directory Application ID and X.509 certificate to authenticate to a key vault when the app is hosted outside of Azure. 詳細については、「About keys, secrets, and certificates (キー、シークレット、証明書について)」を参照してください。For more information, see About keys, secrets, and certificates.

注意

Azure でホストされているアプリでは、アプリケーション ID と x.509 証明書を使用することができますが、azure でアプリをホストする場合は、 azure リソースの管理対象 id を使用することをお勧めします。Although using an Application ID and X.509 certificate is supported for apps hosted in Azure, we recommend using Managed identities for Azure resources when hosting an app in Azure. マネージド id では、アプリまたは開発環境に証明書を保存する必要はありません。Managed identities don't require storing a certificate in the app or in the development environment.

このサンプルアプリでは、 #define Program.cs ファイルの先頭にあるステートメントがに設定されている場合に、アプリケーション ID と x.509 証明書を使用し Certificate ます。The sample app uses an Application ID and X.509 certificate when the #define statement at the top of the Program.cs file is set to Certificate.

  1. PKCS # 12 アーカイブ (.pfx) 証明書を作成します。Create a PKCS#12 archive (.pfx) certificate. 証明書を作成するためのオプションとして、Windows とOpenSSLの MakeCertがあります。Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. 現在のユーザーの個人証明書ストアに証明書をインストールします。Install the certificate into the current user's personal certificate store. キーをエクスポート可能としてマークすることはオプションです。Marking the key as exportable is optional. このプロセスの後半で使用される証明書の拇印をメモしておきます。Note the certificate's thumbprint, which is used later in this process.
  3. PKCS # 12 アーカイブ (.pfx) 証明書を DER でエンコードされた証明書 (.cer) としてエクスポートします。Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. アプリを Azure AD (アプリの登録) に登録します。Register the app with Azure AD (App registrations).
  5. DER でエンコードされた証明書 (.cer) を Azure AD にアップロードします。Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Azure AD でアプリを選択します。Select the app in Azure AD.
    2. [ 証明書 & シークレット] に移動します。Navigate to Certificates & secrets.
    3. 公開キーを含む証明書をアップロードするには、[ 証明書のアップロード ] を選択します。Select Upload certificate to upload the certificate, which contains the public key. .Cerpem、または .crt 証明書を使用できます。A .cer, .pem, or .crt certificate is acceptable.
  6. Key vault 名、アプリケーション ID、証明書の拇印をアプリのファイルに格納し appsettings.json ます。Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. Azure portal の キーコンテナー に移動します。Navigate to Key vaults in the Azure portal.
  8. Azure Key Vault セクションで、 運用環境のシークレットストレージ に作成したキーコンテナーを選択します。Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. [アクセス ポリシー] を選択します。Select Access policies.
  10. [アクセス ポリシーの追加] を選択します。Select Add Access Policy.
  11. [ シークレットのアクセス許可 ] を開き、アプリに Get および List アクセス許可を提供します。Open Secret permissions and provide the app with Get and List permissions.
  12. [ プリンシパルの選択 ] を選択し、名前で登録済みのアプリを選択します。Select Select principal and select the registered app by name. [選択] ボタンを選択します。Select the Select button.
  13. [OK] を選択します。Select OK.
  14. [保存] を選択します。Select Save.
  15. アプリを展開します。Deploy the app.

サンプルアプリでは、 Certificate IConfigurationRoot シークレット名と同じ名前を使用してから構成値を取得します。The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • 非階層値: の値は、 SecretName で取得され config["SecretName"] ます。Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • 階層値 (セクション): : (コロン) 表記または拡張メソッドを使用し GetSection ます。Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. 次のいずれかの方法を使用して、構成値を取得します。Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

X.509 証明書は OS によって管理されます。The X.509 certificate is managed by the OS. アプリは、ファイルによって指定された値を使用して Addazurekeyvault を呼び出し appsettings.json ます。The app calls AddAzureKeyVault with values supplied by the appsettings.json file:

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;
// using Azure.Identity;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                using (var store = new X509Store(StoreLocation.CurrentUser))
                {
                    store.Open(OpenFlags.ReadOnly);
                    var certs = store.Certificates
                        .Find(X509FindType.FindByThumbprint,
                            builtConfig["AzureADCertThumbprint"], false);

                    config.AddAzureKeyVault(new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                                            new ClientCertificateCredential(builtConfig["AzureADDirectoryId"], builtConfig["AzureADApplicationId"], certs.OfType<X509Certificate2>().Single()),
                                            new KeyVaultSecretManager());


                    store.Close();
                }
            }
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

値の例:Example values:

  • Key vault 名: contosovaultKey vault name: contosovault
  • アプリケーション ID: 627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • 証明書の拇印: fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint",
  "AzureADDirectoryId": "Azure AD Directory ID"
}

アプリを実行すると、web ページに読み込まれたシークレット値が表示されます。When you run the app, a webpage shows the loaded secret values. 開発環境では、シークレット値はサフィックス付きで読み込ま _dev れます。In the Development environment, secret values load with the _dev suffix. 運用環境では、値はというサフィックスで読み込まれ _prod ます。In the Production environment, the values load with the _prod suffix.

Azure リソースの管理対象 id を使用するUse Managed identities for Azure resources

Azure にデプロイされたアプリ は、 Azure リソースの管理対象 idを利用できます。これにより、アプリは、アプリに格納されている資格情報 (アプリケーション ID とパスワード/クライアントシークレット) を使用せずに Azure AD 認証を使用して Azure Key Vault で認証することができます。An app deployed to Azure can take advantage of Managed identities for Azure resources, which allows the app to authenticate with Azure Key Vault using Azure AD authentication without credentials (Application ID and Password/Client Secret) stored in the app.

このサンプルアプリでは、 #define Program.cs ファイルの先頭にあるステートメントがに設定されている場合に、Azure リソースの管理対象 id を使用し Managed ます。The sample app uses Managed identities for Azure resources when the #define statement at the top of the Program.cs file is set to Managed.

アプリのファイルにコンテナー名を入力し appsettings.json ます。Enter the vault name into the app's appsettings.json file. このサンプルアプリでは、バージョンに設定するときにアプリケーション ID とパスワード (クライアントシークレット) は必要ありません Managed 。そのため、これらの構成エントリは無視してかまいません。The sample app doesn't require an Application ID and Password (Client Secret) when set to the Managed version, so you can ignore those configuration entries. アプリが Azure にデプロイされ、Azure は、ファイルに格納されているコンテナー名を使用してのみ Azure Key Vault にアクセスするようにアプリを認証し appsettings.json ます。The app is deployed to Azure, and Azure authenticates the app to access Azure Key Vault only using the vault name stored in the appsettings.json file.

サンプルアプリを Azure App Service にデプロイします。Deploy the sample app to Azure App Service.

Azure App Service にデプロイされたアプリは、サービスの作成時に Azure AD に自動的に登録されます。An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. 次のコマンドで使用するために、デプロイからオブジェクト ID を取得します。Obtain the Object ID from the deployment for use in the following command. オブジェクト ID は、App Service のパネルの Azure portal に表示され Identity ます。The Object ID is shown in the Azure portal on the Identity panel of the App Service.

Azure CLI とアプリのオブジェクト ID を使用して、 list get キーコンテナーにアクセスするためのアクセス許可とアクセス許可をアプリに付与します。Using Azure CLI and the app's Object ID, provide the app with list and get permissions to access the key vault:

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Azure CLI、PowerShell、または Azure portal を使用して アプリを再起動 します。Restart the app using Azure CLI, PowerShell, or the Azure portal.

サンプルアプリ:The sample app:

  • クラスのインスタンスを作成し DefaultAzureCredential ます。資格情報は、Azure リソースの環境からアクセストークンを取得しようとします。Creates an instance of the DefaultAzureCredential class, the credential attempts to obtain an access token from environment for Azure resources.
  • インスタンスを Azure.Security.KeyVault.Secrets.Secrets 使用して、新しいが作成され DefaultAzureCredential ます。A new Azure.Security.KeyVault.Secrets.Secrets is created with the DefaultAzureCredential instance.
  • Azure.Security.KeyVault.Secrets.Secretsインスタンスは、の既定の実装で使用されます。この実装では、 Azure.Extensions.Aspnetcore.Configuration.Secrets すべてのシークレット値が読み込まれ、二重ダッシュ ( -- ) がキー名のコロン () に置き換えられ : ます。The Azure.Security.KeyVault.Secrets.Secrets instance is used with a default implementation of Azure.Extensions.Aspnetcore.Configuration.Secrets that loads all secret values and replaces double-dashes (--) with colons (:) in key names.
// using Azure.Security.KeyVault.Secrets;
// using Azure.Identity;
// using Azure.Extensions.AspNetCore.Configuration.Secrets;

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();
                var secretClient = new SecretClient(new Uri($"https://{builtConfig["KeyVaultName"]}.vault.azure.net/"),
                                                         new DefaultAzureCredential());
                config.AddAzureKeyVault(secretClient, new KeyVaultSecretManager());


            }
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Key vault 名の値の例: contosovaultKey vault name example value: contosovault

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

アプリを実行すると、web ページに読み込まれたシークレット値が表示されます。When you run the app, a webpage shows the loaded secret values. 開発環境では、シークレット値は _dev ユーザーシークレットによって提供されるため、サフィックスが付いています。In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. 運用環境では、値は _prod Azure Key Vault によって提供されるため、サフィックス付きで読み込まれます。In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

エラーが発生した場合は Access denied 、アプリが Azure AD に登録されていること、およびキーコンテナーへのアクセスが提供されていることを確認します。If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Azure でサービスを再起動したことを確認します。Confirm that you've restarted the service in Azure.

マネージ id と Azure DevOps パイプラインでプロバイダーを使用する方法の詳細については、「 管理対象サービス id を使用して VM への Azure Resource Manager サービス接続を作成する」を参照してください。For information on using the provider with a managed identity and an Azure DevOps pipeline, see Create an Azure Resource Manager service connection to a VM with a managed service identity.

構成オプションConfiguration options

AddAzureKeyVault は、AzureKeyVaultConfigurationOptions を受け入れることができます。AddAzureKeyVault can accept an AzureKeyVaultConfigurationOptions:

config.AddAzureKeyVault(new SecretClient(new URI("Your Key Vault Endpoint"), new DefaultAzureCredential()),
                        new AzureKeyVaultConfigurationOptions())
    {
        ...
    });
プロパティProperty 説明Description
Manager Azure.Extensions.Aspnetcore.Configuration.Secrets シークレットの読み込みを制御するために使用されるインスタンス。Azure.Extensions.Aspnetcore.Configuration.Secrets instance used to control secret loading.
ReloadInterval Timespan キーコンテナーのポーリングによって変更が試行されるまでの待機時間。Timespan to wait between attempts at polling the key vault for changes. 既定値はです null (構成は再読み込みされません)。The default value is null (configuration isn't reloaded).

キー名のプレフィックスを使用するUse a key name prefix

AddAzureKeyVault は、の実装を受け入れるオーバーロードを提供します Azure.Extensions.Aspnetcore.Configuration.Secrets 。これにより、key vault のシークレットを構成キーに変換する方法を制御できます。AddAzureKeyVault provides an overload that accepts an implementation of Azure.Extensions.Aspnetcore.Configuration.Secrets, which allows you to control how key vault secrets are converted into configuration keys. たとえば、アプリの起動時に指定されたプレフィックス値に基づいてシークレット値を読み込むようにインターフェイスを実装できます。For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. これにより、たとえば、アプリのバージョンに基づいてシークレットを読み込むことができます。This allows you, for example, to load secrets based on the version of the app.

警告

Key vault シークレットのプレフィックスを使用して、複数のアプリのシークレットを同じ key vault に配置したり、環境の機密情報 ( 開発運用 シークレットなど) を同じコンテナーに配置したりしないでください。Don't use prefixes on key vault secrets to place secrets for multiple apps into the same key vault or to place environmental secrets (for example, development versus production secrets) into the same vault. さまざまなアプリと開発/運用環境では、セキュリティレベルが最も高いアプリケーション環境を分離するために個別のキーコンテナーを使用することをお勧めします。We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

次の例では、キーコンテナー (および開発環境のシークレットマネージャーツールを使用) でシークレットが確立されてい 5000-AppSecret ます (キーコンテナーのシークレット名ではピリオドは使用できません)。In the following example, a secret is established in the key vault (and using the Secret Manager tool for the Development environment) for 5000-AppSecret (periods aren't allowed in key vault secret names). このシークレットは、アプリのバージョン5.0.0.0 のアプリシークレットを表します。This secret represents an app secret for version 5.0.0.0 of the app. アプリの別のバージョンでは、5.1.0.0 は、キーコンテナーに (およびシークレットマネージャーツールを使用して) シークレットを追加し 5100-AppSecret ます。For another version of the app, 5.1.0.0, a secret is added to the key vault (and using the Secret Manager tool) for 5100-AppSecret. 各アプリバージョンは、バージョン管理されたシークレット値をとして構成に読み込み AppSecret ます。これにより、シークレットが読み込まれるときにバージョンが除去されます。Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVault は、カスタムのを使用して呼び出され Azure.Extensions.Aspnetcore.Configuration.Secrets ます。AddAzureKeyVault is called with a custom Azure.Extensions.Aspnetcore.Configuration.Secrets:

config.AddAzureKeyVault(
    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
    builtConfig["AzureADApplicationId"],
    certs.OfType<X509Certificate2>().Single(),
    new PrefixKeyVaultSecretManager(versionPrefix));

実装によって、 Azure.Extensions.Aspnetcore.Configuration.Secrets シークレットのバージョンプレフィックスに反応し、適切なシークレットが構成に読み込まれます。The Azure.Extensions.Aspnetcore.Configuration.Secrets implementation reacts to the version prefixes of secrets to load the proper secret into configuration:

  • Load 名前がプレフィックスで始まる場合に、シークレットを読み込みます。Load loads a secret when its name starts with the prefix. 他のシークレットは読み込まれていません。Other secrets aren't loaded.
  • GetKey:GetKey:
    • シークレット名からプレフィックスを削除します。Removes the prefix from the secret name.
    • 任意の名前の2つのダッシュを、 KeyDelimiter 構成で使用される区切り記号 (通常はコロン) で置き換えます。Replaces two dashes in any name with the KeyDelimiter, which is the delimiter used in configuration (usually a colon). Azure Key Vault では、シークレット名にコロンを使用することはできません。Azure Key Vault doesn't allow a colon in secret names.
public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public override bool Load(SecretProperties secret)
    {
        return secret.Name.StartsWith(_prefix);
    }

    public override string GetKey(KeyVaultSecret secret)
    {
        return secret.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

この Load メソッドは、コンテナーシークレットを反復処理してバージョンプレフィックスを持つものを検索するプロバイダーアルゴリズムによって呼び出されます。The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. バージョンプレフィックスがで見つかった場合 Load 、アルゴリズムは、メソッドを使用して GetKey シークレット名の構成名を返します。When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. シークレットの名前からバージョンプレフィックスを取り除き、アプリの構成名と値のペアに読み込むための残りのシークレット名を返します。It strips off the version prefix from the secret's name and returns the rest of the secret name for loading into the app's configuration name-value pairs.

このアプローチが実装されている場合:When this approach is implemented:

  1. アプリのプロジェクトファイルで指定されているアプリのバージョン。The app's version specified in the app's project file. 次の例では、アプリのバージョンがに設定されてい 5.0.0.0 ます。In the following example, the app's version is set to 5.0.0.0:

    <PropertyGroup>
      <Version>5.0.0.0</Version>
    </PropertyGroup>
    
  2. <UserSecretsId>アプリケーションのプロジェクトファイルにプロパティが存在することを確認します。ここで、 {GUID} はユーザー指定の GUID です。Confirm that a <UserSecretsId> property is present in the app's project file, where {GUID} is a user-supplied GUID:

    <PropertyGroup>
      <UserSecretsId>{GUID}</UserSecretsId>
    </PropertyGroup>
    

    シークレットマネージャーツールを使用して、次のシークレットをローカルに保存します。Save the following secrets locally with the Secret Manager tool:

    dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
    dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
    
  3. シークレットは、次の Azure CLI コマンドを使用して Azure Key Vault に保存されます。Secrets are saved in Azure Key Vault using the following Azure CLI commands:

    az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
    az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
    
  4. アプリを実行すると、key vault シークレットが読み込まれます。When the app is run, the key vault secrets are loaded. の文字列シークレット 5000-AppSecret は、アプリのプロジェクトファイル () で指定されているアプリのバージョンと一致し 5.0.0.0 ます。The string secret for 5000-AppSecret is matched to the app's version specified in the app's project file (5.0.0.0).

  5. バージョン 5000 (ダッシュ付き) は、キー名から削除されます。The version, 5000 (with the dash), is stripped from the key name. アプリ全体で、キーを使用して構成を読み取ると、 AppSecret シークレットの値が読み込まれます。Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. アプリのバージョンがプロジェクトファイルでに変更され、 5.1.0.0 アプリが再度実行された場合、返されるシークレット値は 5.1.0.0_secret_value_dev 開発環境および 5.1.0.0_secret_value_prod 運用環境にあります。If the app's version is changed in the project file to 5.1.0.0 and the app is run again, the secret value returned is 5.1.0.0_secret_value_dev in the Development environment and 5.1.0.0_secret_value_prod in Production.

注意

SecretClientAddAzureKeyVault に独自の実装を提供することもできます。You can also provide your own SecretClient implementation to AddAzureKeyVault. カスタムクライアントは、アプリ全体でクライアントの1つのインスタンスを共有することを許可します。A custom client permits sharing a single instance of the client across the app.

配列をクラスにバインドするBind an array to a class

プロバイダーは、POCO 配列にバインドするために、配列に構成値を読み取ることができます。The provider is capable of reading configuration values into an array for binding to a POCO array.

キーにコロン () 区切り記号を含めることができる構成ソースから読み取る場合 : 、配列を構成するキー (、、) を区別するために、数値キーセグメントが使用され :0: :1::{n}: ます。When reading from a configuration source that allows keys to contain colon (:) separators, a numeric key segment is used to distinguish the keys that make up an array (:0:, :1:, … :{n}:). 詳細については、「 構成: 配列をクラスにバインドする」を参照してください。For more information, see Configuration: Bind an array to a class.

Azure Key Vault キーでは、区切り記号としてコロンを使用することはできません。Azure Key Vault keys can't use a colon as a separator. このトピックで説明する方法では、 -- 階層値 (セクション) の区切り記号として二重ダッシュ () を使用します。The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). 配列キーは、2つのダッシュと数値のキーセグメント (、、) を使用して Azure Key Vault に格納され --0-- --1----{n}-- ます。Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

JSON ファイルによって提供される次の Serilog logging プロバイダーの構成を確認します。Examine the following Serilog logging provider configuration provided by a JSON file. 次の2つのオブジェクトリテラルが配列に定義されています WriteTo 。この シンク には、ログ出力の宛先が記述されています。There are two object literals defined in the WriteTo array that reflect two Serilog sinks, which describe destinations for logging output:

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

前の JSON ファイルに示されている構成は、二重ダッシュ ( -- ) 表記と数値セグメントを使用して Azure Key Vault に格納されます。The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

キーKey Value
Serilog--WriteTo--0--Name AzureTableStorage
Serilog--WriteTo--0--Args--storageTableName logs
Serilog--WriteTo--0--Args--connectionString DefaultEnd...ountKey=Eby8...GMGw==
Serilog--WriteTo--1--Name AzureDocumentDB
Serilog--WriteTo--1--Args--endpointUrl https://contoso.documents.azure.com:443
Serilog--WriteTo--1--Args--authorizationKey Eby8...GMGw==

シークレットの再読み込みReload secrets

シークレットは、が呼び出されるまでキャッシュされ IConfigurationRoot.Reload() ます。Secrets are cached until IConfigurationRoot.Reload() is called. が実行されるまで、key vault 内の有効期限切れ、無効、および更新されたシークレットは、アプリで尊重されません ReloadExpired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

無効なシークレットと期限切れのシークレットDisabled and expired secrets

無効で有効期限が切れたシークレットは、をスローし RequestFailedException ます。Disabled and expired secrets throw a RequestFailedException. アプリがスローされないようにするには、別の構成プロバイダーを使用して構成を提供するか、無効または期限切れのシークレットを更新してください。To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

トラブルシューティングTroubleshoot

アプリがプロバイダーを使用した構成の読み込みに失敗すると、エラーメッセージが ASP.NET Core ログ記録インフラストラクチャに書き込まれます。When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. 次の状況では、構成を読み込むことができません。The following conditions will prevent configuration from loading:

  • Azure Active Directory で、アプリまたは証明書が正しく構成されていません。The app or certificate isn't configured correctly in Azure Active Directory.
  • キーコンテナーは Azure Key Vault に存在しません。The key vault doesn't exist in Azure Key Vault.
  • アプリは、key vault にアクセスする権限がありません。The app isn't authorized to access the key vault.
  • アクセスポリシーには Get 、とのアクセス許可は含まれません ListThe access policy doesn't include Get and List permissions.
  • Key vault で、構成データ (名前と値のペア) の名前が正しくないか、存在しないか、無効であるか、または期限が切れています。In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • アプリの key vault 名 ( KeyVaultName )、Azure AD アプリケーション Id ( AzureADApplicationId )、Azure AD 証明書の拇印 ( AzureADCertThumbprint )、または Azure AD directoryid () が正しくあり AzureADDirectoryId ません。The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint), or Azure AD DirectoryId (AzureADDirectoryId).
  • 読み込みようとしている値の構成キー (名前) が正しくありません。The configuration key (name) is incorrect in the app for the value you're trying to load.
  • アプリのアクセスポリシーを key vault に追加すると、ポリシーが作成されましたが、アクセスポリシー UI で [保存] ボタンが選択されていませんでした。When adding the access policy for the app to the key vault, the policy was created, but the Save button wasn't selected in the Access policies UI.

その他のリソースAdditional resources

このドキュメントでは、 Microsoft Azure Key Vault 構成プロバイダーを使用して Azure Key Vault シークレットからアプリ構成値を読み込む方法について説明します。This document explains how to use the Microsoft Azure Key Vault Configuration Provider to load app configuration values from Azure Key Vault secrets. Azure Key Vault は、アプリとサービスで使用される暗号化キーとシークレットを保護するのに役立つクラウドベースのサービスです。Azure Key Vault is a cloud-based service that assists in safeguarding cryptographic keys and secrets used by apps and services. ASP.NET Core アプリで Azure Key Vault を使用する一般的なシナリオは次のとおりです。Common scenarios for using Azure Key Vault with ASP.NET Core apps include:

  • 機密性の高い構成データへのアクセスを制御する。Controlling access to sensitive configuration data.
  • 構成データを格納するときに、FIPS 140-2 Level 2 で検証されたハードウェアセキュリティモジュール (HSM) の要件を満たしている。Meeting the requirement for FIPS 140-2 Level 2 validated Hardware Security Modules (HSM's) when storing configuration data.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

パッケージPackages

パッケージ参照を Microsoft.Extensions.Configuration に追加します。AzureKeyVault パッケージ。Add a package reference to the Microsoft.Extensions.Configuration.AzureKeyVault package.

サンプル アプリSample app

サンプルアプリは、 #define Program.cs ファイルの先頭にあるステートメントによって決定される2つのモードのいずれかで実行されます。The sample app runs in either of two modes determined by the #define statement at the top of the Program.cs file:

  • Certificate: Azure Key Vault クライアント ID と x.509 証明書を使用して、Azure Key Vault に格納されているシークレットにアクセスする方法を示します。Certificate: Demonstrates the use of an Azure Key Vault Client ID and X.509 certificate to access secrets stored in Azure Key Vault. このバージョンのサンプルは、Azure App Service、または ASP.NET Core アプリを提供できる任意のホストにデプロイされている任意の場所から実行できます。This version of the sample can be run from any location, deployed to Azure App Service or any host capable of serving an ASP.NET Core app.
  • Managed: Azure リソースの管理対象 id を使用して、アプリのコードまたは構成に格納されている資格情報を使用せずに Azure AD 認証で Azure Key Vault するようにアプリを認証する方法を示します。Managed: Demonstrates how to use Managed identities for Azure resources to authenticate the app to Azure Key Vault with Azure AD authentication without credentials stored in the app's code or configuration. マネージ id を使用して認証を行う場合、Azure AD アプリケーション ID とパスワード (クライアントシークレット) は必要ありません。When using managed identities to authenticate, an Azure AD Application ID and Password (Client Secret) aren't required. Managedサンプルのバージョンは、Azure にデプロイする必要があります。The Managed version of the sample must be deployed to Azure. Azure リソースの管理対象 id の使用 」セクションのガイダンスに従ってください。Follow the guidance in the Use the Managed identities for Azure resources section.

プリプロセッサディレクティブ () を使用してサンプルアプリケーションを構成する方法の詳細につい #define ては、「」を参照してください ASP.NET Core の概要For more information on how to configure a sample app using preprocessor directives (#define), see ASP.NET Core の概要.

開発環境でのシークレットストレージSecret storage in the Development environment

シークレットマネージャーツールを使用してローカルにシークレットを設定します。Set secrets locally using the Secret Manager tool. 開発環境のローカルコンピューターでサンプルアプリを実行すると、シークレットはローカルユーザーシークレットストアから読み込まれます。When the sample app runs on the local machine in the Development environment, secrets are loaded from the local user secrets store.

Secret Manager ツールでは、 <UserSecretsId> アプリのプロジェクトファイルにプロパティが必要です。The Secret Manager tool requires a <UserSecretsId> property in the app's project file. プロパティ値 ( {GUID} ) を任意の一意の GUID に設定します。Set the property value ({GUID}) to any unique GUID:

<PropertyGroup>
  <UserSecretsId>{GUID}</UserSecretsId>
</PropertyGroup>

シークレットは、名前と値のペアとして作成されます。Secrets are created as name-value pairs. 階層値 (構成セクション) では、 : ASP.NET Core 構成 キー名の区切り記号として (コロン) を使用します。Hierarchical values (configuration sections) use a : (colon) as a separator in ASP.NET Core configuration key names.

シークレットマネージャーは、プロジェクトの コンテンツルートに開かれたコマンドシェルから使用され {SECRET NAME} ます。ここで、は名前、 {SECRET VALUE} は値です。The Secret Manager is used from a command shell opened to the project's content root, where {SECRET NAME} is the name and {SECRET VALUE} is the value:

dotnet user-secrets set "{SECRET NAME}" "{SECRET VALUE}"

プロジェクトの コンテンツルート からコマンドシェルで次のコマンドを実行して、サンプルアプリのシークレットを設定します。Execute the following commands in a command shell from the project's content root to set the secrets for the sample app:

dotnet user-secrets set "SecretName" "secret_value_1_dev"
dotnet user-secrets set "Section:SecretName" "secret_value_2_dev"

これらのシークレットが Azure Key Vault セクションを 含む運用環境のシークレットストレージ の Azure Key Vault に格納されている場合、 _dev サフィックスはに変更され _prod ます。When these secrets are stored in Azure Key Vault in the Secret storage in the Production environment with Azure Key Vault section, the _dev suffix is changed to _prod. サフィックスは、構成値のソースを示すビジュアルキューをアプリの出力に提供します。The suffix provides a visual cue in the app's output indicating the source of the configuration values.

Azure Key Vault を使用した運用環境のシークレットストレージSecret storage in the Production environment with Azure Key Vault

クイックスタートに記載されている手順 : Azure CLI トピックを使用して Azure Key Vault からシークレットを設定して取得 する方法については、Azure Key Vault の作成とサンプルアプリで使用するシークレットの保存に関するページを参照してください。The instructions provided by the Quickstart: Set and retrieve a secret from Azure Key Vault using Azure CLI topic are summarized here for creating an Azure Key Vault and storing secrets used by the sample app. 詳細については、「」を参照してください。Refer to the topic for further details.

  1. Azure portalの次のいずれかの方法を使用して、Azure Cloud shell を開きます。Open Azure Cloud shell using any one of the following methods in the Azure portal:

    • コード ブロックの右上隅にある [使ってみる] を選択します。Select Try It in the upper-right corner of a code block. テキストボックス内の検索文字列 "Azure CLI" を使用します。Use the search string "Azure CLI" in the text box.
    • [ Cloud Shell の起動 ] ボタンを使用して、ブラウザーで Cloud Shell を開きます。Open Cloud Shell in your browser with the Launch Cloud Shell button.
    • Azure portal の右上隅にあるメニューの [ Cloud Shell ] ボタンを選択します。Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.

    詳細については、「 Azure Cloud Shell の Azure CLIと概要」を参照してください。For more information, see Azure CLI and Overview of Azure Cloud Shell.

  2. まだ認証されていない場合は、コマンドを使用してサインインし az login ます。If you aren't already authenticated, sign in with the az login command.

  3. 次のコマンドを使用してリソースグループを作成 {RESOURCE GROUP NAME} します。は、新しいリソースグループのリソースグループ名で、 {LOCATION} は Azure リージョン (datacenter) です。Create a resource group with the following command, where {RESOURCE GROUP NAME} is the resource group name for the new resource group and {LOCATION} is the Azure region (datacenter):

    az group create --name "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  4. 次のコマンドを使用して、リソースグループにキーコンテナーを作成します。ここで、 {KEY VAULT NAME} は新しい key vault の名前、 {LOCATION} は Azure リージョン (datacenter) です。Create a key vault in the resource group with the following command, where {KEY VAULT NAME} is the name for the new key vault and {LOCATION} is the Azure region (datacenter):

    az keyvault create --name {KEY VAULT NAME} --resource-group "{RESOURCE GROUP NAME}" --location {LOCATION}
    
  5. 名前と値のペアとして、キーコンテナーにシークレットを作成します。Create secrets in the key vault as name-value pairs.

    Azure Key Vault のシークレット名は、英数字とダッシュに限定されます。Azure Key Vault secret names are limited to alphanumeric characters and dashes. 階層値 (構成セクション) -- は、区切り記号として (2 つのダッシュ) を使用します。Hierarchical values (configuration sections) use -- (two dashes) as a separator. ASP.NET Core 構成でサブキーからセクションを区切るために通常使用されるコロンは、key vault のシークレット名では許可されていません。Colons, which are normally used to delimit a section from a subkey in ASP.NET Core configuration, aren't allowed in key vault secret names. そのため、シークレットがアプリの構成に読み込まれるときに、2つのダッシュが使用され、コロンにスワップされます。Therefore, two dashes are used and swapped for a colon when the secrets are loaded into the app's configuration.

    サンプルアプリで使用するシークレットは次のとおりです。The following secrets are for use with the sample app. 値には、 _prod _dev 開発環境で読み込まれたサフィックス値とユーザーシークレットから区別するためのサフィックスが含まれます。The values include a _prod suffix to distinguish them from the _dev suffix values loaded in the Development environment from User Secrets. は、 {KEY VAULT NAME} 前の手順で作成したキーコンテナーの名前に置き換えます。Replace {KEY VAULT NAME} with the name of the key vault that you created in the prior step:

    az keyvault secret set --vault-name {KEY VAULT NAME} --name "SecretName" --value "secret_value_1_prod"
    az keyvault secret set --vault-name {KEY VAULT NAME} --name "Section--SecretName" --value "secret_value_2_prod"
    

Azure でホストされていないアプリにアプリケーション ID と x.509 証明書を使用するUse Application ID and X.509 certificate for non-Azure-hosted apps

アプリが Azure の外部でホストされている場合 に、AZURE ACTIVE DIRECTORY アプリケーション ID と x.509 証明書を使用して Key Vault に対する認証を行うように Azure AD、Azure Key Vault、アプリを構成します。Configure Azure AD, Azure Key Vault, and the app to use an Azure Active Directory Application ID and X.509 certificate to authenticate to a key vault when the app is hosted outside of Azure. 詳細については、「About keys, secrets, and certificates (キー、シークレット、証明書について)」を参照してください。For more information, see About keys, secrets, and certificates.

注意

Azure でホストされているアプリでは、アプリケーション ID と x.509 証明書を使用することができますが、azure でアプリをホストする場合は、 azure リソースの管理対象 id を使用することをお勧めします。Although using an Application ID and X.509 certificate is supported for apps hosted in Azure, we recommend using Managed identities for Azure resources when hosting an app in Azure. マネージド id では、アプリまたは開発環境に証明書を保存する必要はありません。Managed identities don't require storing a certificate in the app or in the development environment.

このサンプルアプリでは、 #define Program.cs ファイルの先頭にあるステートメントがに設定されている場合に、アプリケーション ID と x.509 証明書を使用し Certificate ます。The sample app uses an Application ID and X.509 certificate when the #define statement at the top of the Program.cs file is set to Certificate.

  1. PKCS # 12 アーカイブ (.pfx) 証明書を作成します。Create a PKCS#12 archive (.pfx) certificate. 証明書を作成するためのオプションとして、Windows とOpenSSLの MakeCertがあります。Options for creating certificates include MakeCert on Windows and OpenSSL.
  2. 現在のユーザーの個人証明書ストアに証明書をインストールします。Install the certificate into the current user's personal certificate store. キーをエクスポート可能としてマークすることはオプションです。Marking the key as exportable is optional. このプロセスの後半で使用される証明書の拇印をメモしておきます。Note the certificate's thumbprint, which is used later in this process.
  3. PKCS # 12 アーカイブ (.pfx) 証明書を DER でエンコードされた証明書 (.cer) としてエクスポートします。Export the PKCS#12 archive (.pfx) certificate as a DER-encoded certificate (.cer).
  4. アプリを Azure AD (アプリの登録) に登録します。Register the app with Azure AD (App registrations).
  5. DER でエンコードされた証明書 (.cer) を Azure AD にアップロードします。Upload the DER-encoded certificate (.cer) to Azure AD:
    1. Azure AD でアプリを選択します。Select the app in Azure AD.
    2. [ 証明書 & シークレット] に移動します。Navigate to Certificates & secrets.
    3. 公開キーを含む証明書をアップロードするには、[ 証明書のアップロード ] を選択します。Select Upload certificate to upload the certificate, which contains the public key. .Cerpem、または .crt 証明書を使用できます。A .cer, .pem, or .crt certificate is acceptable.
  6. Key vault 名、アプリケーション ID、証明書の拇印をアプリのファイルに格納し appsettings.json ます。Store the key vault name, Application ID, and certificate thumbprint in the app's appsettings.json file.
  7. Azure portal の キーコンテナー に移動します。Navigate to Key vaults in the Azure portal.
  8. Azure Key Vault セクションで、 運用環境のシークレットストレージ に作成したキーコンテナーを選択します。Select the key vault that you created in the Secret storage in the Production environment with Azure Key Vault section.
  9. [アクセス ポリシー] を選択します。Select Access policies.
  10. [アクセス ポリシーの追加] を選択します。Select Add Access Policy.
  11. [ シークレットのアクセス許可 ] を開き、アプリに Get および List アクセス許可を提供します。Open Secret permissions and provide the app with Get and List permissions.
  12. [ プリンシパルの選択 ] を選択し、名前で登録済みのアプリを選択します。Select Select principal and select the registered app by name. [選択] ボタンを選択します。Select the Select button.
  13. [OK] を選択します。Select OK.
  14. [保存] を選択します。Select Save.
  15. アプリを展開します。Deploy the app.

サンプルアプリでは、 Certificate IConfigurationRoot シークレット名と同じ名前を使用してから構成値を取得します。The Certificate sample app obtains its configuration values from IConfigurationRoot with the same name as the secret name:

  • 非階層値: の値は、 SecretName で取得され config["SecretName"] ます。Non-hierarchical values: The value for SecretName is obtained with config["SecretName"].
  • 階層値 (セクション): : (コロン) 表記または拡張メソッドを使用し GetSection ます。Hierarchical values (sections): Use : (colon) notation or the GetSection extension method. 次のいずれかの方法を使用して、構成値を取得します。Use either of these approaches to obtain the configuration value:
    • config["Section:SecretName"]
    • config.GetSection("Section")["SecretName"]

X.509 証明書は OS によって管理されます。The X.509 certificate is managed by the OS. アプリは AddAzureKeyVault 、ファイルによって指定された値を使用してを呼び出し appsettings.json ます。The app calls AddAzureKeyVault with values supplied by the appsettings.json file:

// using System.Linq;
// using System.Security.Cryptography.X509Certificates;
// using Microsoft.Extensions.Configuration;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                using (var store = new X509Store(StoreLocation.CurrentUser))
                {
                    store.Open(OpenFlags.ReadOnly);
                    var certs = store.Certificates
                        .Find(X509FindType.FindByThumbprint,
                            builtConfig["AzureADCertThumbprint"], false);

                    config.AddAzureKeyVault(
                        $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
                        builtConfig["AzureADApplicationId"],
                        certs.OfType<X509Certificate2>().Single());

                    store.Close();
                }
            }
        })
        .UseStartup<Startup>();

値の例:Example values:

  • Key vault 名: contosovaultKey vault name: contosovault
  • アプリケーション ID: 627e911e-43cc-61d4-992e-12db9c81b413Application ID: 627e911e-43cc-61d4-992e-12db9c81b413
  • 証明書の拇印: fe14593dd66b2406c5269d742d04b6e1ab03adb1Certificate thumbprint: fe14593dd66b2406c5269d742d04b6e1ab03adb1

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name",
  "AzureADApplicationId": "Azure AD Application ID",
  "AzureADCertThumbprint": "Azure AD Certificate Thumbprint"
}

アプリを実行すると、web ページに読み込まれたシークレット値が表示されます。When you run the app, a webpage shows the loaded secret values. 開発環境では、シークレット値はサフィックス付きで読み込ま _dev れます。In the Development environment, secret values load with the _dev suffix. 運用環境では、値はというサフィックスで読み込まれ _prod ます。In the Production environment, the values load with the _prod suffix.

Azure リソースの管理対象 id を使用するUse Managed identities for Azure resources

Azure にデプロイされたアプリ は、 Azure リソースの管理対象 idを利用できます。これにより、アプリは、アプリに格納されている資格情報 (アプリケーション ID とパスワード/クライアントシークレット) を使用せずに Azure AD 認証を使用して Azure Key Vault で認証することができます。An app deployed to Azure can take advantage of Managed identities for Azure resources, which allows the app to authenticate with Azure Key Vault using Azure AD authentication without credentials (Application ID and Password/Client Secret) stored in the app.

このサンプルアプリでは、 #define Program.cs ファイルの先頭にあるステートメントがに設定されている場合に、Azure リソースの管理対象 id を使用し Managed ます。The sample app uses Managed identities for Azure resources when the #define statement at the top of the Program.cs file is set to Managed.

アプリのファイルにコンテナー名を入力し appsettings.json ます。Enter the vault name into the app's appsettings.json file. このサンプルアプリでは、バージョンに設定するときにアプリケーション ID とパスワード (クライアントシークレット) は必要ありません Managed 。そのため、これらの構成エントリは無視してかまいません。The sample app doesn't require an Application ID and Password (Client Secret) when set to the Managed version, so you can ignore those configuration entries. アプリが Azure にデプロイされ、Azure は、ファイルに格納されているコンテナー名を使用してのみ Azure Key Vault にアクセスするようにアプリを認証し appsettings.json ます。The app is deployed to Azure, and Azure authenticates the app to access Azure Key Vault only using the vault name stored in the appsettings.json file.

サンプルアプリを Azure App Service にデプロイします。Deploy the sample app to Azure App Service.

Azure App Service にデプロイされたアプリは、サービスの作成時に Azure AD に自動的に登録されます。An app deployed to Azure App Service is automatically registered with Azure AD when the service is created. 次のコマンドで使用するために、デプロイからオブジェクト ID を取得します。Obtain the Object ID from the deployment for use in the following command. オブジェクト ID は、App Service のパネルの Azure portal に表示され Identity ます。The Object ID is shown in the Azure portal on the Identity panel of the App Service.

Azure CLI とアプリのオブジェクト ID を使用して、 list get キーコンテナーにアクセスするためのアクセス許可とアクセス許可をアプリに付与します。Using Azure CLI and the app's Object ID, provide the app with list and get permissions to access the key vault:

az keyvault set-policy --name {KEY VAULT NAME} --object-id {OBJECT ID} --secret-permissions get list

Azure CLI、PowerShell、または Azure portal を使用して アプリを再起動 します。Restart the app using Azure CLI, PowerShell, or the Azure portal.

サンプルアプリ:The sample app:

  • AzureServiceTokenProvider接続文字列を指定せずに、クラスのインスタンスを作成します。Creates an instance of the AzureServiceTokenProvider class without a connection string. 接続文字列が指定されていない場合、プロバイダーは Azure リソースの管理対象 id からアクセストークンを取得しようとします。When a connection string isn't provided, the provider attempts to obtain an access token from Managed identities for Azure resources.
  • KeyVaultClientインスタンストークンのコールバックを使用して、新しいが作成され AzureServiceTokenProvider ます。A new KeyVaultClient is created with the AzureServiceTokenProvider instance token callback.
  • KeyVaultClientインスタンスは、の既定の実装で使用されます。この実装では、 IKeyVaultSecretManager すべてのシークレット値が読み込まれ、二重ダッシュ ( -- ) がキー名のコロン () に置き換えられ : ます。The KeyVaultClient instance is used with a default implementation of IKeyVaultSecretManager that loads all secret values and replaces double-dashes (--) with colons (:) in key names.
// using Microsoft.Azure.KeyVault;
// using Microsoft.Azure.Services.AppAuthentication;
// using Microsoft.Extensions.Configuration.AzureKeyVault;

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            if (context.HostingEnvironment.IsProduction())
            {
                var builtConfig = config.Build();

                var azureServiceTokenProvider = new AzureServiceTokenProvider();
                var keyVaultClient = new KeyVaultClient(
                    new KeyVaultClient.AuthenticationCallback(
                        azureServiceTokenProvider.KeyVaultTokenCallback));

                config.AddAzureKeyVault(
                    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
                    keyVaultClient,
                    new DefaultKeyVaultSecretManager());
            }
        })
        .UseStartup<Startup>();

Key vault 名の値の例: contosovaultKey vault name example value: contosovault

appsettings.json:appsettings.json:

{
  "KeyVaultName": "Key Vault Name"
}

アプリを実行すると、web ページに読み込まれたシークレット値が表示されます。When you run the app, a webpage shows the loaded secret values. 開発環境では、シークレット値は _dev ユーザーシークレットによって提供されるため、サフィックスが付いています。In the Development environment, secret values have the _dev suffix because they're provided by User Secrets. 運用環境では、値は _prod Azure Key Vault によって提供されるため、サフィックス付きで読み込まれます。In the Production environment, the values load with the _prod suffix because they're provided by Azure Key Vault.

エラーが発生した場合は Access denied 、アプリが Azure AD に登録されていること、およびキーコンテナーへのアクセスが提供されていることを確認します。If you receive an Access denied error, confirm that the app is registered with Azure AD and provided access to the key vault. Azure でサービスを再起動したことを確認します。Confirm that you've restarted the service in Azure.

マネージ id と Azure DevOps パイプラインでプロバイダーを使用する方法の詳細については、「 管理対象サービス id を使用して VM への Azure Resource Manager サービス接続を作成する」を参照してください。For information on using the provider with a managed identity and an Azure DevOps pipeline, see Create an Azure Resource Manager service connection to a VM with a managed service identity.

キー名のプレフィックスを使用するUse a key name prefix

AddAzureKeyVault の実装を受け入れるオーバーロードを提供します IKeyVaultSecretManager 。これにより、キーコンテナーのシークレットを構成キーに変換する方法を制御できます。AddAzureKeyVault provides an overload that accepts an implementation of IKeyVaultSecretManager, which allows you to control how key vault secrets are converted into configuration keys. たとえば、アプリの起動時に指定されたプレフィックス値に基づいてシークレット値を読み込むようにインターフェイスを実装できます。For example, you can implement the interface to load secret values based on a prefix value you provide at app startup. これにより、たとえば、アプリのバージョンに基づいてシークレットを読み込むことができます。This allows you, for example, to load secrets based on the version of the app.

警告

Key vault シークレットのプレフィックスを使用して、複数のアプリのシークレットを同じ key vault に配置したり、環境の機密情報 ( 開発運用 シークレットなど) を同じコンテナーに配置したりしないでください。Don't use prefixes on key vault secrets to place secrets for multiple apps into the same key vault or to place environmental secrets (for example, development versus production secrets) into the same vault. さまざまなアプリと開発/運用環境では、セキュリティレベルが最も高いアプリケーション環境を分離するために個別のキーコンテナーを使用することをお勧めします。We recommend that different apps and development/production environments use separate key vaults to isolate app environments for the highest level of security.

次の例では、キーコンテナー (および開発環境のシークレットマネージャーツールを使用) でシークレットが確立されてい 5000-AppSecret ます (キーコンテナーのシークレット名ではピリオドは使用できません)。In the following example, a secret is established in the key vault (and using the Secret Manager tool for the Development environment) for 5000-AppSecret (periods aren't allowed in key vault secret names). このシークレットは、アプリのバージョン5.0.0.0 のアプリシークレットを表します。This secret represents an app secret for version 5.0.0.0 of the app. アプリの別のバージョンでは、5.1.0.0 は、キーコンテナーに (およびシークレットマネージャーツールを使用して) シークレットを追加し 5100-AppSecret ます。For another version of the app, 5.1.0.0, a secret is added to the key vault (and using the Secret Manager tool) for 5100-AppSecret. 各アプリバージョンは、バージョン管理されたシークレット値をとして構成に読み込み AppSecret ます。これにより、シークレットが読み込まれるときにバージョンが除去されます。Each app version loads its versioned secret value into its configuration as AppSecret, stripping off the version as it loads the secret.

AddAzureKeyVault は、カスタムのを使用して呼び出され IKeyVaultSecretManager ます。AddAzureKeyVault is called with a custom IKeyVaultSecretManager:

config.AddAzureKeyVault(
    $"https://{builtConfig["KeyVaultName"]}.vault.azure.net/",
    builtConfig["AzureADApplicationId"],
    certs.OfType<X509Certificate2>().Single(),
    new PrefixKeyVaultSecretManager(versionPrefix));

実装によって、 IKeyVaultSecretManager シークレットのバージョンプレフィックスに反応し、適切なシークレットが構成に読み込まれます。The IKeyVaultSecretManager implementation reacts to the version prefixes of secrets to load the proper secret into configuration:

  • Load 名前がプレフィックスで始まる場合に、シークレットを読み込みます。Load loads a secret when its name starts with the prefix. 他のシークレットは読み込まれていません。Other secrets aren't loaded.
  • GetKey:GetKey:
    • シークレット名からプレフィックスを削除します。Removes the prefix from the secret name.
    • 任意の名前の2つのダッシュを、 KeyDelimiter 構成で使用される区切り記号 (通常はコロン) で置き換えます。Replaces two dashes in any name with the KeyDelimiter, which is the delimiter used in configuration (usually a colon). Azure Key Vault では、シークレット名にコロンを使用することはできません。Azure Key Vault doesn't allow a colon in secret names.
public class PrefixKeyVaultSecretManager : KeyVaultSecretManager
{
    private readonly string _prefix;

    public PrefixKeyVaultSecretManager(string prefix)
    {
        _prefix = $"{prefix}-";
    }

    public override bool Load(SecretProperties secret)
    {
        return secret.Name.StartsWith(_prefix);
    }

    public override string GetKey(KeyVaultSecret secret)
    {
        return secret.Name
            .Substring(_prefix.Length)
            .Replace("--", ConfigurationPath.KeyDelimiter);
    }
}

この Load メソッドは、コンテナーシークレットを反復処理してバージョンプレフィックスを持つものを検索するプロバイダーアルゴリズムによって呼び出されます。The Load method is called by a provider algorithm that iterates through the vault secrets to find the ones that have the version prefix. バージョンプレフィックスがで見つかった場合 Load 、アルゴリズムは、メソッドを使用して GetKey シークレット名の構成名を返します。When a version prefix is found with Load, the algorithm uses the GetKey method to return the configuration name of the secret name. シークレットの名前からバージョンプレフィックスを取り除き、アプリの構成名と値のペアに読み込むための残りのシークレット名を返します。It strips off the version prefix from the secret's name and returns the rest of the secret name for loading into the app's configuration name-value pairs.

このアプローチが実装されている場合:When this approach is implemented:

  1. アプリのプロジェクトファイルで指定されているアプリのバージョン。The app's version specified in the app's project file. 次の例では、アプリのバージョンがに設定されてい 5.0.0.0 ます。In the following example, the app's version is set to 5.0.0.0:

    <PropertyGroup>
      <Version>5.0.0.0</Version>
    </PropertyGroup>
    
  2. <UserSecretsId>アプリケーションのプロジェクトファイルにプロパティが存在することを確認します。ここで、 {GUID} はユーザー指定の GUID です。Confirm that a <UserSecretsId> property is present in the app's project file, where {GUID} is a user-supplied GUID:

    <PropertyGroup>
      <UserSecretsId>{GUID}</UserSecretsId>
    </PropertyGroup>
    

    シークレットマネージャーツールを使用して、次のシークレットをローカルに保存します。Save the following secrets locally with the Secret Manager tool:

    dotnet user-secrets set "5000-AppSecret" "5.0.0.0_secret_value_dev"
    dotnet user-secrets set "5100-AppSecret" "5.1.0.0_secret_value_dev"
    
  3. シークレットは、次の Azure CLI コマンドを使用して Azure Key Vault に保存されます。Secrets are saved in Azure Key Vault using the following Azure CLI commands:

    az keyvault secret set --vault-name {KEY VAULT NAME} --name "5000-AppSecret" --value "5.0.0.0_secret_value_prod"
    az keyvault secret set --vault-name {KEY VAULT NAME} --name "5100-AppSecret" --value "5.1.0.0_secret_value_prod"
    
  4. アプリを実行すると、key vault シークレットが読み込まれます。When the app is run, the key vault secrets are loaded. の文字列シークレット 5000-AppSecret は、アプリのプロジェクトファイル () で指定されているアプリのバージョンと一致し 5.0.0.0 ます。The string secret for 5000-AppSecret is matched to the app's version specified in the app's project file (5.0.0.0).

  5. バージョン 5000 (ダッシュ付き) は、キー名から削除されます。The version, 5000 (with the dash), is stripped from the key name. アプリ全体で、キーを使用して構成を読み取ると、 AppSecret シークレットの値が読み込まれます。Throughout the app, reading configuration with the key AppSecret loads the secret value.

  6. アプリのバージョンがプロジェクトファイルでに変更され、 5.1.0.0 アプリが再度実行された場合、返されるシークレット値は 5.1.0.0_secret_value_dev 開発環境および 5.1.0.0_secret_value_prod 運用環境にあります。If the app's version is changed in the project file to 5.1.0.0 and the app is run again, the secret value returned is 5.1.0.0_secret_value_dev in the Development environment and 5.1.0.0_secret_value_prod in Production.

注意

また、に独自の実装を提供することもでき KeyVaultClient AddAzureKeyVault ます。You can also provide your own KeyVaultClient implementation to AddAzureKeyVault. カスタムクライアントは、アプリ全体でクライアントの1つのインスタンスを共有することを許可します。A custom client permits sharing a single instance of the client across the app.

配列をクラスにバインドするBind an array to a class

プロバイダーは、POCO 配列にバインドするために、配列に構成値を読み取ることができます。The provider is capable of reading configuration values into an array for binding to a POCO array.

キーにコロン () 区切り記号を含めることができる構成ソースから読み取る場合 : 、配列を構成するキー (、、) を区別するために、数値キーセグメントが使用され :0: :1::{n}: ます。When reading from a configuration source that allows keys to contain colon (:) separators, a numeric key segment is used to distinguish the keys that make up an array (:0:, :1:, … :{n}:). 詳細については、「 構成: 配列をクラスにバインドする」を参照してください。For more information, see Configuration: Bind an array to a class.

Azure Key Vault キーでは、区切り記号としてコロンを使用することはできません。Azure Key Vault keys can't use a colon as a separator. このトピックで説明する方法では、 -- 階層値 (セクション) の区切り記号として二重ダッシュ () を使用します。The approach described in this topic uses double dashes (--) as a separator for hierarchical values (sections). 配列キーは、2つのダッシュと数値のキーセグメント (、、) を使用して Azure Key Vault に格納され --0-- --1----{n}-- ます。Array keys are stored in Azure Key Vault with double dashes and numeric key segments (--0--, --1--, … --{n}--).

JSON ファイルによって提供される次の Serilog logging プロバイダーの構成を確認します。Examine the following Serilog logging provider configuration provided by a JSON file. 次の2つのオブジェクトリテラルが配列に定義されています WriteTo 。この シンク には、ログ出力の宛先が記述されています。There are two object literals defined in the WriteTo array that reflect two Serilog sinks, which describe destinations for logging output:

"Serilog": {
  "WriteTo": [
    {
      "Name": "AzureTableStorage",
      "Args": {
        "storageTableName": "logs",
        "connectionString": "DefaultEnd...ountKey=Eby8...GMGw=="
      }
    },
    {
      "Name": "AzureDocumentDB",
      "Args": {
        "endpointUrl": "https://contoso.documents.azure.com:443",
        "authorizationKey": "Eby8...GMGw=="
      }
    }
  ]
}

前の JSON ファイルに示されている構成は、二重ダッシュ ( -- ) 表記と数値セグメントを使用して Azure Key Vault に格納されます。The configuration shown in the preceding JSON file is stored in Azure Key Vault using double dash (--) notation and numeric segments:

キーKey Value
Serilog--WriteTo--0--Name AzureTableStorage
Serilog--WriteTo--0--Args--storageTableName logs
Serilog--WriteTo--0--Args--connectionString DefaultEnd...ountKey=Eby8...GMGw==
Serilog--WriteTo--1--Name AzureDocumentDB
Serilog--WriteTo--1--Args--endpointUrl https://contoso.documents.azure.com:443
Serilog--WriteTo--1--Args--authorizationKey Eby8...GMGw==

シークレットの再読み込みReload secrets

シークレットは、が呼び出されるまでキャッシュされ IConfigurationRoot.Reload() ます。Secrets are cached until IConfigurationRoot.Reload() is called. が実行されるまで、key vault 内の有効期限切れ、無効、および更新されたシークレットは、アプリで尊重されません ReloadExpired, disabled, and updated secrets in the key vault are not respected by the app until Reload is executed.

Configuration.Reload();

無効なシークレットと期限切れのシークレットDisabled and expired secrets

無効で有効期限が切れたシークレットは、をスローし KeyVaultErrorException ます。Disabled and expired secrets throw a KeyVaultErrorException. アプリがスローされないようにするには、別の構成プロバイダーを使用して構成を提供するか、無効または期限切れのシークレットを更新してください。To prevent the app from throwing, provide the configuration using a different configuration provider or update the disabled or expired secret.

トラブルシューティングTroubleshoot

アプリがプロバイダーを使用した構成の読み込みに失敗すると、エラーメッセージが ASP.NET Core ログ記録インフラストラクチャに書き込まれます。When the app fails to load configuration using the provider, an error message is written to the ASP.NET Core Logging infrastructure. 次の状況では、構成を読み込むことができません。The following conditions will prevent configuration from loading:

  • Azure Active Directory で、アプリまたは証明書が正しく構成されていません。The app or certificate isn't configured correctly in Azure Active Directory.
  • キーコンテナーは Azure Key Vault に存在しません。The key vault doesn't exist in Azure Key Vault.
  • アプリは、key vault にアクセスする権限がありません。The app isn't authorized to access the key vault.
  • アクセスポリシーには Get 、とのアクセス許可は含まれません ListThe access policy doesn't include Get and List permissions.
  • Key vault で、構成データ (名前と値のペア) の名前が正しくないか、存在しないか、無効であるか、または期限が切れています。In the key vault, the configuration data (name-value pair) is incorrectly named, missing, disabled, or expired.
  • アプリの key vault 名 ( KeyVaultName )、Azure AD アプリケーション Id ( AzureADApplicationId )、または Azure AD 証明書の拇印 () が正しくあり AzureADCertThumbprint ません。The app has the wrong key vault name (KeyVaultName), Azure AD Application Id (AzureADApplicationId), or Azure AD certificate thumbprint (AzureADCertThumbprint).
  • 読み込みようとしている値の構成キー (名前) が正しくありません。The configuration key (name) is incorrect in the app for the value you're trying to load.
  • アプリのアクセスポリシーを key vault に追加すると、ポリシーが作成されましたが、アクセスポリシー UI で [保存] ボタンが選択されていませんでした。When adding the access policy for the app to the key vault, the policy was created, but the Save button wasn't selected in the Access policies UI.

その他のリソースAdditional resources