Sdílet prostřednictvím

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:

Pokud chcete ověřit JWT, který poskytl jiný zprostředkovatel identity než Microsoft Entra, 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, "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>

Atributy

Atribut Popis Požaduje se Výchozí
tenant-id ID tenanta nebo adresa URL tenanta Microsoft Entra ID nebo jednoho z následujících dobře známých tenantů:

- organizations nebo https://login.microsoftonline.com/organizations – povolení tokenů z účtů v libovolném organizačním adresáři (libovolném adresáři Microsoft Entra)
- common nebo https://login.microsoftonline.com/common – povolení tokenů z účtů v libovolném organizačním adresáři (libovolném adresáři Microsoft Entra) a z osobních účtů Microsoft (například Skype, XBox)

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-value query-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-value query-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-value query-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
publika 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é. No
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
dešifrovací klíče Seznam dílčích key částí, které slouží k dešifrování tokenu podepsaného asymetrickým klíčem. Pokud existuje více klíčů, pak se každý klíč pokusí, dokud se nevyčerpají všechny klíče (v takovém případě ověření selže) nebo se klíč úspěšně nezdaří.

Zadejte veřejný klíč pomocí atributu certificate-id s hodnotou nastavenou na identifikátor certifikátu nahraného do služby API Management.		 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 –

klíčové atributy

Atribut Popis Požaduje se Výchozí
id certifikátu Identifikátor entity certifikátu nahrané do služby API Management, který slouží k zadání veřejného klíče k ověření tokenu podepsaného asymetrickým klíčem. Yes –

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. ID tenanta Microsoftu je dobře známý organizations tenant, který umožňuje tokeny z účtů v libovolném adresáři organizace. Název hostitele se poskytuje pomocí výrazu zásad a ID klientské aplikace se poskytuje pomocí pojmenované hodnoty. 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="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>

Související obsah

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