Schützen einer API in Azure API Management mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel erfahren Sie detaillierte Schritte, um Ihre Azure API Management-Instanz so konfigurieren, dass eine API über das OAuth 2.0-Protokoll mit Microsoft Entra ID geschützt ist.

Eine Konzept-Übersicht über die API-Autorisierung finden Sie unter Authentifizierung und Autorisierung an APIs im API-Management.

Voraussetzungen

Bevor Sie die Schritte in diesem Artikel ausführen können, benötigen Sie Folgendes:

  • Eine API Management-Instanz
  • Eine veröffentlichte API, die die API Management-Instanz verwendet
  • Ein Microsoft Entra-Mandant

Überblick

Führen Sie diese Schritte aus, um eine API in API Management mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID zu schützen.

  1. Registrieren Sie eine Anwendung (in diesem Artikel als Back-End-App bezeichnet) in Microsoft Entra ID, um den Zugriff auf die API zu schützen.

    Um auf die API zuzugreifen, erwerben Benutzer oder Anwendungen ein gültiges OAuth-Token, das Zugriff auf diese App mit jeder API-Anforderung gewährt.

  2. Konfigurieren Sie die Richtlinie „validate-jwt“ in API Management, um das in jeder eingehenden API-Anforderung dargestellte OAuth-Token zu überprüfen. Gültige Anforderungen können an die API übergeben werden.

Details zu OAuth-Autorisierungsflüssen und zum Generieren der erforderlichen OAuth-Token gehen über den Umfang dieses Artikels hinaus. In der Regel wird eine separate Client-App verwendet, um Token von Microsoft Entra ID abzurufen, die den Zugriff auf die API autorisieren. Links mit weiteren Informationen finden Sie im Abschnitt Nächste Schritte.

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

Schützen Sie eine API mit Microsoft Entra ID unter Verwendung des Azure-Portals, indem Sie zunächst eine Anwendung registrieren, die die API darstellt.

Ausführliche Informationen zur App-Registrierung finden Sie unter Schnellstart: Konfigurieren einer Anwendung für das Verfügbarmachen von Web-APIs

  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.

  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. Wenn Sie eine separate Client-App entwickeln, um OAuth 2.0-Token für den Zugriff auf die Back-End-App abzurufen, notieren Sie diesen Wert später.

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

    1. Geben Sie einen neuen Bereichsnamen ein, einen Anzeigenamen der Administratoreinwilligung und eine Beschreibung der Administratoreinwilligung.
    2. 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 für eine spätere Verwendung.

Konfigurieren einer JWT-Überprüfungsrichtlinie zur Vorautorisierung von Anforderungen

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>

Hinweis

Die obige openid-config-URL entspricht dem v2-Endpunkt. Verwenden Sie für den v1-openid-config-Endpunkt https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

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.

Autorisierungsworkflow

  1. Ein*e Benutzer*in oder eine Anwendung erwirbt ein Token von Microsoft Entra ID mit Berechtigungen, die Zugriff auf die Back-End-App gewähren.

  2. Das Token wird im Autorisierungsheader der API-Anforderungen an das API Management hinzugefügt.

  3. Das API Management überprüft das Token mithilfe der Richtlinie „validate-jwt“.

    • Wenn für eine Anforderung kein gültiges Token vorliegt, wird sie von API Management blockiert.

    • Wenn eine Anforderung von einem gültigen Token begleitet wird, kann das Gateway die Anforderung an die API weiterleiten.

Nächste Schritte