Freigeben über

Konfigurieren eines Anbieters von benutzerdefinierten Ansprüchen für ein Tokenausstellungsereignis

  • Artikel

In diesem Artikel wird beschrieben, wie Sie einen benutzerdefinierten Anspruchsanbieter für ein Startereignis der Token-Ausgabe konfigurieren. Mithilfe einer vorhandenen Rest-API für Azure Functions registrieren Sie eine benutzerdefinierte Authentifizierungserweiterung und fügen Attribute hinzu, die von Ihrer REST-API analysiert werden sollen. Zum Testen der benutzerdefinierten Authentifizierungserweiterung registrieren Sie eine OpenID Connect-Beispielanwendung, um ein Token abzurufen und die Ansprüche anzuzeigen.

Voraussetzungen

Schritt 1: Registrieren einer benutzerdefinierten Authentifizierungserweiterung

Sie konfigurieren eine benutzerdefinierte Authentifizierungserweiterung, die von Microsoft Entra ID zum Aufrufen Ihrer Azure-Funktion verwendet wird. Die benutzerdefinierte Authentifizierungserweiterung enthält Informationen zu Ihrem REST-API-Endpunkt, zu den aus Ihrer REST-API geparsten Ansprüchen sowie zur Authentifizierung bei Ihrer REST-API. Führen Sie die folgenden Schritte aus, um eine benutzerdefinierte Authentifizierungserweiterung für Ihre Azure Function-App zu registrieren.

Hinweis

Sie können maximal 100 benutzerdefinierte Erweiterungsrichtlinien verwenden.

Registrieren einer benutzerdefinierten Authentifizierungserweiterung

  1. Melden Sie sich beim Azure-Portal mindestens mit der Rolle Anwendungsadministrator und Authentifizierungsadministrator an.
  2. Suchen Und wählen Sie Microsoft Entra-ID und Enterprise-Anwendungen aus.
  3. Wählen Sie Benutzerdefinierte Authentifizierungserweiterungen und dann Benutzerdefinierte Erweiterung erstellen aus.
  4. Wählen Sie unter Grundeinstellungen den Ereignistyp TokenIssuanceStart aus, und wählen Sie dann Weiter aus.
  5. Füllen Sie unter Endpunktkonfiguration die folgenden Eigenschaften aus:
    • Name – Ein Name für Ihre benutzerdefinierte Authentifizierungserweiterung. Beispielsweise Tokenausstellungsereignis.
    • Ziel-URL: Die {Function_Url} Ihrer Azure-Funktions-URL. Navigieren Sie zur Seite Übersicht Ihrer Azure Function-App, und wählen Sie dann die von Ihnen erstellte Funktion aus. Wählen Sie auf der Seite Funktionsübersicht die Option Funktions-URL abrufen aus, und verwenden Sie das Kopiersymbol, um die URL customauthenticationextension_extension (Systemschlüssel) zu kopieren.
    • Beschreibung – Eine Beschreibung für Ihre benutzerdefinierten Authentifizierungserweiterungen.
  6. Wählen Sie Weiter aus.
  7. Wählen Sie unter API-Authentifizierung die Option Neue App-Registrierung erstellen aus, um eine App-Registrierung zu erstellen, die Ihre Funktions-App darstellt.
  8. Weisen Sie der App einen Namen zu, z. B. Azure Functions-Authentifizierungsereignis-API.
  9. Wählen Sie Weiter aus.
  10. Geben Sie unter Ansprüche die Attribute ein, die Ihre benutzerdefinierte Authentifizierungserweiterung aus Ihrer REST-API parsen soll und die im Token zusammengeführt werden. Fügen Sie die folgenden Ansprüche hinzu:
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. Wählen Sie Weiter und dann Erstellen aus, wodurch die benutzerdefinierte Authentifizierungserweiterung und die zugehörige Anwendungsregistrierung registriert werden.
  12. Beachten Sie die App-ID unter API-Authentifizierung, die zum Konfigurieren der Authentifizierung für Ihre Azure Function in Ihrer Azure Function-App erforderlich ist.

Nachdem Ihre benutzerdefinierte Authentifizierungserweiterung erstellt wurde, müssen Sie der API Berechtigungen erteilen. Die benutzerdefinierte Authentifizierungserweiterung verwendet client_credentials für die Authentifizierung bei der Azure-Funktions-App mit der Berechtigung Receive custom authentication extension HTTP requests.

  1. Öffnen Sie die Seite Übersicht der neuen benutzerdefinierten Authentifizierungserweiterung. Notieren Sie sich die App-ID unter API-Authentifizierung, da sie beim Hinzufügen eines Identitätsanbieters erforderlich ist.

  2. Wählen Sie unter API-Authentifizierung die Option Berechtigung erteilen aus.

  3. Ein neues Fenster wird geöffnet. Nach der Anmeldung werden Berechtigungen zum Empfangen von HTTP-Anforderungen für benutzerdefinierte Authentifizierungserweiterungen angefordert. Dadurch kann sich die benutzerdefinierte Authentifizierungserweiterung bei Ihrer API authentifizieren. Wählen Sie Akzeptieren aus.

    Screenshot: Erteilen der Administratoreinwilligung.

Schritt 2: Konfigurieren einer OpenID Connect-App zum Empfangen angereicherter Token

Sie können die https://jwt.ms-App verwenden, um ein Token abzurufen und die benutzerdefinierte Authentifizierungserweiterung zu testen. Dabei handelt es sich um eine Microsoft-Webanwendung, die den decodierten Inhalt eines Tokens anzeigt (der Inhalt des Tokens verlässt niemals Ihren Browser).

2.1. Registrieren einer Testwebanwendung

Führen Sie die folgenden Schritte aus, um die Webanwendung jwt.ms zu registrieren:

  1. Wählen Sie auf derStart-Seite im Azure-Portal die Microsoft Entra-ID aus.

  2. Wählen Sie App-Registrierungen>Neue Registrierung aus.

  3. Geben Sie unter Name einen Namen für die Anwendung ein. Beispielsweise „Meine Testanwendung“ oder My Test application.

  4. Wählen Sie unter Unterstützte Kontotypen die Option Nur Konten in diesem Organisationsverzeichnis aus.

  5. Wählen Sie im Dropdownmenü Plattform auswählen unter Umleitungs-URI die Option Web aus, und geben Sie dann in das URL-Textfeld die Zeichenfolge https://jwt.ms ein.

  6. Wählen Sie Registrieren aus, um die App-Registrierung abzuschließen.

    Screenshot: Auswählen des unterstützten Kontotyps und des Umleitungs-URIs.

  7. Kopieren Sie in Ihrer App-Registrierung unter Übersicht die Anwendungs-ID (Client). Die App-ID wird in späteren Schritten als {App_to_enrich_ID} bezeichnet. In Microsoft Graph wird sie durch die appId-Eigenschaft referenziert.

    Screenshot: Kopieren der Anwendungs-ID.

2.2 Aktivieren des impliziten Flows

Die Testanwendung jwt.ms verwendet den impliziten Flow. Aktivieren Sie den impliziten Flow in Ihrer App-Registrierung Meine Testanwendung:

  1. Wählen Sie unter Verwalten die Option Authentifizierung aus.
  2. Aktivieren Sie unter Implizite Genehmigung und Hybridflows das Kontrollkästchen ID-Token (für implizite und Hybridflows verwendet).
  3. Wählen Sie Speichern.

2.3 Aktivieren Ihrer App für eine Anspruchszuordnungsrichtlinie

Eine Anspruchszuordnungsrichtlinie wird verwendet, um auszuwählen, welche von der benutzerdefinierten Authentifizierungserweiterung zurückgegebenen Attribute dem Token zugeordnet werden. Damit Token erweitert werden können, müssen Sie die Anwendungsregistrierung explizit aktivieren, um zugeordnete Ansprüche zu akzeptieren:

  1. Wählen Sie in Ihrer App-Registrierung Meine Testanwendung unter Verwalten die Option Manifest aus.
  2. Suchen Sie im Manifest nach dem Attribut acceptMappedClaims, und legen Sie den Wert auf true fest.
  3. Legen Sie accessTokenAcceptedVersion auf 2 fest.
  4. Klicken Sie zum Speichern der Änderungen auf Speichern.

Im folgenden JSON-Codeausschnitt wird die Konfiguration dieser Eigenschaften veranschaulicht.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

Warnung

Legen Sie die acceptMappedClaims-Eigenschaft für mehrinstanzenfähige Apps nicht auf true fest. Dies kann dazu führen, dass böswillige Akteure Anspruchszuordnungsrichtlinien für Ihre App erstellen. Konfigurieren Sie stattdessen einen benutzerdefinierten Signaturschlüssel.

Fahren Sie mit dem nächsten Schritt fort: Zuweisen eines benutzerdefinierten Anspruchsanbieters zu Ihrer App.

Schritt 3: Zuweisen eines benutzerdefinierten Anspruchsanbieters zu Ihrer App

Damit Token mit von der benutzerdefinierten Authentifizierungserweiterung eingehenden Ansprüchen ausgestellt werden, müssen Sie Ihrer Anwendung einen benutzerdefinierten Anspruchsanbieter zuweisen. Dieser Schritt basiert auf der Tokenzielgruppe. Daher muss der Anbieter der Clientanwendung zugeordnet sein, um Ansprüche in einem ID-Token zu empfangen, und der Ressourcenanwendung, um Ansprüche in einem Zugriffstoken zu empfangen. Der benutzerdefinierte Anspruchsanbieter basiert auf der mit dem Ereignislistener Start der Tokenausgabe konfigurierten benutzerdefinierten Authentifizierungserweiterung. Sie können auswählen, ob dem Token alle oder eine Teilmenge der Ansprüche des benutzerdefinierten Anspruchsanbieters zugeordnet werden sollen.

Hinweis

Sie können nur 250 eindeutige Zuweisungen zwischen Anwendungen und benutzerdefinierten Erweiterungen erstellen. Wenn Sie denselben Aufruf einer benutzerdefinierten Erweiterung in mehreren Apps anwenden möchten, wird die Verwendung der Microsoft Graph-API authenticationEventListeners empfohlen, um Listener für mehrere Anwendungen zu erstellen. Dies wird im Azure-Portal nicht unterstützt.

Führen Sie die folgenden Schritte aus, um Meine Testanwendung mit Ihrer benutzerdefinierten Authentifizierungserweiterung zu verbinden:

So weisen Sie die benutzerdefinierte Authentifizierungserweiterung als Quelle eines benutzerdefinierten Anspruchsanbieters zu

  1. Wählen Sie auf derStart-Seite im Azure-Portal die Microsoft Entra-ID aus.

  2. Wählen Sie unter Verwalten die Option Unternehmensanwendungen und dann Alle Anwendungen aus. Suchen Und wählen Sie Meine Testanwendung aus der Liste aus.

  3. Navigieren Sie auf der Seite Übersicht von Meine Testanwendung zu Verwalten, und wählen Sie Einmaliges Anmelden aus.

  4. Wählen Sie unter Attribute & Ansprüche die Option Bearbeiten aus.

    Screenshot: Konfigurieren von App-Ansprüchen.

  5. Erweitern Sie das Menü Erweiterte Einstellungen.

  6. Wählen Sie neben Benutzerdefinierter Anspruchsanbieter die Option Konfigurieren aus.

  7. Erweitern Sie das Dropdownfeld Benutzerdefinierter Anspruchsanbieter, und wählen Sie das zuvor von Ihnen erstellte Tokenausstellungsereignis aus.

  8. Wählen Sie Speichern aus.

Weisen Sie als Nächstes die Attribute des benutzerdefinierten Anspruchsanbieters zu, die im Token als Ansprüche ausgestellt werden sollen:

  1. Wählen Sie Neuen Anspruch hinzufügen aus, um einen neuen Anspruch hinzuzufügen. Geben Sie einen Namen für den auszustellenden Anspruch an, z. B. dateOfBirth.

  2. Wählen Sie unter Quelle die Option Attribut aus. Wählen Sie anschließend im Dropdownfeld Quellattribut die Option customClaimsProvider.dateOfBirth aus.

    Screenshot: Hinzufügen einer Anspruchszuordnung zu Ihrer App.

  3. Wählen Sie Speichern.

  4. Wiederholen Sie diesen Vorgang, um die Attribute customClaimsProvider.customRoles, customClaimsProvider.apiVersion und customClaimsProvider.correlationId sowie den entsprechenden Namen hinzuzufügen. Es ist ratsam, den Namen des Anspruchs auf den Namen des Attributs abzustimmen.

Schritt 4: Schützen Ihrer Azure-Funktion

Die benutzerdefinierte Microsoft Entra-Authentifizierungserweiterung verwendet den Server-zu-Server-Flow, um ein Zugriffstoken abzurufen, das im HTTP-Header Authorization an Ihre Azure-Funktion gesendet wird. Wenn Sie Ihre Funktion in Azure – insbesondere in einer Produktionsumgebung – veröffentlichen, müssen Sie das im Autorisierungsheader gesendete Token überprüfen.

Führen Sie zum Schutz Ihrer Azure-Funktion die folgenden Schritte zum Integrieren der Microsoft Entra-Authentifizierung aus, um eingehende Token mit der Azure Functions-Authentifizierungsereignis-API zur Authentifizierungsregistrierung zu überprüfen. Verwenden Sie abhängig von Ihrem Mandantentyp eine der folgenden Registerkarten aus.

Hinweis

Wenn die Azure-Funktions-App in einem anderen Azure-Mandanten gehostet wird als dem Mandanten, in dem Ihre benutzerdefinierte Authentifizierungserweiterung registriert ist, wählen Sie die Registerkarte OpenID Connect aus.

4.1. Verwenden des Microsoft Entra-Identitätsanbieters

Führen Sie die folgenden Schritte aus, um Microsoft Entra als Identitätsanbieter zu Ihrer Azure-Funktions-App hinzuzufügen.

  1. Suchen Sie im Azure-Portal die zuvor veröffentlichte Funktions-App, und wählen Sie diese aus.

  2. Wählen Sie unter Einstellungen die Option Authentifizierung aus.

  3. Wählen Sie Identitätsanbieter hinzufügen aus.

  4. Wählen Sie Microsoft als Identitätsanbieter aus.

  5. Wählen Sie als Mandantentyp den Wert Mitarbeiter aus.

  6. Wählen Sie unter App-Registrierung die Option Vorhandene App-Registrierung in diesem Verzeichnis auswählen für App-Registrierungstyp aus. Wählen Sie dann die App-Registrierung Azure Functions-Authentifizierungsereignis-API aus, die Sie beim Registrieren des benutzerdefinierten Anspruchsanbieters zuvor erstellt haben.

  7. Geben Sie die Aussteller-URL https://login.microsoftonline.com/{tenantId}/v2.0 ein, wobei {tenantId} die Mandanten-ID Ihres Mitarbeitermandanten ist.

  8. Wählen Sie unter Clientanwendungs-Anforderung die Option Anfragen von bestimmten Clientanwendungen zulassen aus und geben Sie 99045fe1-7639-4a75-9d4a-577b6ca3810f ein.

  9. Wählen Sie unter Mandantenanforderung die Option Anfragen von bestimmten Mandanten zulassen und geben Sie Ihre Workforce-Mandanten-ID ein.

  10. Wählen Sie unter Nicht authentifizierte Anforderungen die Option HTTP 401 (nicht autorisiert): für APIs empfohlen aus.

  11. Deaktivieren Sie die Option Tokenspeicher.

  12. Wählen Sie Hinzufügen aus, um Ihrer Azure-Funktion die Authentifizierung hinzuzufügen.

    Screenshot, der zeigt, wie Sie Ihrer Funktions-App in einem Workforce-Mandanten eine Authentifizierung hinzufügen.

4.2 Verwenden des OpenID Connect-Identitätsanbieters

Wenn Sie Microsoft als Identitätsanbieter konfiguriert haben, überspringen Sie diesen Schritt. Wird die Azure-Funktion jedoch in einem anderen Mandanten gehostet als dem Mandanten, in dem Ihre benutzerdefinierte Authentifizierungserweiterung registriert ist, führen Sie die folgenden Schritte aus, um Ihre Funktion zu schützen:

Erstellen eines Clientgeheimnisses

  1. Wählen Sie auf der Start-Seite im Azure-Portal Microsoft Entra ID>App-Registrierungen aus.
  2. Wählen Sie die App-Registrierung Azure Functions-Authentifizierungsereignis-API aus, die Sie zuvor erstellt haben.
  3. Wählen Sie Zertifikate und Geheimnisse>Geheime Clientschlüssel>Neuer geheimer Clientschlüssel aus.
  4. Wählen Sie für das Geheimnis eine Ablauffrist aus, oder geben Sie eine benutzerdefinierte Lebensdauer an, fügen Sie eine Beschreibung hinzu, und wählen Sie dann Hinzufügen aus.
  5. Notieren Sie sich den Wert des geheimen Clientschlüssels, der in Ihrem Clientanwendungscode verwendet werden soll. Dieser Geheimniswert kann nach Verlassen dieser Seite nicht erneut angezeigt werden.

Als Nächstes fügen Sie Ihrer Azure-Funktions-App den OpenID Connect-Identitätsanbieter hinzu.

  1. Suchen Sie die zuvor veröffentlichte Funktions-App, und wählen Sie diese aus.

  2. Wählen Sie unter Einstellungen die Option Authentifizierung aus.

  3. Wählen Sie Identitätsanbieter hinzufügen aus.

  4. Wählen Sie OpenID Connect als Identitätsanbieter aus.

  5. Geben Sie einen Namen an, z. B. Contoso Microsoft Entra ID.

  6. Geben Sie unter dem Metadateneintrag die folgende URL zur Dokument-URL ein. Ersetzen Sie {tenantId} durch Ihre Microsoft Entra-Mandanten-ID.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration

  7. Geben Sie unter der App-Registrierung die Anwendungs-ID (Client-ID) der App-Registrierung Azure Functions-Authentifizierungsereignis-API ein, die Sie zuvor erstellt haben.

  8. Geben Sie zur Azure-Funktion zurück, und geben Sie unter App-Registrierung den Wert für Geheimer Clientschlüssel ein.

  9. Deaktivieren Sie die Option Tokenspeicher.

  10. Wählen Sie Hinzufügen aus, um den OpenID Connect-Identitätsanbieter hinzuzufügen.

Schritt 5: Testen der Anwendung

Führen Sie die folgenden Schritte aus, um Ihren benutzerdefinierten Anspruchsanbieter zu testen:

  1. Öffnen Sie ein neues privates Browserfenster, und navigieren Sie zur folgenden URL, um sich anzumelden.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

  2. Ersetzen Sie {tenantId} durch Ihre Mandanten-ID, Ihren Mandantennamen oder einen Ihrer überprüften Domänennamen. Beispiel: contoso.onmicrosoft.com.

  3. Ersetzen Sie {App_to_enrich_ID} durch die Client-ID für Meine Testanwendung.

  4. Nach der Anmeldung wird Ihr decodiertes Token unter https://jwt.ms angezeigt. Überprüfen Sie, ob die Ansprüche aus der Azure-Funktion im decodierten Token enthalten sind, z. B. dateOfBirth.

Siehe auch