Verifiera Microsoft Entra-token

GÄLLER FÖR: Alla API Management-nivåer

Principen validate-azure-ad-token framtvingar förekomsten och giltigheten för en JSON-webbtoken (JWT) som tillhandahölls av Microsoft Entra-tjänsten (kallades tidigare Azure Active Directory) för en angiven uppsättning huvudnamn i katalogen. JWT kan extraheras från ett angivet HTTP-huvud, en frågeparameter eller ett värde som tillhandahålls med hjälp av ett principuttryck eller en kontextvariabel.

Principuttryck

<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)"
    authentication-endpoint="Microsoft Entra environment endpoint"
    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">
    <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>
    <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>
    <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>
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Attribut

Element

anspråksattribut

nyckelattribut

Förbrukning

• Principavsnitt: inkommande
• Principomfattningar: global, arbetsyta, produkt, API, åtgärd
• Gatewayer: klassisk, v2, förbrukning, lokalt installerad, arbetsyta

Användningsanteckningar

• Du kan använda principer för åtkomstbegränsning i olika omfång för olika syften. Du kan till exempel skydda hela API:et med Microsoft Entra-autentisering genom att tillämpa validate-azure-ad-token principen på API-nivå, eller så kan du tillämpa den på API-åtgärdsnivå och använda claims den för mer detaljerad kontroll.
• Microsoft Entra-ID för kunder (förhandsversion) stöds inte.

Exempel

Enkel tokenverifiering

Följande princip är principens validate-azure-ad-token minimala form. Den förväntar sig att JWT anges i standardrubriken Authorization med hjälp av Bearer schemat. I det här exemplet tillhandahålls Microsoft Entra-klient-ID och klientprogram-ID med namngivna värden.

<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>

Tokenverifiering med dekrypteringsnyckel

Det här exemplet visar hur du använder validate-azure-ad-token principen för att verifiera en token som dekrypteras med hjälp av en dekrypteringsnyckel. Klient-ID och klientprogram-ID för Microsoft Entra tillhandahålls med namngivna värden. Nyckeln anges med hjälp av ID:t för ett uppladdat certifikat (i PFX-format) som innehåller den offentliga nyckeln.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
    </decryption-keys>
</validate-azure-ad-token>

Verifiera att målgruppen och anspråket är korrekta

Följande princip kontrollerar att målgruppen är värdnamnet för API Management-instansen och att anspråket ctry är US. Microsofts klientorganisations-ID är den välkända organizations klientorganisationen, som tillåter token från konton i alla organisationskataloger. Värdnamnet tillhandahålls med ett principuttryck och klientprogram-ID:t tillhandahålls med hjälp av ett namngivet värde. Den avkodade JWT:en anges i variabeln jwt efter valideringen.

Mer information om valfria anspråk finns i Ange valfria anspråk till din 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>

Relaterade principer

• Autentisering och auktorisering

Relaterat innehåll

Mer information om hur du arbetar med principer finns i:

• Självstudie: Transformera och skydda ditt API
• Principreferens för en fullständig lista över principinstruktioner och deras inställningar
• Principuttryck
• Ange eller redigera principer
• Återanvända principkonfigurationer
• Lagringsplats för principfragment
• Lagringsplats för principlekplats
• Principverktyg för Azure API Management
• Få Hjälp med Copilot för att skapa, förklara och felsöka principer