Użyj Key Vault odwołań dla App Service i Azure FunctionsUse Key Vault references for App Service and Azure Functions

Uwaga

Odwołania Key Vault nie są obecnie dostępne w planach zużycia systemu Linux.Key Vault references are not currently available in Linux consumption plans.

W tym temacie przedstawiono sposób pracy z wpisami tajnymi Azure Key Vault w App Service lub Azure Functions aplikacji bez konieczności wprowadzania jakichkolwiek zmian w kodzie.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 to usługa zapewniająca scentralizowane zarządzanie kluczami tajnymi z pełną kontrolą nad zasadami dostępu i historią inspekcji.Azure Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history.

Udzielanie aplikacji dostępu do Key VaultGranting your app access to Key Vault

Aby można było odczytać wpisy tajne z Key Vault, należy utworzyć magazyn i nadać aplikacji uprawnienia dostępu do niej.In order to read secrets from Key Vault, you need to have a vault created and give your app permission to access it.

  1. Utwórz magazyn kluczy, postępując zgodnie z przewodnikiem Szybki start Key Vault.Create a key vault by following the Key Vault quickstart.

  2. Utwórz skojarzoną z systemem tożsamość zarządzaną dla aplikacji.Create a system-assigned managed identity for your application.

    Uwaga

    Odwołania Key Vault obecnie obsługują tylko tożsamości zarządzane przypisane do systemu.Key Vault references currently only support system-assigned managed identities. Nie można używać tożsamości przypisanych do użytkownika.User-assigned identities cannot be used.

  3. Utwórz zasady dostępu w Key Vault dla utworzonej wcześniej tożsamości aplikacji.Create an access policy in Key Vault for the application identity you created earlier. Włącz uprawnienie "Pobieranie" klucza tajnego dla tych zasad.Enable the "Get" secret permission on this policy. Nie należy konfigurować ustawień "autoryzowane aplikacje" ani applicationId, ponieważ nie są one zgodne z zarządzaną tożsamością.Do not configure the "authorized application" or applicationId settings, as this is not compatible with a managed identity.

    Uwaga

    Odwołania Key Vault nie są obecnie dostępne do rozpoznawania wpisów tajnych przechowywanych w magazynie kluczy z ograniczeniami sieci.Key Vault references are not presently able to resolve secrets stored in a key vault with network restrictions.

Składnia odwołaniaReference syntax

Odwołanie Key Vault ma postać @Microsoft.KeyVault({referenceString}), gdzie {referenceString} jest zastępowana jedną z następujących opcji:A Key Vault reference is of the form @Microsoft.KeyVault({referenceString}), where {referenceString} is replaced by one of the following options:

Ciąg odwołaniaReference string OpisDescription
SecretUri =SecretUriSecretUri=secretUri SecretUri powinien być pełnym identyfikatorem URI płaszczyzny danych klucza tajnego w Key Vault, w tym wersji, np., https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931The 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
Magazynname =magazynname; Secretname =secretname; Wersjawpisutajnego =wersjawpisutajnegoVaultName=vaultName;SecretName=secretName;SecretVersion=secretVersion Nazwa magazynu powinna być nazwą zasobu Key Vault.The VaultName should the name of your Key Vault resource. Wpis tajny musi być nazwą docelowego wpisu tajnego.The SecretName should be the name of the target secret. Wersjawpisutajnego powinna być wersją klucza tajnego do użycia.The SecretVersion should be the version of the secret to use.

Na przykład kompletne odwołanie z wersją będzie wyglądać następująco:For example, a complete reference with Version would look like the following:

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

AlternatywneAlternatively:

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

Ustawienia aplikacji źródłowej z Key VaultSource Application Settings from Key Vault

Odwołania Key Vault mogą być używane jako wartości ustawień aplikacji, co pozwala zachować wpisy tajne w Key Vault zamiast konfiguracji lokacji. Ustawienia aplikacji są bezpiecznie szyfrowane w stanie spoczynku, ale jeśli potrzebujesz funkcji tajnego zarządzania, należy przejść do 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.

Aby użyć odwołania Key Vault dla ustawienia aplikacji, należy ustawić odwołanie jako wartość ustawienia.To use a Key Vault reference for an application setting, set the reference as the value of the setting. Twoja aplikacja może odwoływać się do klucza tajnego za pomocą jego klucza jako normalnego.Your app can reference the secret through its key as normal. Nie są wymagane żadne zmiany w kodzie.No code changes are required.

Porada

Większość ustawień aplikacji używających odwołań Key Vault powinna być oznaczona jako ustawienia miejsca, ponieważ dla każdego środowiska należy mieć oddzielne magazyny.Most application settings using Key Vault references should be marked as slot settings, as you should have separate vaults for each environment.

Wdrożenie usługi Azure Resource ManagerAzure Resource Manager deployment

W przypadku automatyzowania wdrożeń zasobów za pomocą szablonów Azure Resource Manager może być konieczne sekwencjonowanie zależności w określonej kolejności, aby ta funkcja działała.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. Pamiętaj, że musisz zdefiniować ustawienia aplikacji jako własny zasób zamiast używać właściwości siteConfig w definicji lokacji.Of note, you will need to define your application settings as their own resource, rather than using a siteConfig property in the site definition. Wynika to z faktu, że lokacja musi być zdefiniowana jako pierwsza, aby można było utworzyć tożsamość przypisaną do systemu i użyć jej w zasadach dostępu.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.

Przykład psuedo-Template dla aplikacji funkcji może wyglądać następująco: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]"
                    }
                }
            ]
        }
    ]
}

Uwaga

W tym przykładzie wdrożenie kontroli źródła zależy od ustawień aplikacji.In this example, the source control deployment depends on the application settings. Jest to zwykle niebezpieczne zachowanie, ponieważ aktualizacja ustawienia aplikacji zachowuje się asynchronicznie.This is normally unsafe behavior, as the app setting update behaves asynchronously. Ponieważ jednak zostały dołączone WEBSITE_ENABLE_SYNC_UPDATE_SITE ustawienie aplikacji, aktualizacja jest synchroniczna.However, because we have included the WEBSITE_ENABLE_SYNC_UPDATE_SITE application setting, the update is synchronous. Oznacza to, że wdrożenie kontroli źródła rozpocznie się dopiero po całkowitym zaktualizowaniu ustawień aplikacji.This means that the source control deployment will only begin once the application settings have been fully updated.

Rozwiązywanie problemów dotyczących Key VaultTroubleshooting Key Vault References

Jeśli odwołanie nie zostanie prawidłowo rozwiązane, zamiast tego zostanie użyta wartość referencyjna.If a reference is not resolved properly, the reference value will be used instead. Oznacza to, że dla ustawień aplikacji zostanie utworzona zmienna środowiskowa, której wartość ma składnię @Microsoft.KeyVault(...).This means that for application settings, an environment variable would be created whose value has the @Microsoft.KeyVault(...) syntax. Może to spowodować, że aplikacja zgłosi błędy, ponieważ oczekuje ona wpisu tajnego określonej struktury.This may cause the application to throw errors, as it was expecting a secret of a certain structure.

Najczęściej jest to spowodowane niepoprawną konfiguracją zasad dostępu Key Vault.Most commonly, this is due to a misconfiguration of the Key Vault access policy. Jednak może być również przyczyną, że wpis tajny nie jest już istniejący lub błąd składniowy w samej odwołaniu.However, it could also be due to a secret no longer existing or a syntax error in the reference itself.

Jeśli składnia jest poprawna, można wyświetlić inne przyczyny błędu, sprawdzając bieżący stan rozwiązania w portalu.If the syntax is correct, you can view other causes for error by checking the current resolution status in the portal. Przejdź do ustawień aplikacji i wybierz pozycję "Edytuj" dla odnośnego odwołania.Navigate to Application Settings and select "Edit" for the reference in question. Na stronie Konfiguracja ustawienia powinny być widoczne informacje o stanie, w tym wszelkie błędy.Below the setting configuration, you should see status information, including any errors. Brak tych informacji oznacza, że Składnia odwołania jest nieprawidłowa.The absence of these implies that the reference syntax is invalid.

Możesz również użyć jednego z wbudowanych detektorów, aby uzyskać dodatkowe informacje.You can also use one of the built-in detectors to get additional information.

Używanie narzędzia wykrywania dla App ServiceUsing the detector for App Service

  1. W portalu przejdź do swojej aplikacji.In the portal, navigate to your app.
  2. Wybierz pozycję Diagnozuj i rozwiąż problemy.Select Diagnose and solve problems.
  3. Wybierz pozycję dostępność i wydajność , a następnie wybierz pozycję aplikacja internetowa.Choose Availability and Performance and select Web app down.
  4. Znajdź Key Vault Diagnostyka ustawień aplikacji i kliknij pozycję więcej informacji.Find Key Vault Application Settings Diagnostics and click More info.

Używanie narzędzia wykrywania dla Azure FunctionsUsing the detector for Azure Functions

  1. W portalu przejdź do swojej aplikacji.In the portal, navigate to your app.
  2. Przejdź do opcji platformy.Navigate to Platform features.
  3. Wybierz pozycję Diagnozuj i rozwiąż problemy.Select Diagnose and solve problems.
  4. Wybierz opcję dostępność i wydajność , a następnie wybierz pozycję aplikacja funkcjonalna lub raportowanie błędów.Choose Availability and Performance and select Function app down or reporting errors.
  5. Kliknij pozycję Key Vault Diagnostyka ustawień aplikacji.Click on Key Vault Application Settings Diagnostics.