Benutzerdefinierte Authentifizierung in Azure Static Web Apps
Artikel
Azure Static Web Apps bietet verwaltete Authentifizierung, die von Azure verwaltete Anbieterregistrierungen verwendet. Um mehr Flexibilität bei der Registrierung zu ermöglichen, können Sie die Standardwerte mit einer benutzerdefinierten Registrierung überschreiben.
Wenn Sie benutzerdefinierte Registrierungen verwenden, werden alle vorkonfigurierten Anbieter deaktiviert.
Hinweis
Die benutzerdefinierte Authentifizierung ist nur im Azure Static Web Apps-Standardplan verfügbar.
Konfigurieren eines benutzerdefinierten Identitätsanbieters
Benutzerdefinierte Identitätsanbieter werden im Abschnitt auth der Konfigurationsdatei konfiguriert.
Um zu vermeiden, dass Geheimnisse in die Quellcodeverwaltung aufgenommen werden, sucht die Konfiguration in den Anwendungseinstellungen nach einem übereinstimmenden Namen in der Konfigurationsdatei. Sie können ihre Geheimnisse auch in Azure Key Vault speichern.
Um die Registrierung zu erstellen, müssen Sie zunächst die folgenden Anwendungseinstellungen vornehmen:
Einstellungsname
Wert
AZURE_CLIENT_ID
Die Anwendungs-ID (Client-ID) für die Microsoft Entra-App-Registrierung.
AZURE_CLIENT_SECRET_APP_SETTING_NAME
Der Name der Anwendungseinstellung, die den geheimen Clientschlüssel für die Microsoft Entra-App-Registrierung enthält.
Verwenden Sie als Nächstes das folgende Beispiel, um den Anbieter in der Konfigurationsdatei zu konfigurieren.
Microsoft Entra-Anbieter sind in zwei verschiedenen Versionen verfügbar. Version 1 definiert userDetailsClaim explizit, wodurch in den Nutzdaten Benutzerinformationen zurückgegeben werden können. Im Gegensatz dazu gibt Version 2 standardmäßig Benutzerinformationen zurück und wird durch v2.0 in der openIdIssuer-URL festgelegt.
Während der Konfigurationsabschnitt für Microsoft Entra ID azureActiveDirectory lautet, verwendet die Plattform den Alias aad in den URLs für Anmeldung, Abmeldung und zur Bereinigung von Benutzerinformationen. Weitere Informationen finden Sie im Abschnitt Authentifizierung und Autorisierung.
Benutzerdefiniertes Zertifikat
Führen Sie die folgenden Schritte aus, um Ihrer Microsoft Entra ID-App-Registrierung ein benutzerdefiniertes Zertifikat hinzuzufügen.
Laden Sie Ihr Zertifikat in eine Microsoft Key Vault-Instanz hoch, sofern noch nicht geschehen.
Fügen Sie Ihrer statischen Web-App eine verwaltete Identität hinzu.
Legen Sie für benutzerseitig zugewiesene verwaltete Identitäten die Eigenschaft keyVaultReferenceIdentity für Ihr statisches Websiteobjekt auf die Ressourcen-ID (resourceId) der benutzerseitig zugewiesenen verwalteten Identität fest.
Überspringen Sie diesen Schritt, wenn es sich um eine systemseitig zugewiesene verwaltete Identität handelt.
Gewähren Sie der verwalteten Identität die folgenden Zugriffsrichtlinien:
Geheimnisse: Get/List
Zertifikate: Get/List
Aktualisieren Sie den Authentifizierungskonfigurationsabschnitt des Konfigurationsabschnitts azureActiveDirectory mit einem clientSecretCertificateKeyVaultReference-Wert, wie im folgenden Beispiel gezeigt:
Ersetzen Sie unbedingt die Werte für die Platzhalter in <>.
Geben Sie im geheimen URI den Schlüsseltresornamen und den Zertifikatnamen an. Wenn Sie eine Version anheften möchten, schließen Sie die Zertifikatversion ein. Lassen Sie andernfalls die Version weg, damit die Laufzeit die neueste Version des Zertifikats auswählen kann.
Legen Sie clientSecretCertificateThumbprint auf * fest, um immer die aktuelle Version des Zertifikatfingerabdrucks zu pullen.
Um die Registrierung zu erstellen, müssen Sie zunächst die folgenden Anwendungseinstellungen vornehmen:
Einstellungsname
Wert
APPLE_CLIENT_ID
Die ID des Apple-Clients.
APPLE_CLIENT_SECRET_APP_SETTING_NAME
Der Name der Anwendungseinstellung, die den geheimen Apple-Clientschlüssel enthält.
Verwenden Sie als Nächstes das folgende Beispiel, um den Anbieter in der Konfigurationsdatei zu konfigurieren.
Sie können Azure Static Web Apps für die Verwendung eines benutzerdefinierten Authentifizierungsanbieters konfigurieren, der die OpenID Connect-Spezifikation (OIDC) einhält. Die folgenden Schritte sind erforderlich, um einen benutzerdefinierten OIDC-Anbieter zu verwenden.
Ein oder mehrere OIDC-Anbieter sind zulässig.
Jeder Anbieter muss über einen eindeutigen Namen in der Konfiguration verfügen.
Nur ein Anbieter kann als Standardumleitungsziel dienen.
Registrieren Ihrer Anwendung beim Identitätsanbieter
Sie müssen die Details Ihrer Anwendung bei einem Identitätsanbieter registrieren. Fragen Sie den Anbieter nach den Schritten, die zum Generieren einer Client-ID und eines geheimen Clientschlüssels für Ihre Anwendung erforderlich sind.
Nachdem die Anwendung beim Identitätsanbieter registriert wurde, erstellen Sie die folgenden Anwendungsgeheimnisse in den Anwendungseinstellungen der statischen Web-App:
Einstellungsname
Wert
MY_PROVIDER_CLIENT_ID
Die Client-ID, die vom Authentifizierungsanbieter für Ihre statische Web-App generiert wurde.
MY_PROVIDER_CLIENT_SECRET_APP_SETTING_NAME
Der Name der Anwendungseinstellung, die den geheimen Clientschlüssel enthält, der von der benutzerdefinierten Registrierung des Authentifizierungsanbieters für Ihre statische Web-App generiert wird.
Wenn Sie weitere Anbieter registrieren, benötigt jeder Anbieter eine zugeordnete Client-ID und einen Speicher für geheime Clientschlüssel in den Anwendungseinstellungen.
Wichtig
Anwendungsgeheimnisse sind vertrauliche Sicherheitsanmeldeinformationen. Teilen Sie dieses Geheimnis mit niemandem, verteilen Sie es in keiner Clientanwendung, und checken Sie es nicht in die Quellcodeverwaltung ein.
Sobald Sie über die Anmeldeinformationen für die Registrierung verfügen, erstellen Sie mithilfe der folgenden Schritte eine benutzerdefinierte Registrierung.
Sie benötigen die OpenID Connect-Metadaten für den Anbieter. Diese Informationen werden häufig über ein Konfigurationsmetadatendokument zur Verfügung gestellt, bei dem es sich um die Aussteller-URL des Anbieters mit dem Suffix /.well-known/openid-configuration handelt. Erfassen Sie diese Konfigurations-URL.
Fügen Sie der Konfigurationsdatei einen auth-Abschnitt mit einem Konfigurationsblock für die OIDC-Anbieter und Ihre Anbieterdefinition hinzu.
Der Anbietername, in diesem Beispiel myProvider, ist der eindeutige Bezeichner, der von Azure Static Web Apps verwendet wird.
Stellen Sie sicher, <PROVIDER_ISSUER_URL> durch den Pfad zur Aussteller-URL des Anbieters zu ersetzen.
Mit dem login-Objekt können Sie Werte für benutzerdefinierte Bereiche, Anmeldeparameter oder benutzerdefinierte Ansprüche angeben.
Authentifizierungsrückrufe
Identitätsanbieter benötigen zur Ausführung von Anmeldungs- oder Abmeldungsanforderungen eine Umleitungs-URL. Die meisten Anbieter erfordern, dass Sie die Rückruf-URLs einer Zulassungsliste hinzufügen. Die folgenden Endpunkte sind als Umleitungsziele verfügbar.
Wenn Sie Microsoft Entra ID verwenden, geben Sie aad als Wert für den Platzhalter <PROVIDER_NAME_IN_CONFIG> an.
Hinweis
Diese URLs werden von Azure Static Web Apps bereitgestellt, um die Antwort vom Authentifizierungsanbieter zu empfangen. Sie müssen keine Seiten auf diesen Routen erstellen.
Anmeldung, Abmeldung und Benutzerdetails
Um einen benutzerdefinierten Identitätsanbieter zu verwenden, verwenden Sie die folgenden URL-Muster.
Aktion
Muster
Anmelden
/.auth/login/<PROVIDER_NAME_IN_CONFIG>
Logout
/.auth/logout
Benutzerdetails
/.auth/me
Bereinigen von Benutzerdetails
/.auth/purge/<PROVIDER_NAME_IN_CONFIG>
Wenn Sie Microsoft Entra ID verwenden, geben Sie aad als Wert für den Platzhalter <PROVIDER_NAME_IN_CONFIG> an.
Rollen verwalten
Jeder Benutzer, der auf eine statische Web-App zugreift, gehört mindestens einer Rolle an. Benutzer können zwei integrierten Rollen angehören:
anonymous: Alle Benutzer gehören automatisch der Rolle anonymous an.
authenticated: Alle Benutzer, die angemeldet sind, gehören der Rolle authenticated an.
Zusätzlich zu den integrierten Rollen können Sie Benutzern benutzerdefinierte Rollen zuweisen und in der Datei staticwebapp.config.json darauf verweisen.
Um einen Benutzer zu einer Rolle hinzuzufügen, generieren Sie Einladungen, mit denen Sie Benutzer bestimmten Rollen zuordnen können. Rollen werden in der Datei staticwebapp.config.json definiert und verwaltet.
Einladung erstellen
Einladungen gelten spezifisch für einzelne Autorisierungsanbieter. Aus diesem Grund sollten Sie die Anforderungen Ihrer App beachten, wenn Sie die zu unterstützenden Anbieter auswählen. Einige Anbieter legen die E-Mail-Adresse eines Benutzers offen, während andere nur den Benutzernamen für die Website angeben.
Autorisierungsanbieter
Verfügbar gemacht
Microsoft Entra ID
E-Mail-Adresse
GitHub
username
X
username
Führen Sie die folgenden Schritte aus, um eine Einladung zu erstellen.
Navigieren Sie im Azure-Portal zu einer Static Web Apps-Ressource.
Wählen Sie unter Einstellungen die Option Rollenverwaltung aus.
Wählen Sie Einladen aus.
Wählen Sie in der Liste mit den Optionen den Eintrag Autorisierungsanbieter aus.
Fügen Sie im Feld Invitee details (Details zum Eingeladenen) den Benutzernamen oder die E-Mail-Adresse des Empfängers hinzu.
Geben Sie bei GitHub und X den Benutzernamen ein. Geben Sie für alle anderen Anbieter die E-Mail-Adresse des Empfängers ein.
Wählen Sie im Dropdownmenü Domäne die Domäne Ihrer statischen Website aus.
Die von Ihnen ausgewählte Domäne ist die Domäne, die in der Einladung angezeigt wird. Falls Ihrer Website eine benutzerdefinierte Domäne zugeordnet ist, wählen Sie die benutzerdefinierte Domäne aus.
Fügen Sie im Feld Rolle eine Liste mit Rollennamen (durch Kommas getrennt) ein.
Geben Sie die Anzahl von Stunden für die maximale Gültigkeitsdauer der Einladung ein.
Die Obergrenze beträgt 168 Stunden (sieben Tage).
Wählen Sie Generieren aus.
Kopieren Sie den Link aus dem Feld Einladungslink.
Senden Sie eine E-Mail mit dem Einladungslink an den Benutzer, dem Sie Zugriff gewähren möchten.
Wenn der Benutzer in der Einladung den Link auswählt, wird er aufgefordert, sich mit seinem entsprechenden Konto anzumelden. Nach der erfolgreichen Anmeldung wird der Benutzer den ausgewählten Rollen zugeordnet.
Achtung
Stellen Sie sicher, dass Ihre Routenregeln nicht in Konflikt mit Ihren ausgewählten Authentifizierungsanbietern stehen. Wenn ein Anbieter durch eine Routenregel blockiert wird, können Benutzer keine Einladungen akzeptieren.
Aktualisieren von Rollenzuweisungen
Navigieren Sie im Azure-Portal zu einer Static Web Apps-Ressource.
Wählen Sie unter Einstellungen die Option Rollenverwaltung aus.
Wählen Sie den Benutzer aus der Liste aus.
Bearbeiten Sie die Liste mit den Rollen im Feld Rolle.
Wählen Sie Aktualisieren.
Benutzer entfernen
Navigieren Sie im Azure-Portal zu einer Static Web Apps-Ressource.
Wählen Sie unter Einstellungen die Option Rollenverwaltung aus.
Suchen Sie in der Liste nach dem Benutzer.
Aktivieren Sie das Kontrollkästchen in der Zeile des Benutzers.
Klicken Sie auf Löschen.
Beachten Sie beim Entfernen eines Benutzers Folgendes:
Wenn ein Benutzer entfernt wird, werden seine Berechtigungen ungültig.
Die weltweite Verteilung kann einige Minuten dauern.
Wenn der Benutzer wieder der App hinzugefügt wird, ändert sich die userId.
Anstatt des integrierten Einladungssystems können Sie eine serverlose Funktion verwenden, um Benutzern bei der Anmeldung programmgesteuert Rollen zuzuweisen.
Um benutzerdefinierte Rollen in einer Funktion zuzuweisen, können Sie eine API-Funktion definieren, die nach jeder erfolgreichen Authentifizierung eines Benutzers bei einem Identitätsanbieter automatisch aufgerufen wird. Der Funktion werden die Benutzerinformationen vom Anbieter übergeben. Sie muss eine Liste benutzerdefinierter Rollen zurückgeben, die dem Benutzer zugewiesen werden.
Beispiele für die Verwendung dieser Funktion sind:
Abfragen einer Datenbank, um zu bestimmen, welche Rollen einem Benutzer zugewiesen werden sollen
Aufrufen der Microsoft Graph-API, um die Rollen eines Benutzers basierend auf seiner Active Directory-Gruppenmitgliedschaft zu bestimmen
Bestimmen der Rollen eines Benutzers basierend auf Ansprüchen, die vom Identitätsanbieter zurückgegeben werden
Wenn dieses Feature aktiviert ist, werden alle über das integrierte Einladungssystem zugewiesenen Rollen ignoriert.
Konfigurieren einer Funktion zum Zuweisen von Rollen
Um Azure Static Web Apps für die Verwendung einer API-Funktion als Funktion für die Zuweisung von Rollen zu konfigurieren, fügen Sie dem Abschnitt auth der Konfigurationsdatei Ihrer App eine rolesSource-Eigenschaft hinzu. Der Wert der rolesSource-Eigenschaft ist der Pfad zur API-Funktion.
Nach der Konfiguration kann von externen HTTP-Anforderungen nicht mehr auf die Rollenzuweisungsfunktion zugegriffen werden.
Erstellen einer Funktion zum Zuweisen von Rollen
Nachdem Sie die rolesSource-Eigenschaft in der Konfiguration Ihrer App definiert haben, fügen Sie in Ihrer statischen Web-App unter dem angegebenen Pfad eine API-Funktion hinzu. Sie können eine verwaltete Funktions-App oder eine eigene Funktions-App verwenden.
Jedes Mal, wenn sich ein Benutzer erfolgreich bei einem Identitätsanbieter authentifiziert, ruft die POST-Methode die angegebene Funktion auf. Der Funktion übergibt im Anforderungstext ein JSON-Objekt, das die Informationen des Benutzers vom Anbieter enthält. Bei einigen Identitätsanbietern enthalten die Benutzerinformationen auch ein accessToken-Objekt, das die Funktion verwenden kann, um API-Aufrufe mit der Benutzeridentität vorzunehmen.
Sehen Sie sich die folgende Beispielnutzlast von Microsoft Entra ID an:
Die Funktion kann anhand der Benutzerinformationen bestimmen, welche Rollen dem Benutzer zugewiesen werden sollen. Sie muss eine HTTP 200-Antwort mit einem JSON-Text zurückgeben, der eine Liste benutzerdefinierter Rollennamen enthält, die dem Benutzer zugewiesen werden sollen.
Um dem Benutzer z. B. die Rollen Reader und Contributor zuzuweisen, geben Sie die folgende Antwort zurück:
{
"roles": [
"Reader",
"Contributor"
]
}
Wenn Sie dem Benutzer keine weiteren Rollen zuweisen möchten, geben Sie ein leeres roles-Array zurück.
Veröffentlichen Sie eine Angular-, React-, Svelte- oder Vue-JavaScript-Anwendung mit API und Authentifizierung mithilfe von Azure Static Web Apps und Azure Functions. Stellen Sie Ihren Code über GitHub mithilfe von Vorschau-URLs auf einer Stagingwebsite bereit.
Veranschaulichen der Features von Microsoft Entra ID, um Identitätslösungen zu modernisieren sowie Hybridlösungen und Identitätsgovernance zu implementieren