Udostępnij za pośrednictwem

Używanie odwołań usługi Key Vault jako ustawień aplikacji w usłudze Azure App Service oraz usłudze Azure Functions

W tym artykule pokazano, jak używać sekretów tajnych z usługi Azure Key Vault jako wartości dla ustawień aplikacji lub parametrów połączenia w ramach aplikacji usługi Azure App Service lub Azure Functions.

Key Vault to usługa, która zapewnia scentralizowane zarządzanie tajemnicami z pełną kontrolą nad zasadami dostępu i historią audytu. Jeśli ustawienie aplikacji lub parametry połączenia są odwołaniem do usługi Key Vault, kod aplikacji może używać go tak jak w przypadku dowolnego innego ustawienia aplikacji lub parametrów połączenia. Dzięki temu można utrzymywać sekrety oddzielnie od konfiguracji aplikacji. Ustawienia aplikacji są bezpiecznie szyfrowane w spoczynku, ale jeśli potrzebujesz możliwości zarządzania tajnymi danymi, powinny być one umieszczone w magazynie kluczy.

Udostępnij aplikacji dostęp do magazynu kluczy

Aby odczytać tajemnice z magazynu kluczy, należy najpierw utworzyć magazyn i nadać Twojej aplikacji uprawnienia do dostępu do magazynu.

  1. Utwórz magazyn kluczy, postępując zgodnie z przewodnikiem Szybki start usługi Key Vault.

  2. Utwórz tożsamość zarządzaną dla aplikacji.

    Odwołania do magazynu kluczy domyślnie używają tożsamości przypisanej przez system aplikacji, ale można określić tożsamość przypisaną przez użytkownika.

  3. Autoryzuj dostęp do odczytu do tajemnic w magazynie kluczy dla utworzonej tożsamości zarządzanej. Jak to zrobisz, zależy od modelu uprawnień w Twoim magazynie kluczy:

Uzyskiwanie dostępu do magazynów z ograniczonym dostępem sieciowym

Jeśli magazyn jest skonfigurowany z ograniczeniami sieciowymi, upewnij się, że aplikacja ma dostęp do sieci. Magazyny nie powinny zależeć od publicznych adresów IP wychodzących aplikacji, ponieważ źródłowy adres IP żądania wpisu tajnego może być inny. Zamiast tego należy skonfigurować skarbiec tak, aby akceptował ruch z sieci wirtualnej, z której korzysta aplikacja.

  1. Upewnij się, że aplikacja ma skonfigurowane możliwości sieci wychodzącej zgodnie z opisem w temacie Funkcje sieciowe usługi App Service i opcje sieciowe usługi Azure Functions.

    Obecnie aplikacje systemu Linux łączące się z prywatnymi punktami końcowymi muszą być jawnie skonfigurowane do kierowania całego ruchu przez sieć wirtualną. Aby skonfigurować to ustawienie, uruchom następujące polecenie:

    az webapp config set --resource-group <group-name>  --subscription <subscription> --name <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'

  2. Upewnij się, że konfiguracja skarbca zezwala na dostęp do sieci lub podsieci używanej przez Twoją aplikację.

Należy pamiętać, że nawet jeśli skrytka została poprawnie skonfigurowana, aby akceptować ruch z sieci wirtualnej, dzienniki inspekcji skrytki mogą wciąż wykazywać błąd (403 — Zabronione) przy próbie SecretGet z publicznego wychodzącego adresu IP aplikacji. Następnie nastąpi pomyślne zdarzenie SecretGet z prywatnego adresu IP aplikacji, co jest zgodne z zamierzeniem.

Uzyskiwanie dostępu do magazynów przy użyciu tożsamości przypisanej przez użytkownika

Niektóre aplikacje muszą odwoływać się do tajemnic podczas tworzenia, gdy tożsamość przypisana przez system nie jest jeszcze dostępna. W takich przypadkach należy najpierw utworzyć tożsamość przypisaną przez użytkownika i nadać jej dostęp do magazynu.

Po nadaniu uprawnień przypisanej przez użytkownika tożsamości, wykonaj następujące kroki:

  1. Przypisz tożsamość do aplikacji.

  2. Skonfiguruj aplikację tak, aby korzystała z tej tożsamości dla operacji odniesienia do Key Vault, ustawiając właściwość keyVaultReferenceIdentity na identyfikator zasobu tożsamości przypisanej użytkownikowi.

    identityResourceId=$(az identity show --resource-group <group-name> --name <identity-name> --query id -o tsv)
az webapp update --resource-group <group-name> --name <app-name> --set keyVaultReferenceIdentity=${identityResourceId}

To ustawienie dotyczy wszystkich odwołań Key Vault dla aplikacji.

Omówienie rotacji

Jeśli wersja sekretu nie jest określona w odniesieniu, aplikacja używa najnowszej wersji, która istnieje w magazynie kluczy. Gdy nowsze wersje staną się dostępne, takie jak rotacja, aplikacja zostanie automatycznie zaktualizowana i rozpocznie korzystanie z najnowszej wersji w ciągu 24 godzin.

Opóźnienie jest spowodowane tym, że usługa App Service buforuje wartości odwołań usługi Key Vault i odświeża je co każde 24 godziny. Każda zmiana w konfiguracji aplikacji powoduje jej ponowne uruchomienie i natychmiastowe pobranie wszystkich odwołanych tajemnic.

Aby wymusić rozstrzygnięcie odwołań aplikacji do Key Vault, utwórz uwierzytelnione żądanie POST do punktu końcowego interfejsu API https://management.azure.com/[Resource ID]/config/configreferences/appsettings/refresh?api-version=2022-03-01.

Informacje o ustawieniach aplikacji źródłowej z usługi Key Vault

Aby użyć referencji do usługi Key Vault, ustaw referencję jako wartość w ustawieniu. Aplikacja może odwoływać się do tajemnicy za pomocą klucza w normalny sposób. Nie są wymagane żadne zmiany kodu.

Napiwek

Ponieważ dla każdego środowiska powinny istnieć oddzielne magazyny, większość ustawień aplikacji wykorzystujących Key Vault powinna być oznaczona jako ustawienia slotu.

Odwołanie do usługi Key Vault ma postać @Microsoft.KeyVault({referenceString}), gdzie {referenceString} znajduje się w jednym z następujących formatów:

Łańcuch referencyjny opis
SecretUri=<secretUri> Powinien SecretUri to być pełny identyfikator URI płaszczyzny danych wpisu tajnego w magazynie. Na przykład https://myvault.vault.azure.net/secrets/mysecret. Opcjonalnie dołącz wersję, taką jak https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931.
VaultName=<vaultName>;SecretName=<secretName>;SecretVersion=<secretVersion> Wartość VaultName jest wymagana i jest nazwą magazynu. Wartość SecretName jest wymagana i jest nazwą tajną. Wartość SecretVersion jest opcjonalna, ale jeśli jest obecna, wskazuje wersję tajemnicy do użycia.

Na przykład pełne odwołanie bez określonej wersji będzie wyglądać podobnie do następującego ciągu:

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

Inna możliwość:

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

Zagadnienia dotyczące instalowania usługi Azure Files

Aplikacje mogą używać WEBSITE_CONTENTAZUREFILECONNECTIONSTRING ustawienia aplikacji do instalowania usługi Azure Files jako systemu plików. To ustawienie zawiera mechanizmy weryfikacji dla zagwarantowania poprawnego uruchomienia aplikacji.

Platforma polega na posiadaniu udziału zawartości w usłudze Azure Files. Platforma zakłada domyślną nazwę, chyba że przy użyciu ustawienia WEBSITE_CONTENTSHARE zostanie określona inna nazwa. W przypadku żądań modyfikujących te ustawienia platforma sprawdza, czy to wspólne użycie zasobów istnieje. Jeśli udostępnienie zawartości nie istnieje, platforma próbuje je utworzyć. Jeśli platforma nie może zlokalizować ani utworzyć współdzielonej zawartości, blokuje żądanie.

Jeśli używasz odwołań do Key Vault w tym ustawieniu, sprawdzanie poprawności domyślnie kończy się niepowodzeniem, ponieważ wpis tajny nie może zostać rozwiązany podczas przetwarzania żądania przychodzącego. Aby uniknąć tego problemu, możesz pominąć walidację, ustawiając wartość WEBSITE_SKIP_CONTENTSHARE_VALIDATION1. To ustawienie informuje usługę App Service o pomijaniu wszystkich sprawdzeń i nie tworzy dla ciebie udziału zawartości. Upewnij się, że udostępnienie treści zostało utworzone z wyprzedzeniem.

Uwaga

Jeśli pominiesz walidację i ciąg połączenia lub udział zawartości jest nieprawidłowy, aplikacja nie uruchamia się poprawnie i tworzy błędy HTTP 500.

W ramach tworzenia aplikacji próba zamontowania udziału zawartości może zakończyć się niepowodzeniem, co może być spowodowane tym, że uprawnienia dla tożsamości zarządzanej nie są propagowane lub możliwości integracji z siecią wirtualną nie są skonfigurowane. Możesz odroczyć konfigurowanie usługi Azure Files do późniejszego użycia w szablonie wdrożenia, aby uwzględnić to zachowanie. Aby uzyskać więcej informacji, zobacz Wdrażanie usługi Azure Resource Manager w dalszej części tego artykułu.

W takim przypadku usługa App Service używa domyślnego systemu plików do momentu skonfigurowania usługi Azure Files, a pliki nie są kopiowane. Musisz upewnić się, że podczas okresu przejściowego przed zamontowaniem usługi Azure Files nie będą podejmowane żadne próby wdrożenia.

Zagadnienia dotyczące instrumentacji usługi Application Insights

Aplikacje mogą używać APPINSIGHTS_INSTRUMENTATIONKEY ustawień aplikacji lub APPLICATIONINSIGHTS_CONNECTION_STRING do integracji z usługą Application Insights.

W przypadku usług App Service i Azure Functions portal Azure również używa tych ustawień do przedstawiania danych telemetrycznych z zasobu. Jeśli te wartości są przywołyne z usługi Key Vault, takie podejście nie jest dostępne. Zamiast tego musisz pracować bezpośrednio z zasobem usługi Application Insights, aby wyświetlić dane telemetryczne. Jednak te wartości nie są uważane za tajemnice, więc można rozważyć ich bezpośrednią konfigurację zamiast używania odwołań do Key Vault.

Wdrożenie usługi Azure Resource Manager

Podczas automatyzowania wdrożeń zasobów za pomocą szablonów usługi Azure Resource Manager może być konieczne sekwencjonowanie zależności w określonej kolejności. Pamiętaj, aby zdefiniować ustawienia aplikacji jako własny zasób, zamiast używać siteConfig właściwości w ramach definicji aplikacji. Aplikacja musi być najpierw zdefiniowana, aby tożsamość przypisana przez system została utworzona za jej pomocą i może być używana w zasadach dostępu.

Poniższy pseudo-szablon jest przykładem tego, jak może wyglądać aplikacja funkcji:

{
    //...
    "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('storageConnectionStringName')).secretUriWithVersion, ')')]",
                        "WEBSITE_CONTENTAZUREFILECONNECTIONSTRING": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('storageConnectionStringName')).secretUriWithVersion, ')')]",
                        "APPINSIGHTS_INSTRUMENTATIONKEY": "[concat('@Microsoft.KeyVault(SecretUri=', reference(variables('appInsightsKeyName')).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(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.tenantId]",
                        "objectId": "[reference(resourceId('Microsoft.Web/sites/', variables('functionAppName')), '2020-12-01', 'Full').identity.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'),'2019-09-01').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')), '2019-09-01').InstrumentationKey]"
                    }
                }
            ]
        }
    ]
}

Uwaga

W tym przykładzie wdrożenie kontroli źródła zależy od ustawień aplikacji. Ta zależność jest zwykle niebezpiecznym zachowaniem, ponieważ aktualizacja ustawień aplikacji zachowuje się asynchronicznie. Jednak ponieważ uwzględniłeś ustawienie aplikacji WEBSITE_ENABLE_SYNC_UPDATE_SITE, aktualizacja jest synchroniczna. Wdrożenie kontroli źródła rozpoczyna się dopiero po pełnym zaktualizowaniu ustawień aplikacji. Aby uzyskać więcej ustawień aplikacji, zobacz Zmienne środowiskowe i ustawienia aplikacji w usłudze aplikacja systemu Azure Service.

Rozwiązanie problemów z odwołaniami do usługi Key Vault

Jeśli odwołanie nie zostanie poprawnie rozpoznane, zamiast tego zostanie użyty ciąg odwołania, na przykład @Microsoft.KeyVault(...). Taka sytuacja może spowodować, że aplikacja zgłasza błędy, ponieważ oczekuje sekretu o innej wartości.

Błąd rozwiązania jest często spowodowany błędną konfiguracją zasad dostępu usługi Key Vault. Przyczyną może być również to, że wpis tajny już nie istnieje lub odwołanie zawiera błąd składniowy.

Jeśli składnia jest poprawna, możesz wyświetlić inne przyczyny błędu, sprawdzając bieżący status rozwiązywania problemów w portalu Azure. Przejdź do Ustawień aplikacji i wybierz Edytuj w odniesieniu do wybranego odwołania. W oknie dialogowym edycji są wyświetlane informacje o stanie, w tym wszelkie błędy. Jeśli nie widzisz komunikatu o stanie, oznacza to, że składnia jest nieprawidłowa i nie jest rozpoznawana jako odwołanie do usługi Key Vault.

Aby uzyskać więcej informacji, możesz również użyć jednego z wbudowanych detektorów.

Aby użyć narzędzia do wykrywania dla usługi App Service:

  1. W witrynie Azure Portal przejdź do aplikacji.
  2. Kliknij pozycję Diagnozowanie i rozwiązywanie problemów.
  3. Wybierz pozycję Dostępność i wydajność>Awaria aplikacji internetowej.
  4. W polu wyszukiwania wyszukaj i wybierz pozycję Diagnostyka ustawień aplikacji usługi Key Vault.

Aby użyć narzędzia do wykrywania dla usługi Azure Functions:

  1. W witrynie Azure Portal przejdź do aplikacji.
  2. Przejdź do pozycji Funkcje platformy.
  3. Kliknij pozycję Diagnozowanie i rozwiązywanie problemów.
  4. Wybierz Dostępność i wydajność>Aplikacja funkcji nie działa lub zgłasza błędy.
  5. Wybierz pozycję Diagnostyka ustawień aplikacji usługi Key Vault.