App Service と Azure Functions の Key Vault 参照を使用するUse Key Vault references for App Service and Azure Functions

注意

Key Vault 参照は現在、Linux 従量課金プランでは利用できません。Key Vault references are not currently available in Linux consumption plans.

このトピックでは、コードを変更せず、App Service または Azure Functions アプリケーションの Azure Key Vault のシークレットを使用する方法を紹介します。This topic shows you how to work with secrets from Azure Key Vault in your App Service or Azure Functions application without requiring any code changes. Azure Key Vault は、アクセス ポリシーと監査履歴を完全制御する、一元化されたシークレット管理を提供するサービスです。Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Key Vault へのアクセス許可をアプリに付与するGranting your app access to Key Vault

Key Vault からシークレットを読み取るには、Key Vault を作成し、それにアクセスする許可をアプリに与える必要があります。In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Key Vault クイック スタートに従い、Key Vault を作成してください。Create a key vault by following the Key Vault quickstart.

  2. システム割り当てのマネージド ID を自分のアプリケーションのために作成します。Create a system-assigned managed identity for your application.

    注意

    Key Vault 参照では現在のところ、システム割り当てのマネージド ID のみをサポートしています。Key Vault references currently only support system-assigned managed identities. ユーザー割り当て ID は使用できません。User-assigned identities cannot be used.

  3. 先に作成したアプリケーション ID に対して、Key Vault でアクセス ポリシーを作成します。Create an access policy in Key Vault for the application identity you created earlier. このポリシーで "Get" シークレット アクセス許可を有効にします。Enable the "Get" secret permission on this policy. "承認されているアプリケーション" または applicationId 設定を構成しないでください。これは、マネージド ID との互換性がないためです。Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    注意

    Key Vault 参照では現在、ネットワーク制限があるキー コンテナーに格納されているシークレットを解決できません。Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions.

参照構文Reference syntax

Key Vault 参照の形式は @Microsoft.KeyVault({referenceString}) です。{referenceString} は次のいずれかのオプションで置換されます。A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

参照文字列Reference string 説明Description
SecretUri=secretUriSecretUri=secretUri SecretUri は、バージョン (例: https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931 ) を含む、Key Vault におけるシークレットのフル データプレーン URI になります。The SecretUri should be the full data-plane URI of a secret in Key Vault, including a version, e.g., https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
VaultName=vaultName;SecretName=secretName;SecretVersion=secretVersionVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion VaultName は Key Vault リソースの名前になります。The VaultName should the name of your Key Vault resource. SecretName はターゲット シークレットの名前になります。The SecretName should be the name of the target secret. SecretVersion は使用するシークレットのバージョンになります。The SecretVersion should be the version of the secret to use.

たとえば、バージョンを含めた完全な参照は次のようになります。For example, a complete reference with Version would look like the following:

@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931)

あるいは:Alternatively:

@Microsoft.KeyVault(VaultName=myvault;SecretName=mysecret;SecretVersion=ec96f02080254f109c51a1f14cdb1931)

Key Vault からのソース アプリケーション設定Source Application Settings from Key Vault

Key Vault 参照は [アプリケーション設定] の値として使用できます。サイト構成ではなく、Key Vault でシークレットを保存できます。格納中のアプリケーション設定は暗号化されて保護されますが、シークレットの管理機能が必要な場合、Key Vault に進む必要があります。Key Vault references can be used as values for Application Settings, allowing you to keep secrets in Key Vault instead of the site config. Application Settings are securely encrypted at rest, but if you need secret management capabilities, they should go into Key Vault.

アプリケーション設定に Key Vault 参照を使用するには、設定の値として参照を設定します。To use a Key Vault reference for an application setting, set the reference as the value of the setting. アプリは通常どおり、そのキーを利用してシークレットを参照できます。Your app can reference the secret through its key as normal. コードに変更を加える必要はありません。No code changes are required.

ヒント

Key Vault 参照を使用するほとんどのアプリケーション設定は、環境ごとに別個の Key Vault を用意する必要があるため、スロット設定としてマークする必要があります。Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Azure Resource Manager デプロイAzure Resource Manager deployment

Azure Resource Manager テンプレート経由でリソース デプロイを自動化するとき、この機能を動作させるには、場合によっては特定の順序で依存関係を並べる必要があります。When automating resource deployments through Azure Resource Manager templates, you may need to sequence your dependencies in a particular order to make this feature work. 注意すべきことですが、サイト定義の siteConfig プロパティを使用するのではなく、アプリケーション設定を独自のリソースとして定義する必要があります。Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. これはサイトを最初に定義する必要があるからです。そうすることで、サイトと共にシステム割り当て ID が作成され、アクセス ポリシーで使用できます。This is because the site needs to be defined first so that the system-assigned identity is created with it and can be used in the access policy.

Function App の擬似テンプレートの例は次のようになります。An example psuedo-template for a function app might look like the following:

{
    //...
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageAccountName')]",
            //...
        },
        {
            "type": "Microsoft.Insights/components",
            "name": "[variables('appInsightsName')]",
            //...
        },
        {
            "type": "Microsoft.Web/sites",
            "name": "[variables('functionAppName')]",
            "identity": {
                "type": "SystemAssigned"
            },
            //...
            "resources": [
                {
                    "type": "config",
                    "name": "appsettings",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('storageConnectionStringName'))]",
                        "[resourceId('Microsoft.KeyVault/vaults/secrets', variables('keyVaultName'), variables('appInsightsKeyName'))]"
                    ],
                    "properties": {
                        "AzureWebJobsStorage": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringResourceId')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyResourceId')).secretUriWithVersion, ')')]",
                        "WEBSITE_ENABLE_SYNC_UPDATE_SITE": "true"
                        //...
                    }
                },
                {
                    "type": "sourcecontrols",
                    "name": "web",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]",
                        "[resourceId('Microsoft.Web/sites/config', variables('functionAppName'), 'appsettings')]"
                    ],
                }
            ]
        },
        {
            "type": "Microsoft.KeyVault/vaults",
            "name": "[variables('keyVaultName')]",
            //...
            "dependsOn": [
                "[resourceId('Microsoft.Web/sites', variables('functionAppName'))]"
            ],
            "properties": {
                //...
                "accessPolicies": [
                    {
                        "tenantId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').tenantId]",
                        "objectId": "[reference(concat('Microsoft.Web/sites/',  variables('functionAppName'), '/providers/Microsoft.ManagedIdentity/Identities/default'), '2015-08-31-PREVIEW').principalId]",
                        "permissions": {
                            "secrets": [ "get" ]
                        }
                    }
                ]
            },
            "resources": [
                {
                    "type": "secrets",
                    "name": "[variables('storageConnectionStringName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName'))]"
                    ],
                    "properties": {
                        "value": "[concat('DefaultEndpointsProtocol=https;AccountName=', variables('storageAccountName'), ';AccountKey=', listKeys(variables('storageAccountResourceId'),'2015-05-01-preview').key1)]"
                    }
                },
                {
                    "type": "secrets",
                    "name": "[variables('appInsightsKeyName')]",
                    //...
                    "dependsOn": [
                        "[resourceId('Microsoft.KeyVault/vaults/', variables('keyVaultName'))]",
                        "[resourceId('Microsoft.Insights/components', variables('appInsightsName'))]"
                    ],
                    "properties": {
                        "value": "[reference(resourceId('microsoft.insights/components/', variables('appInsightsName')), '2015-05-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

注意

この例では、ソース管理デプロイはアプリケーション設定に依存します。In this example, the source control deployment depends on the application settings. アプリ設定は非同期で更新されるため、通常、これは安全ではありません。This is normally unsafe behavior, as the app setting update behaves asynchronously. しかしながら、WEBSITE_ENABLE_SYNC_UPDATE_SITE アプリケーション設定を含めているため、同期で更新されます。However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. つまり、ソース管理デプロイは、アプリケーションが完全に更新されたときにのみ開始されます。This means that the source control deployment will only begin once the application settings have been fully updated.

Key Vault 参照のトラブルシューティングTroubleshooting Key Vault References

参照が正しく解決されない場合は、代わりに参照値が使用されます。If a reference is not resolved properly, the reference value will be used instead. つまり、アプリケーションの設定では、値の構文が @Microsoft.KeyVault(...) である環境変数が作成されます。This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. この場合に、アプリケーションで特定の構造のシークレットが想定されていると、エラーがスローされることがあります。This may cause the application to throw errors, as it was expecting a secret of a certain structure.

最も一般的な原因は、Key Vault アクセス ポリシーが正しく構成されていないことです。Most commonly, this is due to a misconfiguration of the Key Vault access policy. ただし、シークレットが既に存在していないか、参照自体の構文エラーが原因である可能性もあります。However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

構文が正しい場合は、ポータルで現在の解決状態を確認して、エラーの他の原因を確認できます。If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. [アプリケーションの設定] に移動し、該当する参照の [編集] を選択します。Navigate to Application Settings and select "Edit" for the reference in question. 設定の構成の下には、エラーなどの状態情報が表示されます。Below the setting configuration, you should see status information, including any errors. 表示されない場合は、参照構文が無効であることを意味します。The absence of these implies that the reference syntax is invalid.

組み込みの検出機能のいずれかを使用して、追加情報を取得することもできます。You can also use one of the built-in detectors to get additional information.

App Service の検出機能の使用Using the detector for App Service

  1. ポータルで、アプリに移動します。In the portal, navigate to your app.
  2. [Diagnose and solve prolems](問題の診断と解決) を選択します。Select Diagnose and solve problems.
  3. [Availability and Performance](可用性とパフォーマンス) を選択し、 [Web app down](Web アプリのダウン) を選択します。Choose Availability and Performance and select Web app down.
  4. [Key Vault Application Settings Diagnostics](Key Vault のアプリケーション設定の診断) を見つけて、 [詳細情報] をクリックします。Find Key Vault Application Settings Diagnostics and click More info.

Azure Functions の検出機能の使用Using the detector for Azure Functions

  1. ポータルで、アプリに移動します。In the portal, navigate to your app.
  2. [プラットフォーム機能] に移動します。Navigate to Platform features.
  3. [Diagnose and solve prolems](問題の診断と解決) を選択します。Select Diagnose and solve problems.
  4. [Availability and Performance](可用性とパフォーマンス) を選択し、 [Function app down or reporting errors](関数アプリのダウンまたはエラーの報告) を選択します。Choose Availability and Performance and select Function app down or reporting errors.
  5. [Key Vault Application Settings Diagnostics](Key Vault のアプリケーション設定の診断) をクリックします。Click on Key Vault Application Settings Diagnostics.