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.
Kommentar
Api Management tillhandahåller även den allmänna validate-jwt
principen för att verifiera en JWT som tillhandahölls av en annan identitetsprovider.
Kommentar
Ange principens element och underordnade element i den ordning som anges i principbeskrivningen. Läs mer om hur du anger eller redigerar API Management-principer.
Principuttryck
<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>
Attribut
Attribut | beskrivning | Obligatoriskt | Standardvärde |
---|---|---|---|
klientorganisation-id | Klientorganisations-ID eller URL för Microsoft Entra-tjänsten. Principuttryck tillåts. | Ja | Ej tillämpligt |
rubriknamn | Namnet på HTTP-huvudet som innehåller token. Principuttryck tillåts. | En av header-name , query-parameter-name eller token-value måste anges. |
Authorization |
query-parameter-name | Namnet på frågeparametern som innehåller token. Principuttryck tillåts. | En av header-name , query-parameter-name eller token-value måste anges. |
Ej tillämpligt |
token-value | Uttryck som returnerar en sträng som innehåller token. Du får inte returnera Bearer som en del av tokenvärdet. Principuttryck tillåts. |
En av header-name , query-parameter-name eller token-value måste anges. |
Ej tillämpligt |
failed-validation-httpcode | HTTP-statuskod som ska returneras om JWT inte klarar valideringen. Principuttryck tillåts. | Nej | 401 |
failed-validation-error-message | Felmeddelande om att returnera i HTTP-svarstexten om JWT inte klarar valideringen. Det här meddelandet måste ha undantagna specialtecken. Principuttryck tillåts. | Nej | Standardfelmeddelandet beror på valideringsproblem, till exempel "JWT finns inte". |
output-token-variable-name | Sträng. Namn på kontextvariabel som ska ta emot tokenvärde som ett objekt av typen Jwt vid lyckad tokenverifiering. Principuttryck tillåts inte. |
Nej | Ej tillämpligt |
Element
Element | Description | Obligatoriskt |
---|---|---|
Publik | Innehåller en lista över godtagbara målgruppsanspråk som kan finnas på token. Om det finns flera audience värden provas varje värde tills alla är uttömda (i vilket fall verifieringen misslyckas) eller tills ett lyckas. Principuttryck tillåts. |
Nej |
backend-application-ids | Innehåller en lista över godkända program-ID:t för serverdelen. Detta krävs endast i avancerade fall för konfiguration av alternativ och kan vanligtvis tas bort. Principuttryck tillåts inte. | Nej |
client-application-ids | Innehåller en lista över godkända klientprogram-ID:t. Om det finns flera application-id element provas varje värde tills alla är uttömda (i vilket fall verifieringen misslyckas) eller tills ett lyckas. Om ett klientprogram-ID inte tillhandahålls bör ett eller flera audience anspråk anges. Principuttryck tillåts inte. |
Nej |
obligatoriska anspråk | Innehåller en lista över claim element för anspråksvärden som förväntas finnas på token för att den ska anses vara giltig. match När attributet är inställt på all måste varje anspråksvärde i principen finnas i token för att verifieringen ska lyckas. match När attributet är inställt på any måste minst ett anspråk finnas i token för att verifieringen ska lyckas. Principuttryck tillåts. |
Nej |
anspråksattribut
Attribut | beskrivning | Obligatoriskt | Standardvärde |
---|---|---|---|
name | Namnet på anspråket som det förväntas visas i token. Principuttryck tillåts. | Ja | Ej tillämpligt |
Matcha | Attributet match för elementet claim anger om varje anspråksvärde i principen måste finnas i token för att verifieringen ska lyckas. Möjliga värden är:- all – varje anspråksvärde i principen måste finnas i token för att verifieringen ska lyckas.- any – Minst ett anspråksvärde måste finnas i token för att verifieringen ska lyckas.Principuttryck tillåts. |
Nej | alla |
Avgränsare | Sträng. Anger en avgränsare (till exempel ",") som ska användas för att extrahera en uppsättning värden från ett anspråk med flera värden. Principuttryck tillåts. | Nej | Ej tillämpligt |
Användning
- Principavsnitt: inkommande
- Principomfattningar: global, arbetsyta, produkt, API, åtgärd
- Gatewayer: klassisk, v2, förbrukning, lokalt installerad
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ändaclaims
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>
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
. Värdnamnet tillhandahålls med hjälp av ett principuttryck och Microsoft Entra-klient-ID och klientprogram-ID tillhandahålls med hjälp av namngivna värden. 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="{{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>
Relaterade principer
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
- Skapa principer med Hjälp av Microsoft Copilot för Azure