Ověření tokenu Microsoft Entra

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Zásada validate-azure-ad-token vynucuje existenci a platnost webového tokenu JSON (JWT), který poskytla služba Microsoft Entra (dříve Označovaná jako Azure Active Directory) pro zadanou sadu objektů zabezpečení v adresáři. JWT lze extrahovat ze zadané hlavičky HTTP, parametru dotazu nebo hodnoty poskytnuté pomocí výrazu zásad nebo kontextové proměnné.

Poznámka:

K ověření JWT, který poskytl jiný zprostředkovatel identity, poskytuje služba API Management také obecné validate-jwt zásady.

Poznámka:

Nastavte prvky zásad a podřízené prvky v pořadí uvedeném v prohlášení o zásadách. Přečtěte si další informace o tom, jak nastavit nebo upravit zásady služby API Management.

Prohlášení o zásadách

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

Atributy

Atribut Popis Požaduje se Výchozí
tenant-id ID tenanta nebo adresa URL služby Microsoft Entra. Výrazy zásad jsou povolené. Yes –
header-name Název hlavičky HTTP, která token drží. Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. Authorization
název parametru dotazu Název parametru dotazu, který obsahuje token. Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. –
hodnota tokenu Výraz vracející řetězec obsahující token V rámci hodnoty tokenu nesmíte vracet Bearer . Výrazy zásad jsou povolené. Jedna z hodnot header-namenebo token-valuequery-parameter-name musí být zadána. –
failed-validation-httpcode Stavový kód HTTP, který se má vrátit, pokud JWT neprojde ověřením. Výrazy zásad jsou povolené. No 401
failed-validation-error-message Chybová zpráva, která se vrátí v textu odpovědi HTTP, pokud JWT neprojde ověřením. Tato zpráva musí obsahovat všechny speciální znaky, které jsou správně uchycené. Výrazy zásad jsou povolené. No Výchozí chybová zpráva závisí na problému s ověřením, například "JWT není k dispozici".
output-token-variable-name Řetězec. Název kontextové proměnné, která při úspěšném ověření tokenu obdrží hodnotu tokenu jako objekt typu Jwt . Výrazy zásad nejsou povolené. No –

Elementy

Element (Prvek) Popis Povinní účastníci
Publikum Obsahuje seznam přijatelných deklarací identity cílové skupiny, které se dají v tokenu prezentovat. Pokud existuje více audience hodnot, pak se každá hodnota pokusí, dokud se nevyčerpají všechny hodnoty (v takovém případě ověření selže) nebo dokud se jedna nezdaří. Výrazy zásad jsou povolené. No
back-end-application-ids Obsahuje seznam přijatelných ID back-endových aplikací. To se vyžaduje jenom v pokročilých případech pro konfiguraci možností a dá se obecně odebrat. Výrazy zásad nejsou povolené. No
client-application-ids Obsahuje seznam přijatelných ID klientských aplikací. Pokud existuje více application-id prvků, je každá hodnota vyzkoušena, dokud se nevyčerpají všechny (v takovém případě ověření selže) nebo dokud se jedna nezdaří. Pokud není zadané ID klientské aplikace, měla by být zadána jedna nebo více audience deklarací identity. Výrazy zásad nejsou povolené. Ano
required-claims Obsahuje seznam claim prvků pro hodnoty deklarací identity, u které se očekává, že token bude považován za platný. match Pokud je atribut nastaven na all, musí být každá hodnota deklarace identity v zásadě přítomna v tokenu, aby bylo ověření úspěšné. match Pokud je atribut nastaven na any, musí v tokenu existovat alespoň jedna deklarace identity, aby bylo ověření úspěšné. Výrazy zásad jsou povolené. No

atributy deklarace identity

Atribut Popis Požaduje se Výchozí
name Název deklarace identity, protože se očekává, že se v tokenu zobrazí. Výrazy zásad jsou povolené. Yes –
match Atribut match elementu claim určuje, zda každá hodnota deklarace identity v zásadě musí být přítomna v tokenu, aby bylo ověření úspěšné. Možné hodnoty jsou:

- all – Každá hodnota deklarace identity v zásadách musí být v tokenu, aby bylo ověření úspěšné.

- any – v tokenu musí existovat alespoň jedna hodnota deklarace identity, aby bylo ověření úspěšné.

Výrazy zásad jsou povolené.		 No vše
Oddělovač Řetězec. Určuje oddělovač (například ","), který se má použít k extrahování sady hodnot z deklarace identity s více hodnotami. Výrazy zásad jsou povolené. No –

Využití

Poznámky k využití

  • Zásady omezení přístupu můžete použít v různých oborech pro různé účely. Můžete například zabezpečit celé rozhraní API pomocí ověřování Microsoft Entra použitím validate-azure-ad-token zásad na úrovni rozhraní API nebo ho můžete použít na úrovni operace rozhraní API a použít claims ho k podrobnějšímu řízení.
  • ID Microsoft Entra pro zákazníky (Preview) se nepodporuje.

Příklady

Ověření jednoduchého tokenu

Následující zásada představuje minimální formu validate-azure-ad-token zásady. Očekává, že JWT bude k dispozici ve výchozí Authorization hlavičce pomocí schématu Bearer . V tomto příkladu se ID tenanta Microsoft Entra a ID klientské aplikace zadají pomocí pojmenovaných hodnot.

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

Ověření správnosti cílové skupiny a deklarace identity

Následující zásady kontrolují, že cílová skupina je název hostitele instance služby API Management a že ctry deklarace identity je US. Název hostitele se poskytuje pomocí výrazu zásad a ID tenanta Microsoft Entra a ID klientské aplikace jsou poskytovány pomocí pojmenovaných hodnot. Dekódovaný JWT je k dispozici v jwt proměnné po ověření.

Další podrobnosti o volitelných deklarací identity najdete v tématu Zadání volitelných deklarací identity pro vaši aplikaci.

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

Související obsah

Další informace o práci se zásadami najdete v tématech: