Konfigurieren des Anmeldedatenmanagers – benutzerdelegierter Zugriff auf die Backend-API

GILT FÜR: Alle API Management-Ebenen

Dieser Artikel führt Sie durch die allgemeinen Schritte zum Konfigurieren und Verwenden einer verwalteten Verbindung , die Microsoft Entra-Benutzern oder Gruppen delegierte Berechtigungen für eine Back-End-OAuth 2.0-API gewährt. Führen Sie diese Schritte für Szenarien aus, in denen eine Client-App (oder ein Bot) im Namen eines authentifizierten Benutzers auf gesicherte Onlineressourcen zugreifen muss (z. B. zum Überprüfen von E-Mails oder Zum Aufgeben einer Bestellung).

Beschreibung des Szenarios

In diesem Szenario konfigurieren Sie eine verwaltete Verbindung , mit der eine Client-App (oder ein Bot) im Auftrag eines Microsoft Entra-Benutzers oder einer Gruppe auf eine Back-End-API zugreifen kann. Sie können beispielsweise über eine statische Web-App verfügen, die auf eine Back-End-GitHub-API zugreift, und Sie möchten auf Daten zugreifen, die für den angemeldeten Benutzer spezifisch sind. Das folgende Diagramm veranschaulicht das Szenario.

• Der Benutzer muss die App für den Zugriff auf gesicherte Ressourcen in ihrem Namen autorisieren. Um die App zu autorisieren, muss der Benutzer seine Identität in Microsoft Entra authentifizieren.
• Um Vorgänge im Auftrag eines Benutzers auszuführen, ruft die App den externen Back-End-Dienst auf, z. B. GitHub.
• Jeder externe Dienst hat eine Möglichkeit, diese Anrufe zu sichern; Beispielsweise mit einem Benutzertoken, das den Benutzer eindeutig identifiziert.
• Um den Aufruf des externen Diensts zu sichern, muss die App den Benutzer auffordern, sich anzumelden, damit es das Token des Benutzers abrufen kann.
• Im Rahmen der Konfiguration registrieren Sie einen Anmeldeinformationsanbieter mithilfe des Anmeldeinformations-Managers in der API-Verwaltungsinstanz. Sie enthält Informationen über den zu verwendenden Identitätsanbieter sowie eine gültige OAuth-Client-ID und einen geheimen Schlüssel, die OAuth-Bereiche, die aktiviert werden sollen, und andere Verbindungsmetadaten, die von diesem Identitätsanbieter benötigt werden.
• Sie erstellen und verwenden eine Verbindung, um den Benutzer anzumelden und das Benutzertoken abzurufen, damit es verwaltet werden kann.

Voraussetzungen

• Zugriff auf einen Microsoft Entra-Mandanten, in dem Sie über Berechtigungen zum Erstellen einer App-Registrierung verfügen und um Administratorzustimmung für die Berechtigungen der App zu erteilen. Weitere Informationen

  Wenn Sie Ihren eigenen Entwicklermandanten erstellen möchten, können Sie sich für das Microsoft 365-Entwicklerprogramm registrieren.

• Mindestens ein Benutzer oder eine Gruppe im Mandanten, an die Berechtigungen delegiert werden sollen.

• Eine ausgeführte API-Verwaltungsinstanz. Erstellen Sie bei Bedarf eine Azure API-Verwaltungsinstanz.

• Eine Back-End-OAuth 2.0-API, auf die Sie im Namen des Benutzers oder der Gruppe zugreifen möchten. Beispielsweise die GitHub-API.

• Bei lokaler Verwendung von Azure PowerShell:
  • Installieren Sie die neueste Version des Az PowerShell-Moduls.
  • Stellen Sie mithilfe des Cmdlets Connect-AzAccount eine Verbindung mit Ihrem Azure-Konto her.
• Bei Verwendung von Azure Cloud Shell:
  • Weitere Informationen finden Sie in der Übersicht über Azure Cloud Shell.

Schritt 1: Provisionieren des Azure API Management Data Plane Service Principal

Sie müssen den Azure API Management-Dienstprinzipal auf Datenebene bereitstellen, um Benutzern oder Gruppen die erforderlichen delegierten Berechtigungen zu gewähren. Führen Sie die folgenden Schritte aus, um den Dienstprinzipal mithilfe von Azure PowerShell bereitzustellen.

1. Melden Sie sich bei Azure PowerShell an.

2. Wenn das AzureAD-Modul noch nicht installiert ist, installieren Sie es mit dem folgenden Befehl:

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. Stellen Sie eine Verbindung mit Ihrem Mandanten mit dem folgenden Befehl her:

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

4. Wenn Sie dazu aufgefordert werden, melden Sie sich mit Administratorkontoanmeldeinformationen für Ihren Mandanten an.

5. Stellen Sie den Service Principal "Azure API Management Data Plane" mit dem folgenden Befehl bereit:

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

Schritt 2: Erstellen einer Microsoft Entra-App-Registrierung

Erstellen Sie eine Microsoft Entra ID-Anwendung für die Benutzerdelegierung, und erteilen Sie ihm die entsprechenden Berechtigungen zum Lesen der Verbindung in der API-Verwaltung.

1. Melden Sie sich beim Azure-Portal mit einem Konto mit ausreichenden Berechtigungen im Mandanten an.
2. Suchen Sie unter Azure Services nach Microsoft Entra-ID.
3. Wählen Sie im linken Menü "App-Registrierungen>" und dann +Neue Registrierung aus.
4. Geben Sie auf der Seite "Anwendung registrieren " Ihre Anwendungsregistrierungseinstellungen ein:
   1. Geben Sie unter "Name" einen aussagekräftigen Namen ein, den Benutzer sehen, z. B. "UserPermissions".
   2. Wählen Sie in Unterstützte Kontotypen eine Option aus, die Ihrem Szenario entspricht, z. B. Konten in diesem Organisations-Verzeichnis (nur Einzelner Mandant).
   3. Legen Sie die Umleitungs-URI auf Web fest und geben Sie dann https://www.postman-echo.com/get ein.
   4. Wählen Sie Registrieren aus.
5. Wählen Sie im linken Menü "API-Berechtigungen>" und dann "+Berechtigung hinzufügen" aus.
   1. Wählen Sie die APIs aus, die meine Organisation verwendet , geben Sie Azure API Management Data Plane ein, und wählen Sie sie aus.
   2. Wählen Sie unter "Berechtigungen" die Option "Authorizations.Read" und dann "Berechtigungen hinzufügen" aus.
6. Wählen Sie im linken Menü die Option "Übersicht" aus. Suchen Sie auf der Seite "Übersicht" den Wert der Anwendungs-ID (Client-ID), und notieren Sie ihn für die Verwendung in einem späteren Schritt.
7. Wählen Sie im linken Menü "Zertifikate und Geheime Schlüssel>" und dann "+Neuer geheimer Clientschlüssel" aus.
   1. Geben Sie eine Beschreibung ein.
   2. Wählen Sie eine Option für Gültig bis aus.
   3. Wählen Sie Hinzufügen aus.
   4. Kopieren Sie den Wert des geheimen Clientschlüssels, bevor Sie die Seite verlassen. Sie benötigen sie in einem späteren Schritt.

Schritt 3: Konfigurieren eines Anmeldeinformationsanbieters im API-Management

Erstellen Sie in diesem Schritt einen Anmeldeinformationsanbieter für Ihre Backend-OAuth 2.0-API, auf die Sie im Namen des Benutzers oder der Gruppe zugreifen möchten. Führen Sie beispielsweise die Schritte aus, um einen Anmeldeinformationsanbieter für die GitHub-API zu erstellen. Kurze Schritte:

1. Erstellen Sie eine OAuth-App in GitHub für die API, und geben Sie ihm die entsprechenden Berechtigungen für die Anforderungen, die Sie aufrufen möchten.
2. Melden Sie sich beim Azure-Portal an, und wechseln Sie zu Ihrer API-Verwaltungsinstanz.
3. Wählen Sie im linken Menü apIs>Credential Manager aus, und wählen Sie dann +Erstellen aus.
4. Geben Sie bei "Anmeldeinformationsanbieter erstellen" die Einstellungen für den GitHub-Anbieter ein. Wählen Sie für dieses Szenario im Grant-Typden Autorisierungscode aus. Weitere Informationen erhalten Sie im Abschnitt Konfigurieren von Anmeldeinformationsanbietern im Anmeldeinformations-Manager.
5. Wählen Sie "Erstellen" aus.
6. Wenn Sie dazu aufgefordert werden, überprüfen Sie die angezeigte OAuth-Umleitungs-URL, und wählen Sie "Ja " aus, um zu bestätigen, dass sie mit der URL übereinstimmt, die Sie in der GitHub-App-Registrierung eingegeben haben.

Schritt 4: Konfigurieren einer Verbindung

Nachdem Sie einen Anmeldeinformationsanbieter erstellt haben, können Sie eine Verbindung zum GitHub-Anbieter hinzufügen. Führen Sie auf der Registerkarte "Verbindung " die Schritte für Ihre Verbindung aus:

1. Geben Sie einen Verbindungsnamen ein, und wählen Sie dann "Speichern" aus.
2. Wählen Sie unter Schritt 2: Anmelden bei Ihrer Verbindung die Schaltfläche " Anmelden " aus. Führen Sie dort Schritte aus, um den Zugriff zu autorisieren und zur API-Verwaltung zurückzukehren.
3. Wählen Sie unter Schritt 3: Bestimmen Sie, wer Zugriff auf diese Verbindung hat (Zugriffsrichtlinie), und wählen Sie + Hinzufügen aus. Wählen Sie je nach Ihrem Delegierungsszenario "Benutzer " oder "Gruppe" aus.
4. Treffen Sie im Fenster "Element auswählen " eine Auswahl in der folgenden Reihenfolge:
   1. Suchen Sie nach einem oder mehreren Benutzern oder Gruppen, um das Auswahlfeld hinzuzufügen und zu aktivieren.
   2. Suchen Sie nach der App-Registrierung, die Sie in einem vorherigen Abschnitt erstellt haben.
   3. Wählen Sie Select aus.
5. Wählen Sie Complete (Fertig stellen) aus.

Die neue Verbindung wird in der Liste der Verbindungen angezeigt und zeigt den Status " Verbunden" an. Wenn Sie eine weitere Verbindung für den Anmeldeinformationsanbieter einrichten möchten, führen Sie die vorherigen Schritte aus.

Schritt 5: Abrufen eines Microsoft Entra ID-Zugriffstokens

Um den benutzerdelegierte Zugriff auf die Back-End-API zu aktivieren, müssen Sie ein Zugriffstoken für den delegierten Benutzer oder die delegierte Gruppe zur Laufzeit in der get-authorization-context Richtlinie bereitstellen. In der Regel ruft Ihre Client-App dieses Token programmgesteuert mithilfe der Microsoft Authentication Library (MSAL) ab. Dieser Abschnitt enthält manuelle Schritte zum Erstellen eines Zugriffstokens zum Testen.

1. Fügen Sie die folgende URL in Ihren Browser ein, und ersetzen Sie die Werte für <tenant-id> und <client-id> durch Werte aus Ihrer Microsoft Entra-App-Registrierung:

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234
   

2. Melden Sie sich an, wenn Sie dazu aufgefordert werden. Kopieren Sie im Antworttext den Wert des bereitgestellten Codes (Beispiel: "0.AXYAh2yl...").

3. Senden Sie die folgende POST-Anforderung an den Tokenendpunkt. Ersetzen Sie dabei <tenant-id> durch Ihre Mandanten-ID, und schließen Sie die in Ihrer App-Registrierung angegebenen Header- und Textkörperparameter sowie den Code ein, den Sie im vorherigen Schritt kopiert haben.

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   Header

   Content-Type: application/x-www-form-urlencoded

   Text

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. Kopieren Sie im Antwortkörper den Wert von "access_token," der bereitgestellt wird (Beispiel: ). Sie übergeben diesen Wert in der Richtlinienkonfiguration im nächsten Schritt.

Schritt 6: Konfigurieren der Get-Authorization-Kontextrichtlinie für die Back-End-API

Konfigurieren Sie die Get-Authorization-Kontextrichtlinie für die Back-End-API, auf die Sie im Namen des Benutzers oder der Gruppe zugreifen möchten. Für Testzwecke können Sie die Richtlinie mithilfe des Microsoft Entra ID-Zugriffstokens für den Benutzer konfigurieren, den Sie im vorherigen Abschnitt erhalten haben.

1. Melden Sie sich beim Azure-Portal an, und wechseln Sie zu Ihrer API-Verwaltungsinstanz.

2. Wählen Sie im linken MenüAPIs>aus, und wählen Sie Ihre OAuth 2.0-Back-End-API aus.

3. Wählen Sie "Alle Vorgänge" aus. Wählen Sie im Abschnitt "Eingehende Verarbeitung " das Symbol (</>) (Code-Editor) aus.

4. Konfigurieren Sie die get-authorization-context-Richtlinie im Abschnitt inbound, indem Sie identity-type auf jwt festlegen. Konfigurieren Sie außerdem die beiden set-header Richtlinien, um den Header mit dem Authorization in der get-authorization-context Richtlinie abgerufenen Token festzulegen und einen erforderlichen User-Agent Header für die GitHub-API zu konfigurieren.

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
            <set-header name="Authorization" exists-action="override">
               <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
           </set-header>
           <set-header name="User-Agent" exists-action="override">
               <value>API Management</value>
           </set-header>
           [...]
       </inbound> 
   </policies>
   

Ersetzen Sie in der vorherigen Richtliniendefinition Folgendes:

• <credential-provider-id> und <connection-id> durch die Namen des Anmeldeinformationsanbieters und der Verbindung, die Sie in einem der vorherigen Schritte konfiguriert haben.

• <access-token> mit dem Microsoft Entra ID-Zugriffstoken, das Sie im vorherigen Schritt generiert haben.

Schritt 7: Testen der API

1. Wählen Sie auf der Registerkarte " Test " einen von Ihnen konfigurierten Vorgang aus.

2. Wählen Sie "Senden" aus.

   Eine erfolgreiche Antwort gibt Benutzerdaten aus der Back-End-API zurück.

Verwandte Inhalte

• Erfahren Sie mehr über Authentifizierungs- und Autorisierungsrichtlinien.
• Erfahren Sie mehr über Bereiche und Berechtigungen in der Microsoft Entra-ID.