Überprüfen des Microsoft Entra-Tokens

  • Artikel

GILT FÜR: Alle API Management-Ebenen

Die Richtlinie validate-azure-ad-token erzwingt das Vorhandensein und die Gültigkeit eines JSON Web Tokens (JWT), das vom Microsoft Entra-Dienst (ehemals Azure Active Directory) bereitgestellt wurde für eine vorgegebene Gruppe von Prinzipalen im Verzeichnis. Das JWT kann aus einem angegebenen HTTP-Header, Abfrageparameter oder Wert extrahiert werden, der mithilfe eines Richtlinienausdrucks oder einer Kontextvariablen bereitgestellt wird.

Hinweis

Um ein JWT zu überprüfen, das von einem anderen Identitätsanbieter als Microsoft Entra bereitgestellt wurde, stellt API Management auch die generische Richtlinie validate-jwt bereit.

Hinweis

Legen Sie die Elemente und untergeordneten Elemente einer Richtlinie in der Reihenfolge fest, die in der Richtlinienanweisung angegeben ist. Erfahren Sie mehr darüber, wie Sie API Management-Richtlinien festlegen oder bearbeiten.

Richtlinienanweisung

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "https://contoso.onmicrosoft.com") of the Microsoft Entra ID tenant"
    header-name="name of HTTP header containing the token (alternatively, use query-parameter-name or token-value attribute to specify token)"
    query-parameter-name="name of query parameter used to pass the token (alternative, use header-name or token-value attribute to specify token)"
    token-value="expression returning the token as a string (alternatively, use header-name or query-parameter attribute to specify token)"
    failed-validation-httpcode="HTTP status code to return on failure"
    failed-validation-error-message="error message to return on failure"
    output-token-variable-name="name of a variable to receive a JWT object representing successfully validated token">
    <client-application-ids>
        <application-id>Client application ID from Microsoft Entra</application-id>
        <!-- If there are multiple client application IDs, then add additional application-id elements -->
    </client-application-ids>
    <backend-application-ids>
        <application-id>Backend application ID from Microsoft Entra</application-id>
        <!-- If there are multiple backend application IDs, then add additional application-id elements -->
    </backend-application-ids>
    <audiences>
        <audience>audience string</audience>
        <!-- if there are multiple possible audiences, then add additional audience elements -->
    </audiences>
    <required-claims>
        <claim name="name of the claim as it appears in the token" match="all|any" separator="separator character in a multi-valued claim">
            <value>claim value as it is expected to appear in the token</value>
            <!-- if there is more than one allowed value, then add additional value elements -->
        </claim>
        <!-- if there are multiple possible allowed values, then add additional value elements -->
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Attribute

Attribut BESCHREIBUNG Erforderlich Standard
tenant-id Mandanten-ID oder URL des Microsoft Entra ID-Mandanten oder eines der folgenden bekannten Mandanten:

- organizations oder https://login.microsoftonline.com/organizations – damit Token von Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis) zugelassen werden
- common oder https://login.microsoftonline.com/common – damit Token von Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis) und von persönlichen Microsoft-Konten (z. B. Skype, Xbox) zugelassen werden

Richtlinienausdrücke sind zulässig.		 Ja –
header-name Der Name des HTTP-Headers, der das Token enthält. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. Authorization
query-parameter-name Der Name des Abfrageparameters, der das Token enthält. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. –
token-value Ausdruck, der eine Zeichenfolge mit Token zurückgibt. Bearer darf nicht als Teil des Tokenwerts zurückgegeben werden. Richtlinienausdrücke sind zulässig. Eines von header-name, query-parameter-name oder token-value muss angegeben werden. –
failed-validation-httpcode Der HTTP-Statuscode, der zurückgegeben werden soll, wenn das JWT die Überprüfung nicht besteht. Richtlinienausdrücke sind zulässig. Nein 401
failed-validation-error-message Die Fehlermeldung, die im HTTP-Antworttext zurückgegeben werden soll, wenn das JWT die Überprüfung nicht besteht. In dieser Meldung müssen alle Sonderzeichen ordnungsgemäß mit Escapezeichen versehen sein. Richtlinienausdrücke sind zulässig. Nein Die Standardfehlermeldung hängt vom Überprüfungsproblem ab, z.B. „JWT nicht vorhanden“.
output-token-variable-name Eine Zeichenfolge. Der Name der Kontextvariablen, die den Tokenwert bei erfolgreicher Tokenüberprüfung als ein Objekt des Typs Jwt empfängt. Richtlinienausdrücke sind nicht zulässig. Nein –

Elemente

Element BESCHREIBUNG Erforderlich
audiences Enthält eine Liste der zulässigen audience-Ansprüche, die im Token vorhanden sein können. Wenn mehrere audience-Werte vorhanden sind, wird jeder Wert ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Überprüfungsfehler) oder ein Wert erfolgreich ist. Richtlinienausdrücke sind zulässig. Nein
backend-application-ids Enthält eine Liste der zulässigen Back-End-Anwendungs-IDs. Dies ist nur in erweiterten Fällen für die Konfiguration von Optionen erforderlich und kann in der Regel entfernt werden. Richtlinienausdrücke sind nicht zulässig. Nein
client-application-ids Enthält eine Liste der zulässigen Clientanwendungs-IDs. Wenn mehrere application-id-Elemente vorhanden sind, wird jeder Wert ausprobiert, bis entweder alle verbraucht sind (in diesem Fall gibt es einen Überprüfungsfehler) oder ein Wert erfolgreich ist. Wenn keine Clientanwendungs-ID angegeben wird, sollte mindestens ein audience-Anspruch angegeben werden. Richtlinienausdrücke sind nicht zulässig. No
required-claims Enthält eine Liste von claim-Elementen für Anspruchswerte, deren Vorhandensein im Token erwartet wird, damit dieses als gültig eingestuft wird. Wenn das match-Attribut auf all festgelegt ist, muss jeder Anspruchswert in der Richtlinie im Token vorhanden sein, damit die Überprüfung erfolgreich ist. Wenn das match-Attribut auf any festgelegt ist, muss mindestens ein Anspruch im Token vorhanden sein, damit die Überprüfung erfolgreich ist. Richtlinienausdrücke sind zulässig. No
decryption-keys Eine Liste von Unterelementen von key, die verwendet werden, um ein Token zu entschlüsseln, das mit einem asymmetrischen Schlüssel signiert ist. Wenn mehrere Schlüssel vorhanden sind, wird jeder Schlüssel ausprobiert, bis entweder alle verbraucht sind (in diesem Fall tritt ein Validierungsfehler auf) oder ein Schlüssel erfolgreich ist.

Geben Sie den öffentlichen Schlüssel mithilfe eines certificate-id-Attributs mit dem Wert des Bezeichners eines in API Management hochgeladenen Zertifikats an.		 No

Anspruchsattribute

attribute BESCHREIBUNG Erforderlich Standard
name Name des Anspruchs, wie er im Token angezeigt werden soll. Richtlinienausdrücke sind zulässig. Ja –
match Das match-Attribut im claim-Element gibt an, ob jeder Anspruchswert in der Richtlinie im Token vorhanden sein muss, damit die Überprüfung erfolgreich ist. Mögliche Werte:

- all – jeder Anspruchswert in der Richtlinie muss im Token vorhanden sein, damit die Überprüfung erfolgreich ist.

- any – mindestens ein Anspruchswert in der Richtlinie muss im Token vorhanden sein, damit die Überprüfung erfolgreich ist.

Richtlinienausdrücke sind zulässig.		 Nein alle
Trennzeichen Zeichenfolge. Gibt ein Trennzeichen (z. B. „,“) zum Extrahieren eines Satzes von Werten aus einem mehrwertigen Anspruch an. Richtlinienausdrücke sind zulässig. Nein –

Schlüsselattribute

attribute BESCHREIBUNG Erforderlich Standard
certificate-id Bezeichner einer in API Management hochgeladenen Zertifikatentität, mit der der öffentliche Schlüssel zum Überprüfen eines Tokens, das mit einem asymmetrischen Schlüssel signiert ist, angegeben wird. Ja –

Verwendung

Hinweise zur Verwendung

  • Sie können Richtlinien für die Zugriffsbeschränkung in verschiedenen Bereichen zu unterschiedlichen Zwecken verwenden. Sie können beispielsweise die gesamte API mit der Microsoft Entra-Authentifizierung sichern, indem Sie die validate-azure-ad-token-Richtlinie auf API-Ebene anwenden, oder Sie können sie auf API-Vorgangsebene anwenden und claims für eine genauere Kontrolle verwenden.
  • Microsoft Entra ID für Kunden (Preview) wird nicht unterstützt.

Beispiele

Einfache Tokenüberprüfung

Die folgende Richtlinie ist die minimale Form der validate-azure-ad-token-Richtlinie. Es wird erwartet, dass das JWT im Standard-Authorization-Header mithilfe des Bearer-Schemas bereitgestellt wird. In diesem Beispiel werden die Microsoft Entra-Mandanten-ID und die Clientanwendungs-ID mit benannten Werten bereitgestellt.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
</validate-azure-ad-token>

Überprüfen, ob Zielgruppe und Anspruch richtig sind

Mit der folgenden Richtlinie wird überprüft, ob die Zielgruppe der Hostname der API Management-Instanz ist, und ob US der ctry-Anspruch ist. Die Microsoft-Mandanten-ID ist der bekannte Mandant organizations, der Token von Konten in jedem Organisationsverzeichnis zulässt. Der Hostname wird mithilfe eines Richtlinienausdrucks bereitgestellt, und die Clientanwendungs-ID wird mit einem benannten Wert bereitgestellt. Das decodierte JWT wird nach der Überprüfung in der jwt-Variablen bereitgestellt.

Weitere Informationen zu optionalen Ansprüchen finden Sie unter Bereitstellen optionaler Ansprüche für Ihre App.

<validate-azure-ad-token tenant-id="organizations" output-token-variable-name="jwt">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <audiences>
        <audience>@(context.Request.OriginalUrl.Host)</audience>
    </audiences>
    <required-claims>
        <claim name="ctry" match="any">
            <value>US</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

Zugehöriger Inhalt

Weitere Informationen zum Arbeiten mit Richtlinien finden Sie hier: