Verwalten der API- und Runtimeversionen der App Service-Authentifizierung

In diesem Artikel wird beschrieben, wie Sie die API- und Laufzeitversionen der integrierten Authentifizierung und Autorisierung in App Service anpassen.

Es gibt zwei Versionen der Verwaltungs-API für die App Service Authentifizierung. Die V2-Version ist für die Authentifizierung im Azure-Portal erforderlich. Eine App, die bereits die V1-API verwendet, kann ein Upgrade auf die V2-Version durchführen, nachdem einige Änderungen vorgenommen wurden. Insbesondere muss die Geheimniskonfiguration in slotpersistente Anwendungseinstellungen verschoben werden. Sie können die geheime Konfiguration automatisch aus dem Abschnitt "Authentifizierung " Ihrer App im Portal verschieben.

Aktualisieren der Konfigurationsversion

Warnung

Die Migration zu V2 deaktiviert die Verwaltung des App Service-Authentifizierungs-/Autorisierungsfeatures für Ihre Anwendung über einige Clients, z. B. die vorhandene Erfahrung im Azure-Portal, azure CLI und Azure PowerShell. Diese Migration kann nicht rückgängig gemacht werden.

Die V2-API unterstützt nicht das Erstellen oder Bearbeiten eines Microsoft-Kontos als eindeutiger Anbieter wie V1. Stattdessen wird die zusammengeführte Microsoft Identity Platform verwendet, um Benutzer mit Microsoft Entra- und persönlichen Microsoft-Konten anzumelden. Wenn Sie zur V2-API wechseln, wird die V1 Microsoft Entra-Konfiguration verwendet, um den Microsoft Identity Platform-Anbieter zu konfigurieren. Der Microsoft-Kontoanbieter V1 wird im Migrationsprozess weitergeführt und funktioniert weiterhin wie gewohnt, Sie sollten jedoch zum neueren Microsoft Identity Platform-Modell wechseln. Weitere Informationen finden Sie unter Wechseln einer Konfiguration zu einem Microsoft Entra-Anbieter.

Der automatisierte Migrationsprozess verschiebt geheime Anbieterschlüssel in Anwendungseinstellungen und konvertiert dann die restliche Konfiguration in das neue Format. So verwenden Sie die automatische Migration:

  1. Wechseln Sie im Portal zu Ihrer App, und wählen Sie im linken Bereich dieEinstellungsauthentifizierung> aus.
  2. Wenn die App mit dem V1-Modell konfiguriert ist, wird eine Schaltfläche " Upgrade " angezeigt.
  3. Wählen Sie die Schaltfläche Upgrade aus. Überprüfen Sie die Beschreibung in der Bestätigungsaufforderung. Wenn Sie bereit sind, die Migration durchzuführen, klicken Sie in der Eingabeaufforderung auf Upgrade.

Manuelles Verwalten der Migration

Mit den folgenden Schritten können Sie eine Anwendung manuell zur V2-API migrieren, wenn Sie die zuvor beschriebene automatische Version nicht verwenden möchten.

Geheimnisse in Anwendungseinstellungen verschieben

Führen Sie die folgenden Schritte aus, um geheime Identitätsanbieterschlüssel in Anwendungseinstellungen zu verschieben.

  1. Rufen Sie Ihre vorhandene Konfiguration ab, indem Sie die V1-API verwenden:

    az webapp auth show -g <group_name> -n <app_name>

    Notieren Sie sich den für jeden von Ihnen konfigurierten Anbieter verwendeten geheimen Schlüssel aus den resultierenden JSON-Nutzdaten.

    • Microsoft Entra: clientSecret
    • Googeln: googleClientSecret
    • Facebook: facebookAppSecret
    • X: twitterConsumerSecret
    • Microsoft-Konto: microsoftAccountClientSecret

    Wichtig

    Geheime Werte sind wichtige Sicherheitsdaten und sollten sorgfältig behandelt werden. Geben Sie diese Werte nicht weiter oder speichern Sie sie nicht auf einem lokalen Computer.

  2. Erstellen Sie slot-spezifische Anwendungseinstellungen für jeden geheimen Wert. Sie können den Namen jeder Anwendungseinstellung auswählen. Der Wert sollte mit dem Wert übereinstimmen, den Sie im vorherigen Schritt erhalten haben, oder auf einen Azure Key Vault-Geheimschlüssel verweisen , den Sie mit diesem Wert erstellt haben.

    Zum Erstellen der Einstellung können Sie das Azure-Portal verwenden oder eine Variante des folgenden Befehls für jeden Anbieter ausführen:

    # For web apps, Google example    
az webapp config appsettings set -g <group_name> -n <app_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <app_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Hinweis

    Die Anwendungseinstellungen für diese Konfiguration sollten als "slot-sticky" gekennzeichnet werden, was bedeutet, dass sie während eines Slot-Swap-Vorgangs nicht zwischen den Umgebungen verschoben werden. Diese Konfiguration ist erforderlich, da Ihre Authentifizierungskonfiguration an die Umgebung gebunden ist.

  3. Erstellen Sie eine neue JSON-Datei mit dem Namen authsettings.json. Nehmen Sie die zuvor erhaltene Ausgabe und entfernen Sie jeden geheimen Wert daraus. Fügen Sie die verbleibende Ausgabe zur Datei hinzu, und stellen Sie sicher, dass keine Geheimnisse enthalten sind. In einigen Fällen verfügt die Konfiguration möglicherweise über Arrays, die leere Zeichenfolgen enthalten. Stellen Sie sicher, dass microsoftAccountOAuthScopes dies nicht der Fall ist. Ändern Sie in diesem Fall den Wert in null.

  4. Fügen Sie authsettings.json eine Eigenschaft hinzu, die auf den Namen der Anwendungseinstellung verweist, die Sie zuvor für jeden Anbieter erstellt haben:

    • Microsoft Entra: clientSecretSettingName
    • Googeln: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Microsoft-Konto: microsoftAccountClientSecretSettingName

    Eine Einstellungsdatei nach diesem Vorgang sieht möglicherweise ähnlich wie folgt aus, in diesem Fall nur für Microsoft Entra ID konfiguriert:

    {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. Übermitteln Sie diese Datei als neue Authentifizierungs-/Autorisierungskonfiguration für Ihre App:

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Überprüfen Sie, ob Ihre App nach dem Übermitteln der Datei weiterhin wie erwartet funktioniert.

  7. Löschen Sie die in den vorherigen Schritten verwendete Datei.

Sie haben die App nun migriert, um Geheimnisse von Identitätsanbietern als Anwendungseinstellungen zu speichern.

Wechseln einer Konfiguration zu einem Microsoft Entra-Anbieter

Wenn Ihre vorhandene Konfiguration einen Microsoft-Kontoanbieter enthält und keinen Microsoft Entra-Anbieter enthält, können Sie die Konfiguration in den Microsoft Entra-Anbieter ändern und dann die Migration durchführen:

  1. Wechseln Sie im Azure-Portal zu App-Registrierungen , und suchen Sie die Registrierung, die Ihrem Microsoft-Kontoanbieter zugeordnet ist. Möglicherweise befindet sie sich unter der Überschrift "Eigene Anwendungen" .
  2. Wechseln Sie zur Seite "Authentifizierung (Vorschau)" für die Registrierung. Unter Umleitungs-URI sollte ein Eintrag angezeigt werden, der auf /.auth/login/microsoftaccount/callback endet. Kopieren Sie diesen URI.
  3. Fügen Sie einen neuen URI hinzu, der dem soeben kopierten URI entspricht und mit /.auth/login/aad/callback endet. Mit diesem URI kann die Registrierung in der Authentifizierungs-/Autorisierungskonfiguration des App Service verwendet werden.
  4. Wechseln Sie im Portal zu Ihrer App. Wählen Sie Einstellungen>Authentifizierung aus.
  5. Sammeln Sie die Konfiguration für den Microsoft-Kontoanbieter.
  6. Konfigurieren Sie den Microsoft Entra-Anbieter mithilfe des Modus "Erweiterte Verwaltung", und geben Sie die client-ID und die geheimen Clientschlüsselwerte an, die Sie im vorherigen Schritt gesammelt haben. Verwenden Sie für die <authentication-endpoint>/<tenant-id>/v2.0 . Ersetzen Sie den <authentication-endpoint>Authentifizierungsendpunkt für Ihre Cloudumgebung (z. B. "https://login.microsoftonline.com" für globale Microsoft Entra-ID). Ersetzen Sie <tenant-id> durch Ihre Verzeichnis-ID (Mandanten-ID).
  7. Nachdem Sie die Konfiguration gespeichert haben, testen Sie den Anmeldefluss, indem Sie in Ihrem Browser zum /.auth/login/aad Endpunkt auf Ihrer Website navigieren und den Anmeldeablauf abschließen.
  8. An diesem Punkt haben Sie die Konfiguration erfolgreich kopiert, aber die vorhandene Konfiguration des Microsoft-Kontoanbieters bleibt bestehen. Bevor Sie es entfernen, stellen Sie sicher, dass alle Teile Ihrer App über Anmeldelinks usw. auf den Microsoft Entra-Anbieter verweisen. Stellen Sie sicher, dass alle Teile Ihrer App erwartungsgemäß funktionieren.
  9. Nachdem Sie überprüft haben, ob alles mit dem Microsoft Entra-Anbieter funktioniert, können Sie die Konfiguration des Microsoft-Kontoanbieters entfernen.

Warnung

Es ist möglich, die beiden Registrierungen zusammenzuführen, indem sie die unterstützten Kontotypen für die Microsoft Entra-App-Registrierung ändern. Diese Konfiguration würde jedoch eine neue Zustimmungsaufforderung für Microsoft-Kontobenutzer erzwingen, und die Identitätsansprüche dieser Benutzer können sich in der Struktur unterscheiden, insbesondere wenn Werte geändert werden, sub da eine neue App-ID verwendet wird. Wir empfehlen diesen Ansatz nicht, es sei denn, Sie verstehen ihn gründlich. Warten Sie stattdessen lieber, bis Unterstützung für die zwei Registrierungen in der V2-API-Oberfläche bereitgestellt wird.

Wechseln zu V2

Nachdem Sie die vorherigen Schritte ausgeführt haben, wechseln Sie zur App im Azure-Portal. Wählen Sie den Abschnitt "Authentifizierung (Vorschau)" aus.

Alternativ können Sie eine PUT-Anforderung an die config/authsettingsv2-Ressource im Rahmen der Site-Ressource vornehmen. Das Schema für die Nutzlast entspricht der in der dateibasierten Konfiguration erfassten.

Heften Sie Ihre App an eine bestimmte Version der Authentifizierungs-Laufzeitumgebung

Wenn Sie die Authentifizierung/Autorisierung aktivieren, wird die Plattformmiddleware in Ihre HTTP-Anforderungspipeline eingefügt, wie in der Featureübersicht beschrieben. Diese Plattformmiddleware wird im Rahmen der routinemäßigen Plattformupdates in regelmäßigen Abständen mit neuen Features und Verbesserungen aktualisiert. Standardmäßig wird Ihre Web- oder Funktions-App auf der neuesten Version dieser Plattform-Middleware ausgeführt. Diese automatischen Updates sind immer abwärtskompatibel. In dem seltenen Fall, dass dieses automatische Update ein Runtimeproblem bei Ihrer Web- oder Funktions-App verursacht, können Sie jedoch vorübergehend ein Rollback zur vorherigen Middlewareversion ausführen. In diesem Abschnitt wird erläutert, wie Sie eine App vorübergehend an eine bestimmte Version der Authentifizierungs-Middleware anheften.

Automatische und manuelle Versionsupdates

Sie können Ihre App an eine bestimmte Version der Plattform-Middleware anheften, indem Sie eine runtimeVersion Einstellung für die App konfigurieren. Ihre App wird immer auf der neuesten Version ausgeführt, es sei denn, Sie können sie explizit an eine bestimmte Version anheften. Es werden jeweils einige Versionen unterstützt. Wenn Sie eine ungültige Version anheften, die nicht mehr unterstützt wird, verwendet Ihre App stattdessen die neueste Version. Wenn Sie immer die neueste Version ausführen möchten, legen Sie das runtimeVersion fest auf ~1.

Anzeigen und Aktualisieren der aktuellen Runtimeversion

Sie können die von der App verwendete Runtimeversion ändern. Die neue Laufzeitversion sollte nach dem Neustart der App wirksam werden.

Anzeigen der aktuellen Runtimeversion

Sie können die aktuelle Version der Plattformauthentifizierungs-Middleware mithilfe der Azure CLI oder über einen der integrierten HTTP-Endpunkte in Ihrer App anzeigen.

Über die Azure CLI

Zeigen Sie mithilfe der Azure CLI die aktuelle Middleware-Version mit dem Befehl "az webapp auth show" an.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

Ersetzen Sie in diesem Code <my_app_name> durch den Namen der App. Ersetzen Sie <my_resource_group> durch den Namen der Ressourcengruppe Ihrer App.

Das Feld runtimeVersion wird in der CLI-Ausgabe angezeigt. Es ähnelt der folgenden Beispielausgabe, die aus Gründen der Übersichtlichkeit abgeschnitten wird:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Vom Version-Endpoint

Sie können auch auf den Endpunkt "/.auth/version" in einer App klicken, um die aktuelle Middlewareversion anzuzeigen, auf der die App ausgeführt wird. Die Ausgabe sieht in etwa wie folgt aus:

{
"version": "1.3.2"
}

Aktualisieren der aktuellen Runtimeversion

Mit Azure CLI können Sie die runtimeVersion Einstellung in einer App mithilfe des Az webapp-Authentifizierungsaktualisierungsbefehls aktualisieren:

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Ersetzen Sie <my_app_name> durch den Namen Ihrer App. Ersetzen Sie <my_resource_group> durch den Namen der Ressourcengruppe für Ihre App. Ersetzen Sie <version> durch eine gültige Version von 1.x-Laufzeitumgebung, oder verwenden Sie ~1 für die neueste Version. Informationen zum Ermitteln der Version, an die Sie für Azure Functions gebunden werden sollen, finden Sie in der Übersicht über Azure Functions-Laufzeitversionen.

Sie können diesen Befehl über die Azure Cloud Shell ausführen, indem Sie im vorherigen Codebeispiel "Cloud Shell öffnen" auswählen. Sie können die Azure CLI auch lokal verwenden, um diesen Befehl auszuführen, nachdem Sie az login zum Anmelden ausgeführt haben.

Nächster Schritt

Tutorial: End-to-End-Authentifizierung und -Autorisierung von Benutzern

  • Last updated on