Konfigurieren der OAuth 2.0-Benutzerautorisierung in der Testkonsole des Entwicklerportals

GILT FÜR: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Viele APIs unterstützen OAuth 2.0 , um sicherzustellen, dass nur gültige Benutzer Zugriff haben, und um Benutzer auf Ressourcen zu beschränken, auf die sie anspruchsberechtigt sind. Damit Sie die interaktive Entwicklerkonsole von Azure API Management mit solchen APIs verwenden können, ermöglicht es der Dienst Ihnen, einen externen Anbieter für die OAuth 2.0-Benutzerautorisierung zu konfigurieren.

Das Konfigurieren der OAuth 2.0-Benutzerautorisierung in der Testkonsole des Entwicklerportals bietet Entwickler*innen eine praktische Möglichkeit, ein OAuth 2.0-Zugriffstoken abzurufen. Über die Testkonsole wird das Token dann mit dem API-Aufruf an das Back-End übergeben. Die Tokenüberprüfung muss separat konfiguriert werden, entweder mithilfe einer JWT-Validierungsrichtlinie oder im Back-End-Dienst.

Voraussetzungen

• Erstellen Sie eine Azure API-Verwaltungsdienstinstanz.
• Ein OAuth 2.0-Anbieter.

Dieser Artikel beschreibt, wie Sie eine Instanz des API Management-Diensts zur Verwendung der OAuth 2.0-Autorisierung in der Testkonsole des Entwicklerportals konfigurieren. Es wird jedoch nicht behandelt, wie Sie einen OAuth 2.0-Anbieter konfigurieren.

Übersicht über das Szenario

Die Konfiguration der OAuth 2.0-Benutzerautorisierung in API Management ermöglicht es nur der Testkonsole des Entwicklerportals (und der Testkonsole im Azure-Portal) als Client, ein Token vom Autorisierungsserver abzurufen. Die Konfiguration ist je nach OAuth 2.0-Anbieter unterschiedlich, die Schritte sind jedoch ähnlich, und die beim Konfigurieren von OAuth 2.0 in Ihrer Instanz des API Management-Diensts erforderlichen Informationen sind gleich. In diesem Artikel wird ein Beispiel zur Verwendung von Microsoft Entra ID als OAuth 2.0-Anbieter gezeigt.

Im Folgenden sind die allgemeinen Konfigurationsschritte aufgeführt:

1. Registrieren einer Anwendung (Back-End-App) in Microsoft Entra ID, um die API darzustellen

2. Registrieren Sie eine andere Anwendung (Client-App) in Microsoft Entra ID, um eine Clientanwendung darzustellen, die die API aufrufen muss, in diesem Fall die Testkonsole des Entwicklerportals.

   Gewähren Sie Berechtigungen in Microsoft Entra ID, damit die Client-App die Back-End-App aufrufen kann.

3. Konfigurieren der Testkonsole im Entwicklerportal zum Aufrufen einer API unter Verwendung der OAuth 2.0-Benutzerautorisierung

4. Konfigurieren einer API zum Verwenden der OAuth 2.0-Benutzerautorisierung

5. Fügen Sie eine Richtlinie hinzu, um das OAuth 2.0-Token für jede eingehende Anforderung vorab zu authentifizieren. Sie können die validate-jwt-Richtlinie für jeden OAuth 2.0-Anbieter verwenden.

Diese Konfiguration unterstützt den folgenden OAuth-Flow:

1. Das Entwicklerportal fordert ein Token von Microsoft Entra ID unter Verwendung der Client-App-Anmeldeinformationen an.

2. Nach erfolgreicher Überprüfung stellt Microsoft Entra ID das Zugriffs-/Aktualisierungstoken aus.

3. Ein Entwickler (Benutzer des Entwicklerportals) führt einen API-Aufruf mit dem Autorisierungsheader aus.

4. Das Token wird mithilfe der validate-jwt -Richtlinie mit dem OAuth 2.0-Anbieter überprüft. Für den Microsoft Entra ID-Anbieter stellt API Management auch die validate-azure-ad-token -Richtlinie bereit.

5. Basierend auf dem Validierungsergebnis erhält der Entwickler die Antwort im Entwicklerportal.

Autorisierungsgewährungstypen

Azure API Management unterstützt die folgenden OAuth 2.0-Gewährungstypen (Flows). Ein Gewährungstyp bezieht sich auf eine Art, wie eine Clientanwendung (in diesem Kontext die Testkonsole im Entwicklerportal) ein Zugriffstoken für Ihre Backend-API abrufen kann. Sie können je nach OAuth 2.0-Anbieter und Szenarien einen oder mehrere Gewährungstypen konfigurieren.

Es folgt eine allgemeine Zusammenfassung. Weitere Informationen zu Gewährungstypen finden Sie unter OAuth 2.0-Autorisierungsframework und OAuth-Gewährungstypen.

Sicherheitsüberlegungen

Sie können entscheiden, wie der Gewährungstyp ein Token generiert, welchen Gültigkeitsbereich das Token hat und wie das Token verfügbar gemacht werden kann. Ein kompromittiertes Token kann von einem böswilligen Akteur verwendet werden, um auf zusätzliche Ressourcen im Gültigkeitsbereich des Tokens zuzugreifen.

Beim Konfigurieren der OAuth 2.0-Benutzerautorisierung an der Testkonsole im Entwicklerportal:

• Beschränken Sie den Bereich des Tokens auf das Minimum, das Entwickler*innen zum Testen der APIs benötigen. Beschränken Sie den Bereich auf die Testkonsole oder die betroffenen APIs. Die Schritte zum Konfigurieren des Tokenbereichs hängen von Ihrem OAuth 2.0-Anbieter ab. Ein Beispiel wird weiter unten in diesem Artikel mithilfe von Microsoft Entra ID gezeigt.

  Je nach Ihren Szenarien können Sie mehr oder weniger restriktive Tokenbereiche für andere Clientanwendungen konfigurieren, die Sie für den Zugriff auf Back-End-APIs erstellen.

• Seien Sie beim Aktivieren des Flows für die Clientanmeldeinformationen besonders vorsichtig. Die Testkonsole im Entwicklerportal fordert beim Arbeiten mit dem Client-Anmeldeablauf keine Anmeldeinformationen an. Ein Zugriffstoken kann versehentlich für Entwickler*innen oder anonyme Benutzer*innen der Entwicklerkonsole verfügbar gemacht werden.

Nachverfolgen wichtiger Informationen

In diesem Tutorial werden Sie aufgefordert, wichtige Informationen zu notieren, um später darauf zu verweisen:

• Back-End-Anwendung (Client)-ID: Die GUID der Anwendung, die die Back-End-API darstellt
• Back-End-Anwendungsbereiche: Mindestens ein Bereich, den Sie für den Zugriff auf die API erstellen können. Das Bereichsformat ist api://<Backend Application (client) ID>/<Scope Name> (z. B. api://a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/Read)
• Clientanwendungs-ID (Client-ID): Die GUID der Anwendung, die das Entwicklerportal darstellt
• Geheimer Wert der Clientanwendung: Die GUID, die als geheime Kennung für die Interaktion mit der Clientanwendung in Microsoft Entra ID dient

Registrieren von Anwendungen beim OAuth-Server

Sie müssen zwei Anwendungen bei Ihrem OAuth 2.0-Anbieter registrieren: eine stellt die zu schützende Back-End-API dar, und eine zweite stellt die Clientanwendung dar, die die API aufruft, in diesem Fall die Testkonsole des Entwicklerportals.

In den folgenden Beispielschritten wird Microsoft Entra ID als OAuth 2.0-Anbieter verwendet. Ausführliche Informationen zur App-Registrierung finden Sie unter Konfigurieren einer Anwendung zum Verfügbarmachen einer Web-API.

Registrieren einer Anwendung in Microsoft Entra ID, um die API darzustellen

1. Suchen Sie im Azure-Portal nach App-Registrierungen, und wählen Sie App-Registrierungen aus.

2. Wählen Sie Neue Registrierung aus.

3. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen Ihrer Anwendung ein:

   • Geben Sie im Abschnitt "Name " einen aussagekräftigen Anwendungsnamen ein, der Benutzern der App angezeigt wird, z. B. Back-End-App.
   • Wählen Sie im Abschnitt Unterstützte Kontotypen eine Option aus,die Ihrem Szenario entspricht.

4. Lassen Sie den Abschnitt Umleitungs-URI leer. Später fügen Sie einen umleitungs-URI hinzu, der in der OAuth 2.0-Konfiguration in der API-Verwaltung generiert wurde.

5. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

6. Suchen Sie auf der Seite Übersicht den Wert von Anwendungsclient-ID und notieren Sie ihn zur späteren Verwendung.

7. Wählen Sie im Abschnitt Verwalten des seitlichen Menüs Eine API verfügbar machen aus, und legen Sie den Anwendungs-ID-URI auf den Standardwert fest. Notieren Sie sich diesen Wert zur späteren Verwendung.

8. Wählen Sie die Schaltfläche Bereich hinzufügen aus, um die Seite Bereich hinzufügen anzuzeigen:

   1. Geben Sie einen Bereichsnamen für einen Bereich ein, der von der API unterstützt wird (z. B. Files.Read).
   2. Treffen Sie unter Wer darf einwilligen? eine Auswahl für Ihr Szenario, z. B. Administratoren und Benutzer. Wählen Sie für Szenarien mit umfassenderen Berechtigungen Nur Administratoren aus.
   3. Geben Sie den Anzeigenamen der Administratoreinwilligung und eine Beschreibung der Administratoreinwilligung ein.
   4. Stellen Sie sicher, dass der Bereichsstatus Aktiviert ausgewählt ist.

9. Wählen Sie die Schaltfläche Bereich hinzufügen aus, um den Bereich zu erstellen.

10. Wiederholen Sie die beiden vorherigen Schritte, um alle Bereiche hinzuzufügen, die von Ihrer API unterstützt werden.

11. Nachdem Sie die Bereiche erstellt haben, notieren Sie diese, um sie in einem nachfolgenden Schritt zu verwenden.

Registrieren einer weiteren Anwendung in Microsoft Entra ID, um eine Clientanwendung darzustellen

Registrieren Sie jede Clientanwendung, aus der die API aufgerufen wird, als Anwendung in Microsoft Entra ID.

1. Suchen Sie im Azure-Portal nach Anwendungsregistrierungen, und wählen Sie diese aus.

2. Wählen Sie Neue Registrierung aus.

3. Geben Sie auf der daraufhin angezeigten Seite Anwendung registrieren die Registrierungsinformationen Ihrer Anwendung ein:

   • Geben Sie im Abschnitt "Name " einen aussagekräftigen Anwendungsnamen ein, der Benutzern der App angezeigt wird, z. B. client-app.
   • Wählen Sie im Abschnitt Unterstützte Kontotypen eine Option aus,die Ihrem Szenario entspricht.

4. Wählen Sie im Abschnitt Umleitungs-URI die Option Web aus, und lassen Sie das URL-Feld vorerst leer.

5. Wählen Sie Registrieren aus, um die Anwendung zu erstellen.

6. Suchen Sie auf der Seite Übersicht den Wert von Anwendungsclient-ID und notieren Sie ihn zur späteren Verwendung.

7. Erstellen Sie einen geheimen Clientschlüssel für diese Anwendung, der in einem späteren Schritt von ihr verwendet wird.

   1. Wählen Sie im Abschnitt Verwalten des seitlichen Menüs Zertifikate und Geheimnisse aus.
   2. Wählen Sie unter Geheime Clientschlüssel die Option + Neuer geheimer Clientschlüssel.
   3. Geben Sie unter Geheimen Clientschlüssel hinzufügen eine Beschreibung ein, und wählen Sie aus, wann der Schlüssel ablaufen soll.
   4. Wählen Sie Hinzufügen.

Nachdem Sie das Geheimnis erstellt haben, notieren Sie sich den Schlüsselwert, um ihn in einem nachfolgenden Schritt zu verwenden. Sie können im Portal nicht mehr auf das Geheimnis zugreifen.

Gewähren von Berechtigungen in Microsoft Entra ID

Nachdem nun zwei Anwendungen registriert sind, die die API und die Testkonsole darstellen, gewähren Sie Berechtigungen, damit die Client-App die Back-End-App aufrufen kann.

1. Suchen Sie im Azure-Portal nach App-Registrierungen, und wählen Sie App-Registrierungen aus.

2. Wählen Sie Ihre Client-App aus. Wählen Sie dann im Randleistenmenü unter "Verwalten" API-Berechtigungen aus.

3. Wählen Sie + Eine Berechtigung hinzufügen aus.

4. Wählen Sie unter API auswählen die Option Meine APIs aus, suchen Sie dann die Back-End-App (die App-Registrierung für Ihre Back-End-API), und wählen Sie diese aus.

5. Wählen Sie Delegierte Berechtigungen aus, und wählen Sie dann die entsprechenden Berechtigungen für Ihre Back-End-App aus.

6. Wählen Sie Berechtigungen hinzufügen aus.

Optionalerweise:

1. Navigieren Sie zur Seite API-Berechtigungen Ihrer Client-App.

2. Wählen Sie Administratoreinwilligung für <Name_Ihres_Mandanten> erteilen aus, um im Namen aller Benutzer in diesem Verzeichnis die Einwilligung zu erteilen.

Konfigurieren eines OAuth 2.0-Autorisierungsservers in API Management

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.

2. Wählen Sie unter dem Entwicklerportal im Randleistenmenü OAuth 2.0 + OpenID Connect aus.

3. Wählen Sie auf der Registerkarte OAuth 2.0 die Option + Hinzufügen aus.

   

4. Geben Sie in die Felder Name und Beschreibung einen Namen bzw. eine optionale Beschreibung ein.

   Hinweis

   Anhand dieser Felder wird der OAuth 2.0-Autorisierungsserver innerhalb der aktuellen Instanz des API Management-Diensts identifiziert. Ihre Werte stammen nicht vom OAuth 2.0-Server.

5. Geben Sie die URL der Clientregistrierungsseite ein, https://contoso.com/loginz. B. . Auf dieser Seite können Benutzer*innen ihre Konten erstellen und verwalten, sofern Ihr OAuth 2.0-Anbieter die Benutzerverwaltung von Konten unterstützt. Die Seite variiert abhängig vom verwendeten OAuth 2.0-Anbieter.

   Wenn für Ihren OAuth 2.0-Anbieter keine Benutzerverwaltung für Konten konfiguriert ist, geben Sie hier eine Platzhalter-URL ein, z. B. die URL Ihres Unternehmens oder eine URL wie http://localhost.

   

6. Der nächste Abschnitt des Formulars enthält die Einstellungen Autorisierungsberechtigungstypen, Autorisierungsendpunkt-URL und Autorisierungsanforderungsmethode.

   • Wählen Sie eine oder mehrere gewünschte Autorisierungsarten aus. Wählen Sie in diesem Beispiel Autorisierungscode (Standardoption) aus. Weitere Informationen finden Sie unter Autorisierungsgenehmigungstypen.

   • Geben Sie die Autorisierungsendpunkt-URLein. Sie können die Endpunkt-URL auf der Seite Endpunkte einer Ihrer App-Registrierungen abrufen. Bei einer Einzelmandanten-App in Microsoft Entra ID ähnelt diese URL einer der folgenden URLs, wobei <your-tenant> sie durch die ID Ihres Microsoft Entra-Mandanten ersetzt wird.

     Die Verwendung des v2-Endpunkts wird empfohlen. API Management unterstützt jedoch sowohl v1- als auch v2-Endpunkte.

     https://login.microsoftonline.com/<your-tenant>/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/<your-tenant>/oauth2/authorize (v1)

   • Über Methode für Autorisierungsanforderung wird festgelegt, wie die Autorisierungsanforderung an den OAuth 2.0-Server gesendet wird. Wählen Sie POSTaus.

     

7. Geben Sie die URL für Tokenendpunkt, Methoden für Clientauthentifizierung, die Sendemethode für Zugriffstoken und den Standardbereich an.

   • Geben Sie die URL des Token-Endpunkts ein. Bei einer einzelnen Mandanten-App in Microsoft Entra ID ähnelt sie einer der folgenden URLs, wobei <your-tenant> sie durch die ID Ihres Microsoft Entra-Mandanten ersetzt wird. Verwenden Sie die gleiche Endpunktversion (v2 oder v1), die Sie zuvor ausgewählt haben.

     https://login.microsoftonline.com/<your-tenant>/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/<your-tenant>/oauth2/token (v1)

   • Wenn Sie v1-Endpunkte verwenden, fügen Sie einen body-Parameter hinzu:
     * Name: Ressource
     * Wert: Anwendungs-ID (Client) der Back-End-App

   • Wenn Sie v2-Endpunkte verwenden:
     * Geben Sie den Back-End-App-Bereich ein, den Sie im Feld Standardbereich erstellt haben.
     * Legen Sie den Wert der Eigenschaft requestedAccessTokenVersion im Anwendungsmanifest für die Registrierungen der Back-End-App und der Client-App auf 2 fest.

   • Übernehmen Sie die Standardeinstellungen für Methoden für Clientauthentifizierung und Sendemethode für Zugriffstoken.

8. Geben Sie in Clientanmeldeinformationen die Werte für Client-ID und Geheimer Clientschlüssel ein, die Sie beim Erstellen und Konfigurieren Ihrer Client-App abgerufen haben.

9. Nachdem die Werte für Client-ID und Geheimer Clientschlüssel angegeben wurden, wird der Umleitungs-URI für den Autorisierungscode generiert. Dieser URI wird zum Konfigurieren des Umleitungs-URI in Ihrer OAuth 2.0-Serverkonfiguration verwendet.

   Im Entwicklerportal hat das URI-Suffix das folgende Format:

   • /signin-oauth/code/callback/<authServerName> für den Flow zur Autorisierungscodegenehmigung
   • /signin-oauth/implicit/callback für den Flow zur impliziten Genehmigung

   

   Kopieren Sie den entsprechenden Umleitungs-URI auf die Seite Authentifizierung Ihrer Client-App-Registrierung. Wählen Sie in der App-Registrierung Authentifizierung>+ Plattform hinzufügen>Web aus, und geben Sie dann den Umleitungs-URI ein.

10. Falls für Autorisierungsberechtigungstypen die Einstellung Ressourcenbesitzer-Kennwort festgelegt ist, werden diese Berechtigungen im Abschnitt Ressourcenbesitzer-Kennwortberechtigungen festgelegt. Andernfalls lassen Sie den Abschnitt leer.

11. Wählen Sie Erstellen aus, um die OAuth 2.0-Autorisierungsserverkonfiguration für API Management zu speichern.

12. Sie müssen das Entwicklerportal erneut veröffentlichen.

    Wichtig

    Achten Sie beim Vornehmen von Änderungen, die OAuth 2.0 betreffen, darauf, das Entwicklerportal nach jeder relevanten Modifikation, wie etwa einer Änderung des Bereichs, erneut zu veröffentlichen. Andernfalls können die Änderungen nicht in das Portal übernommen werden und stehen beim Testen der APIs nicht zur Verfügung.

Konfigurieren einer API zum Verwenden der OAuth 2.0-Benutzerauthentifizierung

Nach dem Speichern der OAuth 2.0-Serverkonfiguration konfigurieren Sie eine API oder APIs für die Nutzung dieser Konfiguration.

1. Wählen Sie unter "APIs " im Randleistenmenü APIs aus.

2. Wählen Sie den Namen der gewünschten API und dann die Registerkarte Einstellungen aus. Scrollen Sie zum Abschnitt Sicherheit, und wählen Sie dann OAuth 2.0 aus.

3. Wählen Sie in der Dropdownliste den gewünschten Autorisierungsserver und dann Speichern aus.

   

Entwicklerportal: Testen der OAuth 2.0-Benutzerautorisierung

Nachdem Sie Ihren OAuth 2.0-Autorisierungsserver und Ihre API zu dessen Nutzung konfiguriert haben, können Sie ihn testen, indem Sie zum Entwicklerportal wechseln und eine API aufrufen.

1. Wählen Sie auf der Seite Übersicht der Azure API Management-Instanz im oberen Menü Entwicklerportal aus.

2. Navigieren Sie im Entwicklerportal zu einem beliebigen Vorgang unter der API.

3. Wählen Sie Ausprobieren aus, um zur Entwicklerkonsole zu gelangen.

4. Beachten Sie ein neues Element im Abschnitt Autorisierung, das dem soeben hinzugefügten Autorisierungsserver entspricht.

5. Wählen Sie in der Dropdownliste „Autorisierung“ die Option Autorisierungscode aus.

   

6. Sobald Sie dazu aufgefordert werden, melden Sie sich bei dem Microsoft Entra-Mandanten an.

   • Wenn Sie bereits beim Konto angemeldet sind, werden Sie möglicherweise nicht dazu aufgefordert.

7. Nach der erfolgreichen Anmeldung wird der Anforderung ein Authorization-Header mit einem Zugriffstoken von Microsoft Entra ID hinzugefügt. Im Folgenden finden Sie ein abgekürztes Beispieltoken (Base64-codiert):

   Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
   

8. Konfigurieren Sie die gewünschten Werte für die verbleibenden Parameter, und wählen Sie Senden aus, um die API aufzurufen.

Konfigurieren einer JWT-Validierungsrichtlinie zum Vorabautorisieren von Anforderungen

In der bisherigen Konfiguration überprüft API Management das Zugriffstoken nicht. Es wird nur das Token im Autorisierungsheader an die Back-End-API übergeben.

Um Anforderungen vorzuautorisieren, konfigurieren Sie eine Validate-jwt-Richtlinie , um das Zugriffstoken jeder eingehenden Anforderung zu überprüfen. Wenn für eine Anforderung kein gültiges Token vorliegt, wird sie von API Management blockiert. Wenn Sie den Anbieter Microsoft Entra ID verwenden, können Sie auch die Richtlinie validate-azure-ad-token nutzen.

Wenn die folgende Beispielrichtlinie dem Richtlinienabschnitt <inbound> hinzugefügt wird, überprüft sie den Wert des Zielgruppenanspruchs in einem aus Microsoft Entra ID abgerufenen Zugriffstoken, das im Autorisierungsheader angegeben wird. Wenn das Token ungültig ist, wird ein Fehler zurückgegeben. Konfigurieren Sie diese Richtlinie in einem Richtlinienbereich, der für Ihr Szenario geeignet ist.

• In der openid-config-URL ist aad-tenant die Mandanten-ID in Microsoft Entra ID. Ermitteln Sie diesen Wert im Azure-Portal, beispielsweise auf der Seite Übersicht Ihrer Microsoft Entra-Ressource. Das gezeigte Beispiel setzt eine Microsoft Entra-App mit einem einzelnen Mandanten und einen v2-Konfigurationsendpunkt voraus.
• Der Wert für claim ist die Client-ID der Back-End-App, die Sie in Microsoft Entra ID registriert haben.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Informationen zum Konfigurieren von Richtlinien finden Sie unter How to set or edit Azure API Management policies (Festlegen oder Bearbeiten von Azure API Management-Richtlinien). Weitere Anpassungen für JWT-Validierungen finden Sie unter dem Verweis validate-jwt. Um ein JWT zu überprüfen, das vom Microsoft Entra-Dienst bereitgestellt wurde, stellt API Management auch die validate-azure-ad-token-Richtlinie bereit.

Zugehöriger Inhalt

• Schützen einer API in Azure API Management mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID
• Microsoft-Identitätsplattform und der OAuth 2.0-Autorisierungscode-Flow