Autorisieren der Testkonsole des Entwicklerportals durch Konfigurieren der OAuth 2.0-Benutzerautorisierung

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

Viele APIs unterstützen OAuth 2.0 zum Schützen der API und um sicherzustellen, dass nur autorisierte Benutzer Zugriff erhalten und nur auf die Ressourcen zugreifen können, für die sie berechtigt 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-Überprüfungsrichtlinie oder im Back-End-Dienst.

Voraussetzungen

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.

Falls Sie noch keine API Management-Dienstinstanz erstellt haben, finden Sie weitere Informationen unter Erstellen einer API Management-Dienstinstanz.

Ü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 finden Sie die allgemeinen Konfigurationsschritte:

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

2. Registrieren einer weiteren 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. Hinzufügen einer Richtlinie, um das OAuth 2.0-Token für jede eingehende Anforderung vorab zu autorisieren. 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 in API Management von Microsoft Entra ID überprüft.

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 Möglichkeit, mit der eine Clientanwendung (in diesem Kontext die Testkonsole im Entwicklerportal) ein Zugriffstoken für Ihre Back-End-API abzurufen. Je nach OAuth 2.0-Anbieter und Szenario können Sie einen oder mehrere Gewährungstypen konfigurieren.

Im Folgenden finden Sie 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.

  Abhängig von Ihren Szenarien können Sie mehr oder weniger restriktive Tokenbereiche für andere Clientanwendungen für den Zugriff auf Back-End-APIs konfigurieren.

• Seien Sie beim Aktivieren des Flows für die Clientanmeldeinformationen besonders vorsichtig. Die Testkonsole im Entwicklerportal fragt bei der Arbeit mit dem Flow für Clientanmeldeinformationen keine Anmeldeinformationen ab. Ein Zugriffstoken kann versehentlich für Entwickler*innen oder anonyme Benutzer*innen der Entwicklerkonsole verfügbar gemacht werden.

Nachverfolgen von wichtigen Informationen

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

• ID der Back-End-Anwendung (Client): Die GUID der Anwendung, die die Back-End-API darstellt
• Back-End-Anwendungsbereiche: Mindestens ein Bereich, den Sie zum Zugreifen auf die API erstellen können. Das Bereichsformat lautet api://<Backend Application (client) ID>/<Scope Name> (Beispiel: api://1764e900-1827-4a0b-9182-b2c1841864c2/Read).
• ID der Clientanwendung (Client): Die GUID der Anwendung, die das Entwicklerportal darstellt
• Geheimniswert für die Clientanwendung: Die GUID, die als Geheimnis für die Interaktion mit der Clientanwendung in Microsoft Entra ID fungiert

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 und eine zweite 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 Schnellstart: Konfigurieren einer Anwendung für das Verfügbarmachen von Web-APIs

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

1. Suchen Sie im Azure-Portal nach App-Registrierungen, und wählen Sie den Eintrag 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 den Benutzern der App angezeigt wird, beispielsweise 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 API Management generiert wird.

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 App-Registrierungen, und wählen Sie den Eintrag 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 den Benutzern der App angezeigt wird, beispielsweise 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 den Eintrag aus.

2. Wählen Sie Ihre Client-App aus. Wählen Sie dann im Seitenmenü die Option API-Berechtigungen aus.

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

4. Wählen Sie unter API auswählen die Option Meine APIs aus, suchen Sie dann die Back-End-App, 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.

Optional:

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

2. Wählen Sie Administratoreinwilligung für <Name_Ihres_Mandanten> erteilen aus, um die Einwilligung im Auftrag aller Benutzer in diesem Verzeichnis 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 Entwicklerportal im seitlichen Menü 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 Seiten-URL für Clientregistrierung ein, z. B. https://contoso.com/login. 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 unter Autorisierungszuweisungstypen mindestens eine Option aus. Wählen Sie in diesem Beispiel Autorisierungscode (Standardoption) aus. Weitere Informationen

   • Geben Sie die Autorisierungsendpunkt-URLein. Sie können die Endpunkt-URL auf der Seite Endpunkte einer Ihrer App-Registrierungen abrufen. Für eine Einzelmandanten-App in Microsoft Entra ID lautet diese URL ähnlich wie eine der folgenden URLs, wobei {aad-tenant} 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/{aad-tenant}/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/{aad-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 unter URL für Tokenendpunkt die URL ein. Für eine Einzelmandanten-App in Microsoft Entra ID lautet diese URL ähnlich wie eine der folgenden URLs, wobei {aad-tenant} 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/{aad-tenant}/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/{aad-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 für die Eigenschaft accessTokenAcceptedVersion im Anwendungsmanifest für die Registrierung der Back-End-App und die Registrierung 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

    Stellen Sie bei Änderungen im Zusammenhang mit OAuth 2.0 sicher, dass das Entwicklerportal nach jeder Änderung (erneut) neu veröffentlicht wird, da relevante Änderungen (etwa eine Bereichsänderung) andernfalls nicht im Portal verteilt und anschließend nicht zum Ausprobieren der APIs verwendet werden können.

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 im Menü API Management auf der linken Seite 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-Überprüfungsrichtlinie zur Vorautorisierung 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.

Konfigurieren Sie zur Vorautorisierung von Anforderungen die Richtlinie validate-jwt, um das Zugriffstoken für jede eingehende Anforderung zu überprüfen. Wenn für eine Anforderung kein gültiges Token vorliegt, wird sie von API Management blockiert.

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

• Weitere Informationen zur Verwendung von OAuth 2.0 und API Management finden Sie unter Schützen eines Web-API-Back-Ends in Azure API Management mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID.

• Weitere Informationen finden Sie unter Microsoft Identity Platform und der OAuth 2.0-Autorisierungscodeflow.