Benutzerdefinierte Authentifizierung in Azure Static Web Apps
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.
Mit der benutzerdefinierten Authentifizierung können Sie auch benutzerdefinierte Anbieter konfigurieren, die OpenID Connect unterstützen. Diese Konfiguration ermöglicht die Registrierung mehrerer externer Anbieter.
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.
Microsoft Entra-Version 1
{
"auth": {
"identityProviders": {
"azureActiveDirectory": {
"userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
"registration": {
"openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>",
"clientIdSettingName": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
}
}
}
}
}
Ersetzen Sie <TENANT_ID> unbedingt durch Ihre Microsoft Entra-Mandanten-ID.
Microsoft Entra-Version 2
{
"auth": {
"identityProviders": {
"azureActiveDirectory": {
"registration": {
"openIdIssuer": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
"clientIdSettingName": "AZURE_CLIENT_ID",
"clientSecretSettingName": "AZURE_CLIENT_SECRET_APP_SETTING_NAME"
}
}
}
}
}
Ersetzen Sie <TENANT_ID> unbedingt durch Ihre Microsoft Entra-Mandanten-ID.
Weitere Informationen zum Konfigurieren von Microsoft Entra ID finden Sie in der Dokumentation zur App Service-Authentifizierung/-Autorisierung zur Verwendung einer vorhandenen Registrierung.
Informationen zum Konfigurieren der Konten, die sich anmelden können, finden Sie unter Ändern der von einer Anwendung unterstützten Konten und Einschränken Ihrer Microsoft Entra-App auf eine Gruppe von Benutzern in einem Microsoft Entra-Mandanten.
Hinweis
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
keyVaultReferenceIdentityfü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
azureActiveDirectorymit einemclientSecretCertificateKeyVaultReference-Wert, wie im folgenden Beispiel gezeigt:{ "auth": { "rolesSource": "/api/GetRoles", "identityProviders": { "azureActiveDirectory": { "userDetailsClaim": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "registration": { "openIdIssuer": "https://login.microsoftonline.com/common/v2.0", "clientIdSettingName": "AZURE_CLIENT_ID", "clientSecretCertificateKeyVaultReference": "@Microsoft.KeyVault(SecretUri=https://<KEY_VAULT_NAME>.azure.net/certificates/<CERTIFICATE_NAME>/<CERTIFICATE_VERSION_ID>)", "clientSecretCertificateThumbprint": "*" } } } } }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
clientSecretCertificateThumbprintauf*fest, um immer die aktuelle Version des Zertifikatfingerabdrucks zu pullen.
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.
| type | URL-Muster |
|---|---|
| Anmelden | https://<YOUR_SITE>/.auth/login/<PROVIDER_NAME_IN_CONFIG>/callback |
| Logout | https://<YOUR_SITE>/.auth/logout/<PROVIDER_NAME_IN_CONFIG>/callback |
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.
Hinzufügen eines Benutzers zu einer Rolle
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.