Dela via

Verifiera Microsoft Entra-token

  • Artikel

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 än Microsoft Entra.

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

Attribut

Attribut beskrivning Obligatoriskt Standardvärde
klientorganisation-id Klientorganisations-ID eller URL för Microsoft Entra ID-klientorganisationen, eller någon av följande välkända klienter:

- organizations eller https://login.microsoftonline.com/organizations – för att tillåta token från konton i valfri organisationskatalog (alla Microsoft Entra-kataloger)
- common eller https://login.microsoftonline.com/common – för att tillåta token från konton i valfri organisationskatalog (valfri Microsoft Entra-katalog) och från personliga Microsoft-konton (till exempel Skype, XBox)

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å allmåste varje anspråksvärde i principen finnas i token för att verifieringen ska lyckas. match När attributet är inställt på anymåste minst ett anspråk finnas i token för att verifieringen ska lyckas. Principuttryck tillåts. Nej
dekrypteringsnycklar En lista över key underelement som används för att dekryptera en token signerad med en asymmetrisk nyckel. Om det finns flera nycklar provas varje nyckel tills antingen alla nycklar är uttömda (i vilket fall verifieringen misslyckas) eller så lyckas en nyckel.

Ange den offentliga nyckeln med ett certificate-id attribut med värdet inställt på identifieraren för ett certifikat som laddats upp till API Management.		 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
tändsticka 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
separator 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

nyckelattribut

Attribut beskrivning Obligatoriskt Standardvärde
certifikat-ID Identifierare för en certifikatentitet som laddats upp till API Management, som används för att ange den offentliga nyckeln för att verifiera en token signerad med en asymmetrisk nyckel. Ja Ej tillämpligt

Användning

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>

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>

Relaterat innehåll

Mer information om hur du arbetar med principer finns i: