Microsoft Entra-token valideren

  • Artikel

VAN TOEPASSING OP: Alle API Management-lagen

Het validate-azure-ad-token beleid dwingt het bestaan en de geldigheid af van een JSON-webtoken (JWT) dat is geleverd door de Microsoft Entra-service (voorheen Azure Active Directory) voor een opgegeven set principals in de directory. De JWT kan worden geëxtraheerd uit een opgegeven HTTP-header, queryparameter of -waarde met behulp van een beleidsexpressie of contextvariabele.

Notitie

Api Management biedt ook het algemene validate-jwt beleid om een JWT te valideren die is geleverd door een andere id-provider.

Notitie

Stel de elementen en onderliggende elementen van het beleid in de volgorde in die in de beleidsverklaring is opgegeven. Meer informatie over het instellen of bewerken van API Management-beleid.

Beleidsinstructie

<validate-azure-ad-token
    tenant-id="tenant ID or URL (for example, "contoso.onmicrosoft.com") of the Azure Active Directory service"
    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 Azure Active Directory</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 Azure Active Directory</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>
</validate-azure-ad-token>

Kenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
tenant-id Tenant-id of URL van de Microsoft Entra-service. Beleidsexpressies zijn toegestaan. Ja N.v.t.
header-name De naam van de HTTP-header met het token. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. Authorization
query-parameter-name De naam van de queryparameter die het token bevat. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. N.v.t.
tokenwaarde Expressie die een tekenreeks retourneert die het token bevat. U mag niet retourneren Bearer als onderdeel van de tokenwaarde. Beleidsexpressies zijn toegestaan. Een van header-name, query-parameter-name of token-value moet worden opgegeven. N.v.t.
failed-validation-httpcode HTTP-statuscode die moet worden geretourneerd als de JWT geen validatie doorgeeft. Beleidsexpressies zijn toegestaan. Nee 401
failed-validation-error-message Foutbericht dat moet worden geretourneerd in de hoofdtekst van het HTTP-antwoord als de JWT de validatie niet doorstaan. Dit bericht moet speciale tekens bevatten die correct zijn ontsnapt. Beleidsexpressies zijn toegestaan. Nee Het standaardfoutbericht is afhankelijk van het validatieprobleem, bijvoorbeeld 'JWT niet aanwezig'.
output-token-variable-name Tekenreeks. Naam van contextvariabele die tokenwaarde als object van het type Jwt ontvangt bij geslaagde tokenvalidatie. Beleidsexpressies zijn niet toegestaan. Nee N.v.t.

Elementen

Element Beschrijving Vereist
Publiek Bevat een lijst met acceptabele doelgroepclaims die aanwezig kunnen zijn op het token. Als er meerdere audience waarden aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat één is geslaagd. Beleidsexpressies zijn toegestaan. Nee
back-endtoepassings-id's Bevat een lijst met acceptabele back-endtoepassings-id's. Dit is alleen vereist in geavanceerde gevallen voor de configuratie van opties en kan over het algemeen worden verwijderd. Beleidsexpressies zijn niet toegestaan. Nee
client-application-id's Bevat een lijst met acceptabele clienttoepassings-id's. Als er meerdere application-id elementen aanwezig zijn, wordt elke waarde geprobeerd totdat alle waarden zijn uitgeput (in dat geval mislukt de validatie) of totdat één is geslaagd. Als er geen clienttoepassings-id is opgegeven, moeten een of meer audience claims worden opgegeven. Beleidsexpressies zijn niet toegestaan. Ja
vereiste claims Bevat een lijst met claim elementen voor claimwaarden die naar verwachting aanwezig zijn op het token, zodat het als geldig kan worden beschouwd. Wanneer het match kenmerk is ingesteld op all, moet elke claimwaarde in het beleid aanwezig zijn in het token om te kunnen worden gevalideerd. Wanneer het match kenmerk is ingesteld op any, moet er ten minste één claim aanwezig zijn in het token om de validatie te voltooien. Beleidsexpressies zijn toegestaan. Nee

claimkenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
naam De naam van de claim zoals verwacht wordt weergegeven in het token. Beleidsexpressies zijn toegestaan. Ja N.v.t.
Overeenkomen met Het match kenmerk op het claim element geeft aan of elke claimwaarde in het beleid aanwezig moet zijn in het token om te kunnen worden gevalideerd. Mogelijke waarden zijn:

- all - elke claimwaarde in het beleid moet aanwezig zijn in het token om te kunnen worden gevalideerd.

- any - ten minste één claimwaarde moet aanwezig zijn in het token om de validatie te voltooien.

Beleidsexpressies zijn toegestaan.		 Nee Alles
scheidingsteken Tekenreeks. Hiermee geeft u een scheidingsteken (bijvoorbeeld ',') op dat moet worden gebruikt voor het extraheren van een set waarden uit een claim met meerdere waarden. Beleidsexpressies zijn toegestaan. Nee N.v.t.

Gebruik

Gebruiksnotities

  • U kunt toegangsbeperkingsbeleid in verschillende bereiken voor verschillende doeleinden gebruiken. U kunt bijvoorbeeld de hele API beveiligen met Microsoft Entra-verificatie door het validate-azure-ad-token beleid toe te passen op API-niveau, of u kunt deze toepassen op het niveau van de API-bewerking en deze gebruiken claims voor gedetailleerdere controle.
  • Microsoft Entra-id voor klanten (preview) wordt niet ondersteund.

Voorbeelden

Eenvoudige tokenvalidatie

Het volgende beleid is de minimale vorm van het validate-azure-ad-token beleid. Er wordt verwacht dat de JWT wordt opgegeven in de standaardheader Authorization met behulp van het Bearer schema. In dit voorbeeld worden de tenant-id en clienttoepassings-id van Microsoft Entra opgegeven met behulp van benoemde waarden.

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

Controleer of de doelgroep en claim juist zijn

Het volgende beleid controleert of de doelgroep de hostnaam is van het API Management-exemplaar en dat de ctry claim is US. De hostnaam wordt geleverd met behulp van een beleidsexpressie en de Tenant-id van Microsoft Entra en de clienttoepassings-id worden geleverd met behulp van benoemde waarden. De gedecodeerde JWT wordt na validatie opgegeven in de jwt variabele.

Lees Optionele claims opgeven voor uw app voor meer informatie over optionele claims.

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}" 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>

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: