Konfigurieren der Anmeldeinformationsverwaltung – benutzerdelegierter Zugriff auf Back-End-API

  • Artikel

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 im Back-End zugreifen muss (also z. B. E-Mails überprüfen oder eine Bestellung aufgeben soll).

Übersicht über das Szenario

Hinweis

Dieses Szenario gilt nur für Anmeldeinformationsanbieter, die mit dem Gewährungstyp Autorisierungscode konfiguriert sind.

In diesem Szenario konfigurieren Sie eine verwaltete Verbindung, mit deren Hilfe eine Client-App (oder ein Bot) im Auftrag eines Microsoft Entra-Benutzers oder einer -Gruppe auf eine Back-End-API zugreifen kann. Sie könnten beispielsweise über eine statische Web-App verfügen, die auf eine Back-End-GitHub-API zugreift und die auf für den angemeldeten Benutzer spezifische Daten zugreifen soll. Die folgende Abbildung veranschaulicht dieses Szenario.

Diagramm, das den Prozessfluss für benutzerdelegierte Berechtigungen zeigt.

  • Der Benutzer muss die App für den Zugriff auf gesicherte Ressourcen in seinem Namen autorisieren. Um die App zu autorisieren, muss der Benutzer außerdem seine Identität authentifizieren.
  • Um Vorgänge im Auftrag eines Benutzers auszuführen, ruft die App den externen Back-End-Dienst auf, z. B. Microsoft Graph oder GitHub.
  • Jeder externe Dienst hat eigene Möglichkeiten, diese Aufrufe zu sichern, z. B. mit einem Benutzertoken, das den Benutzer eindeutig identifiziert.
  • Zum Sichern des Aufrufs des externen Diensts muss die App den Benutzer auffordern, sich anzumelden, um das Token des Benutzers abzurufen.
  • Im Rahmen der Konfiguration wird ein Anmeldeinformationsanbieter mithilfe der Anmeldeinformationsverwaltung in der API Management-Instanz registriert. Sie enthält Informationen zum zu verwendenden Identitätsanbieter sowie eine gültige OAuth-Client-ID und ein entsprechendes Geheimnis, die zu aktivierenden OAuth-Bereiche und weitere Verbindungsmetadaten, die von diesem Identitätsanbieter benötigt werden.
  • Außerdem wird eine Verbindung erstellt und verwendet, um die Anmeldung des Benutzers zu unterstützen und das Benutzertoken abzurufen, damit es verwaltet werden kann.

Voraussetzungen

  • Greifen Sie auf einen Microsoft Entra-Mandanten zu, in dem Sie über Berechtigungen zum Erstellen einer App-Registrierung und zum Erteilen der Administratoreinwilligung für die Berechtigungen der App verfügen. 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 aktive API Management-Instanz. Erstellen Sie eine Azure API Management-Instanz, sofern erforderlich.

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

Schritt  1: Bereitstellen des Azure API Management-Dienstprinzipals auf Datenebene

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 mit dem folgenden Befehl eine Verbindung zu Ihrem Mandanten her:

    Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"

  4. Wenn Sie dazu aufgefordert werden, melden Sie sich mit Anmeldeinformationen für das Administratorkonto Ihres Mandanten an.

  5. Stellen Sie mit dem folgenden Befehl den Azure API Management-Dienstprinzipal auf Datenebene 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 ihr die erforderlichen Berechtigungen zum Lesen der Verbindung in API Management.

  1. Melden Sie sich beim Azure-Portal mit einem Konto mit ausreichenden Berechtigungen im Mandanten an.
  2. Suchen Sie unter Azure-Dienste die Option 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 die Registrierungseinstellungen Ihrer Anwendung ein:
    1. Geben Sie für Name einen aussagekräftigen Namen ein, der Benutzern der App angezeigt wird, beispielsweise UserPermissions.
    2. Wählen Sie für Unterstützte Kontotypen eine Option aus, die zu Ihrem Szenario passt, beispielsweise Konten nur in diesem Organisationsverzeichnis (Einzelmandant).
    3. Legen Sie die Umleitungs-URI auf Web fest und geben Sie https://www.postman-echo.com/get ein.
  5. Wählen Sie im linken Menü API-Berechtigungen und dann + Berechtigung hinzufügen aus.
    1. Wählen Sie die Registerkarte APIs, die meine Organisation verwendet aus, geben Sie Azure API Management Data Plane ein, und wählen Sie die Option aus.
    2. Wählen Sie unter Berechtigungen die Option Authorizations.Read und dann Berechtigungen hinzufügen aus.
  6. Wählen Sie im Menü auf der linken Seite Übersicht aus. Suchen Sie auf der Seite Übersicht den Wert Anwendungs-ID (Client-ID), und notieren Sie ihn zur Verwendung in einem späteren Schritt.
  7. Wählen Sie im linken Menü Zertifikate und Geheimnisse 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. Klicken Sie auf Hinzufügen.
    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 in API Management

  1. Melden Sie sich beim Portal an, und wechseln Sie zu Ihrer API Management-Instanz.
  2. Wählen Sie im linken Menü Anmeldeinformationsverwaltung aus und dann + Erstellen aus.
    Screenshot des Erstellens einer API-Anmeldeinformationen im Portal.
  3. Geben Sie auf der Seite Anmeldeinformationsanbieter erstellen die Einstellungen für den Anmeldeinformationsanbieter für Ihre API ein. In diesem Szenario müssen Sie unter Gewährungstyp die Option Autorisierungscodeauswählen. Weitere Informationen finden Sie unter Konfigurieren von Anmeldeinformationsanbietern in der Anmeldeinformationsverwaltung.
  4. Klicken Sie auf Erstellen.
  5. 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 App-Registrierung eingegeben haben.

Schritt 4: Konfigurieren einer Verbindung

Nachdem Sie einen Anmeldeinformationsanbieter erstellt haben, können Sie eine Verbindung zum 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 den Link zum Anmelden beim Anmeldeinformationsanbieter aus. Führen Sie dort die notwendigen Schritte aus, um den Zugriff zu autorisieren, und kehren Sie dann zu API Management zurück.
  3. Wählen Sie unter Schritt 3: Bestimmen, wer Zugriff auf diese Verbindung haben soll (Zugriffsrichtlinie) + Hinzufügenaus. Wählen Sie abhängig von Ihrem Delegierungsszenario Benutzer oder Gruppe aus.
  4. Treffen Sie im Fenster Element auswählen in folgender Reihenfolge eine Auswahl:
    1. Suchen Sie zunächst nach einem oder mehreren Benutzern (oder Gruppen), um das Auswahlfeld hinzuzufügen und zu aktivieren.
    2. Suchen Sie dann in der angezeigten Liste nach der App-Registrierung, die Sie in einem der vorherigen Abschnitte erstellt haben.
    3. Klicken Sie dann auf Auswählen.
  5. Wählen Sie Abschließen aus.

Die neue Verbindung wird in der Liste der Verbindungen mit dem Status Verbunden angezeigt. Wenn Sie eine weitere Verbindung für den Anmeldeinformationsanbieter erstellen möchten, führen Sie die vorherigen Schritte erneut aus.

Tipp

Verwenden Sie das Portal, um jederzeit Verbindungen zu einem Anmeldeinformationsanbieter hinzuzufügen, zu aktualisieren oder zu löschen. Weitere Informationen finden Sie unter Konfigurieren mehrerer Verbindungen.

Schritt 5: Erhalten eines Microsoft Entra ID-Zugriffstokens

Um den benutzerdelegierte Zugriff auf die Back-End-API zu aktivieren, muss ein Zugriffstoken für den delegierten Benutzer oder die delegierte Gruppe in der get-authorization-context-Richtlinie zur Laufzeit bereitgestellt werden. In der Regel erfolgt dies programmgesteuert in Ihrer Client-App mithilfe der Microsoft Authentication Library (MSAL). Dieser Abschnitt umfasst die manuellen Schritte zum Erstellen eines Zugriffstokens zu Testzwecken.

  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 für code, der bereitgestellt wird (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

    Übergeordnet

    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 Antworttext den Wert für access_token, der bereitgestellt wird (Beispiel: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Sie übergeben diesen Wert im nächsten Schritt an die Richtlinienkonfiguration.

Schritt 6: Konfigurieren der get-authorization-context-Richtlinie für die Back-End-API

Konfigurieren Sie die get-authorization-context-Richtlinie 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 Portal an, und wechseln Sie zu Ihrer API Management-Instanz.

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

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

  4. Konfigurieren Sie die get-authorization-context-Richtlinie im Abschnitt inbound, indem Sie identity-type auf jwtfestlegen:

    <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" />
        [...]
    </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> durch das 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 Vorgang aus, den Sie konfiguriert haben.

  2. Wählen Sie Send (Senden) aus.

    Eine erfolgreiche Antwort gibt Benutzerdaten von der GitHub-API zurück.

Zugehöriger Inhalt