Delen via

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 dan Microsoft Entra.

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

Kenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
tenant-id Tenant-id of URL van de Microsoft Entra ID-tenant of een van de volgende bekende tenants:

- organizations of https://login.microsoftonline.com/organizations : tokens toestaan van accounts in elke organisatiemap (elke Microsoft Entra-directory)
- common of https://login.microsoftonline.com/common : tokens toestaan van accounts in elke organisatiedirectory (elke Microsoft Entra-directory) en van persoonlijke Microsoft-accounts (bijvoorbeeld Skype, XBox)

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 Snaar. 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. Nee
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
ontsleutelingssleutels Een lijst key met subelementen die worden gebruikt om een token te ontsleutelen dat is ondertekend met een asymmetrische sleutel. Als er meerdere sleutels aanwezig zijn, wordt elke sleutel geprobeerd totdat alle sleutels zijn uitgeput (in dat geval mislukt de validatie) of een sleutel slaagt.

Geef de openbare sleutel op met behulp van een certificate-id kenmerk met de waarde die is ingesteld op de id van een certificaat dat is geüpload naar API Management.		 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.
lucifer 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 Snaar. 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.

sleutelkenmerken

Kenmerk Beschrijving Vereist Standaardinstelling
certificaat-id Id van een certificaatentiteit die is geüpload naar API Management, die wordt gebruikt om de openbare sleutel op te geven om een token te verifiëren dat is ondertekend met een asymmetrische sleutel. Ja 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 Microsoft-tenant-id is de bekende organizations tenant, waarmee tokens van accounts in elke organisatiemap zijn toegestaan. De hostnaam wordt geleverd met behulp van een beleidsexpressie en de clienttoepassings-id wordt geleverd met behulp van een benoemde waarde. 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="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>

Gerelateerde inhoud

Zie voor meer informatie over het werken met beleid: