Używanie odwołań usługi Key Vault jako ustawień aplikacji w usłudze Azure App Service oraz usłudze Azure Functions
Uwaga
Od 1 czerwca 2024 r. nowo utworzone aplikacje usługi App Service mogą wygenerować unikatową domyślną nazwę hosta, która używa konwencji nazewnictwa <app-name>-<random-hash>.<region>.azurewebsites.net. Na przykład: myapp-ds27dh7271aah175.westus-01.azurewebsites.net. Istniejące nazwy aplikacji pozostają niezmienione.
Aby uzyskać więcej informacji, zobacz wpis w blogu dotyczący tworzenia aplikacji internetowej z unikatową domyślną nazwą hosta.
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 wpisami tajnymi, powinny one przejść do magazynu 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.
Utwórz magazyn kluczy, postępując zgodnie z przewodnikiem Szybki start usługi Key Vault.
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.
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:
- Kontrola dostępu oparta na rolach platformy Azure: przypisz rolę Użytkownika wpisów tajnych usługi Key Vault do tożsamości zarządzanej. Aby uzyskać instrukcje, zobacz Zapewnianie dostępu do kluczy, certyfikatów i wpisów tajnych usługi Key Vault przy użyciu kontroli dostępu opartej na rolach platformy Azure.
- Polityka dostępu do magazynu: przypisz uprawnienie Odczytu wpisów tajnych do tożsamości zarządzanej. Aby uzyskać instrukcje, zobacz Przypisywanie zasad dostępu usługi Key Vault.
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 polegać na publicznych adresach IP wychodzących aplikacji, ponieważ adres IP pochodzenia tajemniczego żądania może być inny. Zamiast tego należy skonfigurować magazyn tak, aby akceptował ruch z sieci wirtualnej używanej przez aplikację.
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 --subscription <sub> -g <group-name> -n <app-name> --generic-configurations '{"vnetRouteAllEnabled": true}'Upewnij się, że konfiguracja skarbca zezwala na dostęp do sieci lub podsieci używanej przez Twoją aplikację.
Uzyskiwanie dostępu do magazynów przy użyciu tożsamości przypisanej przez użytkownika
Niektóre aplikacje muszą odwoływać się do tajnych danych w czasie tworzenia, gdy tożsamość przypisana przez system nie jest jeszcze dostępna. W takich przypadkach można utworzyć tożsamość przypisaną przez użytkownika i przyznać jej dostęp do magazynu z wyprzedzeniem.
Po udzieleniu uprawnień tożsamości przypisanej przez użytkownika wykonaj następujące kroki:
Przypisz tożsamość do aplikacji, jeśli jeszcze tego nie zrobiono.
Skonfiguruj aplikację tak, aby korzystała z tej tożsamości dla operacji odniesienia do Key Vault, ustawiając właściwość
keyVaultReferenceIdentityna 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 wpisu tajnego nie jest określona w odwołaniu, aplikacja używa najnowszej wersji, która istnieje w magazynie kluczy. Gdy nowsze wersje stają się dostępne, na przykład przy okazji wydarzenia rotacji, aplikacja zostaje automatycznie zaktualizowana i zaczyna używać 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 pobiera je co 24 godziny. Każda zmiana w konfiguracji aplikacji powoduje jej ponowne uruchomienie i natychmiastowe pobranie wszystkich odwołanych tajemnic.
Informacje o ustawieniach aplikacji źródłowej z usługi Key Vault
Aby użyć odwołania do usługi Key Vault, ustaw odwołanie jako wartość ustawienia. Aplikacja może odwoływać się do tajemnicy za pomocą klucza w normalny sposób. Nie są wymagane żadne zmiany kodu.
Napiwek
Większość ustawień aplikacji korzystających z referencji do Key Vault powinna być oznaczona jako ustawienia dla slotów, ponieważ należy mieć oddzielne magazyny dla każdego środowiska.
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> |
Element SecretUri powinien być pełnym identyfikatorem URI płaszczyzny danych tajemnicy 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 współdzielonych zasobów w usłudze Azure Files i przyjmuje domyślną nazwę, chyba że zostanie ona określona za pośrednictwem ustawienia w WEBSITE_CONTENTSHARE. W przypadku żądań modyfikujących te ustawienia platforma sprawdza, czy ten udział zawartości 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 proces walidacji i ciąg połączenia lub udział zawartości jest nieprawidłowy, aplikacja nie zostanie uruchomiona poprawnie i zwróci 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 dowiedzieć się więcej, 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.
Środowiska portalu dla usług App Service i Azure Functions używają również tych ustawień do przedstawiania danych telemetrycznych z zasobu. Jeśli te wartości pochodzą z usługi Key Vault, te funkcje nie są dostępne i zamiast tego należy korzystać bezpośrednio z zasobu Application Insights, aby wyświetlić dane telemetryczne. Te wartości nie są jednak uznawane za tajemnice, więc można rozważyć ich bezpośrednie skonfigurowanie 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, aby ta funkcja działała. 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ędniliśmy WEBSITE_ENABLE_SYNC_UPDATE_SITE ustawienie aplikacji, aktualizacja jest synchroniczna. Wdrożenie kontroli źródła rozpocznie 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ązywanie 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 stan rozwiązania w portalu. 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.
Możesz również użyć jednego z wbudowanych detektorów, aby uzyskać dodatkowe informacje.
Aby użyć narzędzia do wykrywania dla usługi App Service:
- W portalu przejdź do aplikacji.
- Kliknij pozycję Diagnozowanie i rozwiązywanie problemów.
- Wybierz pozycję Dostępność i wydajność>Awaria aplikacji internetowej.
- 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:
- W portalu przejdź do aplikacji.
- Przejdź do pozycji Funkcje platformy.
- Kliknij pozycję Diagnozowanie i rozwiązywanie problemów.
- Wybierz Dostępność i wydajność>Aplikacja funkcji nie działa lub zgłasza błędy.
- Wybierz pozycję Diagnostyka ustawień aplikacji usługi Key Vault.