Freigeben über

Verwalten der API- und Runtimeversionen der App Service-Authentifizierung

  • Artikel

Dieser Artikel zeigt, wie Sie die API- und Runtimeversionen 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“-Erfahrung im Azure-Portal erforderlich. Eine App, die bereits die V1-API verwendet, kann ein Upgrade auf die V2-Version vornehmen, sobald ein paar Änderungen vorgenommen wurden. Insbesondere muss die Geheimniskonfiguration in slotpersistente Anwendungseinstellungen verschoben werden. Dies kann automatisch über den Abschnitt „Authentifizierung“ im Portal für Ihre App erfolgen.

Aktualisieren der Konfigurationsversion

Warnung

Die Migration zu V2 deaktiviert die Verwaltung des App Service-Authentifizierungs-/Autorisierungsfeatures für Ihre Anwendung durch einige Clients wie das Azure-Portal, die Azure CLI und Azure PowerShell. Dies lässt sich nicht rückgängig machen.

Die V2-API unterstützt kein Erstellen oder Bearbeiten eines Microsoft-Kontos als gesonderten Anbieter, wie es in V1 der Fall war. Stattdessen nutzt sie die konvergierte Microsoft Identity Platform, um Benutzer sowohl mit Microsoft Entra als auch mit persönlichen Microsoft-Konten anzumelden. Wenn Sie zur V2-API wechseln, wird die V1-Konfiguration von Microsoft Entra ID verwendet, um den Microsoft Identity Platform-Anbieter zu konfigurieren. Der Microsoft-Kontoanbieter V1 wird in den Migrationsprozess übernommen und funktioniert weiterhin wie bisher. Sie sollten jedoch zum neueren Microsoft Identity Platform-Modell zu wechseln. Weitere Informationen finden Sie unter Unterstützung für Microsoft-Kontoanbieterregistrierungen.

Beim automatisierten Migrationsvorgang werden Anbietergeheimnisse in Anwendungseinstellungen verschoben, und der Rest der Konfiguration wird in das neue Format konvertiert. So verwenden Sie die automatische Migration

  1. Navigieren Sie im Portal zu Ihrer App, und wählen Sie die Menüoption Authentifizierung aus.
  2. Wenn die App mit dem V1-Modell konfiguriert wurde, wird eine Schaltfläche Aktualisieren angezeigt.
  3. Ü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

Mithilfe der folgenden Schritte können Sie die Anwendung manuell zur V2-API migrieren, wenn Sie nicht die oben genannte automatische Version verwenden möchten.

Verschieben von Geheimnissen in Anwendungseinstellungen

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

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

    Notieren Sie sich aus den resultierenden JSON-Nutzdaten den Geheimniswert für jeden von Ihnen konfigurierten Anbieter:

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

    Wichtig

    Die Geheimniswerte sind wichtige Sicherheitsanmeldeinformationen und sollten sorgfältig behandelt werden. Teilen Sie diese Werte nicht, und speichern Sie sie nicht dauerhaft auf einem lokalen Computer.

  2. Erstellen Sie slotpersistente Anwendungseinstellungen für jeden Geheimniswert. Sie können den Namen jeder einzelnen Anwendungseinstellung auswählen. Ihr Wert sollte dem Wert entsprechen, den Sie im vorherigen Schritt abgerufen haben, oder auf ein Key Vault-Geheimnis verweisen, das Sie mit diesem Wert erstellt haben.

    Um die Einstellung zu erstellen, können Sie das Azure-Portal verwenden oder für jeden Anbieter eine Variation der folgenden Aktionen ausführen:

    # For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_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 <site_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Hinweis

    Die Anwendungseinstellungen für diese Konfiguration müssen als slotpersistent gekennzeichnet werden, was bedeutet, dass Sie während eines Slotaustauschvorgangs nicht zwischen Umgebungen verschoben werden. Der Grund hierfür ist, dass Ihre Authentifizierungskonfiguration selbst an die Umgebung gebunden ist.

  3. Erstellen Sie eine neue JSON-Datei mit dem Namen authsettings.json. Nehmen Sie die Ausgabe, die Sie zuvor erhalten haben, und entfernen Sie daraus jeden Geheimniswert. Schreiben Sie die verbleibende Ausgabe in die Datei, und stellen Sie sicher, dass kein Geheimnis enthalten ist. In einigen Fällen kann die Konfiguration Arrays enthalten, die leere Zeichenfolgen enthalten. Stellen Sie sicher, dass dies auf microsoftAccountOAuthScopes nicht zutrifft, und wenn doch, ändern Sie diesen 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
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Microsoft-Konto: microsoftAccountClientSecretSettingName

    Nach diesem Vorgang könnte eine Beispieldatei etwa wie folgt aussehen, im vorliegenden Fall nur für Microsoft Entra ID konfiguriert:

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/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/0b2ef922-672a-4707-9643-9a5726eec524/",
        "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/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Überprüfen Sie, ob Ihre App nach dieser Geste weiterhin erwartungsgemäß 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.

Unterstützung für Microsoft-Kontoanbieterregistrierungen

Wenn Ihre vorhandene Konfiguration einen Microsoft-Kontoanbieter, aber keinen Microsoft Entra ID-Anbieter enthält, können Sie die Konfiguration auf den Microsoft Entra ID-Anbieter umstellen und dann die Migration durchführen. Gehen Sie dazu folgendermaßen vor:

  1. Wechseln Sie zu App-Registrierungen im Azure-Portal, und suchen Sie die Registrierung, die Ihrem Microsoft-Kontoanbieter zugeordnet ist. Möglicherweise befindet sie sich unter der Überschrift „Anwendungen aus persönlichem Konto“.
  2. Navigieren Sie zur Seite „Authentifizierung“ für die Registrierung. Unter „Umleitungs-URIs“ 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 mit dem soeben kopierten übereinstimmt, außer dass er auf /.auth/login/aad/callback endet. Dies ermöglicht, dass die Registrierung von der Konfiguration der App Service-Authentifizierung/-Autorisierung verwendet werden kann.
  4. Navigieren Sie zu der App Service-Authentifizierungs-/Autorisierungskonfiguration für Ihre App.
  5. Sammeln Sie die Konfiguration für den Microsoft-Kontoanbieter.
  6. Konfigurieren Sie den Microsoft Entra ID-Anbieter mithilfe des Verwaltungsmodus „Erweitert“, wobei Sie die Client-ID und die geheimen Clientschlüsselwerte bereitstellen, die Sie im vorherigen Schritt erfasst haben. Verwenden Sie für die Aussteller-URL <authentication-endpoint>/<tenant-id>/v2.0, und ersetzen Sie <authentication-endpoint> durch den Authentifizierungsendpunkt für Ihre Cloud-Umgebung (z. B. "https://login.microsoftonline.com" für globales Microsoft Entra ID). Ersetzen Sie dabei auch <tenant-id> durch Ihre Verzeichnis-ID (Mandant).
  7. Nachdem Sie die Konfiguration gespeichert haben, testen Sie den Anmeldeablauf, indem Sie in Ihrem Browser zum Endpunkt /.auth/login/aad in Ihrem Standort navigieren und den Anmeldevorgang durchführen.
  8. An diesem Punkt haben Sie die Konfiguration erfolgreich übernommen, aber die vorhandene Konfiguration des Microsoft-Kontoanbieters bleibt erhalten. Bevor Sie sie entfernen, stellen Sie sicher, dass alle Teile Ihrer App über Anmeldelinks auf den Microsoft Entra ID-Anbieter verweisen usw. Vergewissern Sie sich, dass alle Teile Ihrer App erwartungsgemäß funktionieren.
  9. Nachdem Sie überprüft haben, ob der Microsoft Entra ID-Anbieter funktioniert, können Sie die Konfiguration des Microsoft-Kontoanbieters entfernen.

Warnung

Es ist möglich, die beiden Registrierungen durch Ändern der unterstützten Kontotypen für die Microsoft Entra-App-Registrierung zu konvergieren. Dies würde jedoch eine neue Zustimmungsaufforderung für Benutzer von Microsoft-Konten erzwingen, und die Identitätsansprüche dieser Benutzer können sich in der Struktur unterscheiden, weil sub Werte signifikant ändert, da eine neue App-ID verwendet wird. Dieser Ansatz wird nur empfohlen, wenn Sie sich über die Konsequenzen vollkommen bewusst sind. 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 obigen Schritte ausgeführt haben, navigieren Sie im Azure-Portal zu der App. Wählen Sie den Abschnitt „Authentifizierung (Vorschau)“ aus.

Alternativ können Sie eine PUT-Anforderung an die config/authsettingsv2-Ressource unterhalb der Standortressource stellen. Das Schema für die Nutzdaten ist dasselbe wie das im Abschnitt Dateibasierte Konfiguration in Azure App Service-Authentifizierung erfasste.

Anheften Ihrer App an eine bestimmte Authentifizierungsruntimeversion

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 Plattformmiddleware 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 Artikel wird erläutert, wie Sie eine App temporär einer bestimmten Version der Authentifizierungsmiddleware anheften.

Automatische und manuelle Versionsupdates

Sie können Ihre App einer bestimmten Version der Plattformmiddleware anheften, indem Sie eine runtimeVersion-Einstellung für die App vornehmen. Ihre App wird immer auf der neuesten Version ausgeführt, es sei denn, Sie möchten sie explizit einer bestimmten Version anheften. Es werden mehrere Versionen gleichzeitig unterstützt. Wenn Sie sie einer ungültigen Version anheften, die nicht mehr unterstützt wird, verwendet Ihre App stattdessen die neueste Version. Um immer die neueste Version auszuführen, legen Sie runtimeVersion auf ~1 fest.

Anzeigen und Aktualisieren der aktuellen Runtimeversion

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

Anzeigen der aktuellen Runtimeversion

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

Über die Azure CLI

Zeigen Sie mithilfe der Azure CLI die aktuelle Middlewareversion 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 außerdem <my_resource_group> durch den Namen der Ressourcengruppe für Ihre App.

Das Feld runtimeVersion wird in der CLI-Ausgabe angezeigt. Es ähnelt der folgenden Beispielausgabe, die zur besseren Lesbarkeit beschnitten wurde:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Vom Versionsendpunkt

Sie können auch über den /.auth/version-Endpunkt einer App die aktuelle Middlewareversion anzeigen, auf der die App ausgeführt wird. Es ähnelt der folgenden Beispielausgabe:

{
"version": "1.3.2"
}

Aktualisieren der aktuellen Runtimeversion

Mithilfe der Azure CLI können Sie die runtimeVersion-Einstellung in der App mit dem Befehl az webapp auth update 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 außerdem <my_resource_group> durch den Namen der Ressourcengruppe für Ihre App. Ersetzen Sie außerdem <version> durch eine gültige Version der Runtime 1.x oder durch ~1 für die aktuelle Version. Mithilfe der Versionshinweise zu den verschiedenen Runtimeversionen können Sie die Version ermitteln, an die die App angeheftet werden soll.

Sie können diesen Befehl an der Azure Cloud Shell ausführen, indem Sie im vorangehenden Codebeispiel Ausprobieren auswählen. Sie können auch die Azure-Befehlszeilenschnittstelle lokal zum Ausführen dieses Befehls verwenden, nachdem Sie sich mit az login angemeldet haben.

Nächste Schritte

Tutorial: Umfassendes Authentifizieren und Autorisieren von Benutzern in Azure App Service