Megosztás a következőn keresztül:

Microsoft Entra-jogkivonat érvényesítése

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: Minden API Management-szint

A validate-azure-ad-token szabályzat kikényszeríti egy JSON webes jogkivonat (JWT) meglétét és érvényességét, amelyet a Microsoft Entra (korábbi nevén Azure Active Directory) szolgáltatás biztosított a címtár egy meghatározott tagcsoportjához. A JWT kinyerhető egy megadott HTTP-fejlécből, lekérdezési paraméterből vagy egy szabályzatkifejezéssel vagy környezeti változóval megadott értékből.

Feljegyzés

Az általános validate-jwt szabályzattal érvényesítheti a Microsoft Entra-tól eltérő identitásszolgáltató által biztosított JWT-t.

Feljegyzés

Állítsa be a szabályzat elemeit és gyermekelemeit a szabályzatutasításban megadott sorrendben. További információ az API Management-szabályzatok beállításáról és szerkesztéséről.

Szabályzatutasítás

<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">
    <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>
    <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>
    <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>
    </required-claims>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
        <!-- if there are multiple keys, then add additional key elements -->
    </decryption-keys>
</validate-azure-ad-token>

Attribútumok

Attribútum Leírás Kötelező Alapértelmezett
bérlőazonosító A Microsoft Entra ID-bérlő bérlőazonosítója vagy URL-címe, vagy az alábbi jól ismert bérlők egyike:

- organizations vagy https://login.microsoftonline.com/organizations - jogkivonatok engedélyezése bármely szervezeti címtárban (bármely Microsoft Entra-címtárban) lévő fiókokból
- common vagy https://login.microsoftonline.com/common – jogkivonatok engedélyezése bármely szervezeti címtárban (bármely Microsoft Entra-címtárban) lévő fiókokból és személyes Microsoft-fiókokból (például Skype, XBox)

A szabályzatkifejezések engedélyezettek.		 Igen n/a
fejléc neve A jogkivonatot tartalmazó HTTP-fejléc neve. A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. Authorization
query-parameter-name A jogkivonatot tartalmazó lekérdezési paraméter neve. A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. n/a
token-value A jogkivonatot tartalmazó sztringet visszaadó kifejezés. A jogkivonat értékeként nem térhet vissza Bearer . A szabályzatkifejezések engedélyezettek. Az egyiket header-namemeg kell adni, query-parameter-name vagy token-value meg kell adni. n/a
failed-validation-httpcode HTTP-állapotkód visszaadása, ha a JWT nem felel meg az ellenőrzésnek. A szabályzatkifejezések engedélyezettek. Nem 401
failed-validation-error-message Hibaüzenet jelenik meg a HTTP válasz törzsében, ha a JWT nem felel meg az ellenőrzésnek. Ennek az üzenetnek megfelelően kell tartalmaznia a speciális karaktereket. A szabályzatkifejezések engedélyezettek. Nem Az alapértelmezett hibaüzenet az érvényesítési problémától függ, például a "JWT nincs jelen".
output-token-variable-name Húr. Annak a környezeti változónak a neve, amely a jogkivonat értékét típusobjektumként Jwt kapja meg a sikeres jogkivonat-ellenőrzéskor. A szabályzatkifejezések nem engedélyezettek. Nem N.A.

Elemek

Elem Leírás Kötelező
backend-application-ids Az elfogadható háttéralkalmazás-azonosítók listáját tartalmazza. Ez csak speciális esetekben szükséges a beállítások konfigurálásához, és általában eltávolítható. A szabályzatkifejezések nem engedélyezettek. Nem
ügyfélalkalmazás-azonosítók Az elfogadható ügyfélalkalmazás-azonosítók listáját tartalmazza. Ha több application-id elem is van jelen, akkor a rendszer minden értéket megpróbál, amíg az összes ki nem merül (ebben az esetben az ellenőrzés sikertelen), vagy amíg az egyik sikeres nem lesz. Ha nincs megadva ügyfélalkalmazás-azonosító, egy vagy több audience jogcímet kell megadni. A szabályzatkifejezések nem engedélyezettek. Nem
Közönség A jogkivonaton elérhető elfogadható célközönség-jogcímek listáját tartalmazza. Ha több audience érték van jelen, a rendszer minden értéket megpróbál, amíg az összes ki nem merül (ebben az esetben az ellenőrzés sikertelen), vagy amíg az egyik sikeres nem lesz. A szabályzatkifejezések engedélyezettek. Nem
kötelező jogcímek A jogkivonaton érvényesnek vélt jogcímértékek elemeinek listáját claim tartalmazza. Az attribútum beállításakor alla match szabályzat minden jogcímértékének szerepelnie kell a jogkivonatban az ellenőrzés sikerességéhez. Ha az match attribútum értéke be van állítva any, legalább egy jogcímnek szerepelnie kell a jogkivonatban a sikeres érvényesítéshez. A szabályzatkifejezések engedélyezettek. Nem
visszafejtési kulcsok Az aszimmetrikus kulccsal aláírt jogkivonat visszafejtéséhez használt alelemek listája key . Ha több kulcs van jelen, akkor a rendszer mindaddig próbálkozik, amíg az összes kulcs ki nem merül (ebben az esetben az érvényesítés sikertelen), vagy egy kulcs sikeres lesz.

Adja meg a nyilvános kulcsot az certificate-id API Managementbe feltöltött tanúsítvány azonosítójára beállított értékkel rendelkező attribútummal.		 Nem

jogcímattribútumok

Attribútum Leírás Kötelező Alapértelmezett
név A jogcím neve, mivel várhatóan megjelenik a jogkivonatban. A szabályzatkifejezések engedélyezettek. Igen n/a
gyufa Az match elem attribútuma claim azt határozza meg, hogy a szabályzat minden jogcímértékének szerepelnie kell-e a jogkivonatban az ellenőrzés sikerességéhez. A lehetséges értékek a következők:

- all - a szabályzat minden jogcímértékének szerepelnie kell a jogkivonatban az ellenőrzés sikerességéhez.

- any - legalább egy jogcímértéknek szerepelnie kell a jogkivonatban az ellenőrzés sikerességéhez.

A szabályzatkifejezések engedélyezettek.		 Nem mind
elválasztó Húr. Egy elválasztót (például ",") ad meg, amely egy többértékű jogcímből származó értékkészlet kinyeréséhez használható. A szabályzatkifejezések engedélyezettek. Nem N.A.

kulcsattribútumok

Attribútum Leírás Kötelező Alapértelmezett
tanúsítványazonosító Az API Managementbe feltöltött tanúsítványentitás azonosítója, amely a nyilvános kulcs megadására szolgál az aszimmetrikus kulccsal aláírt jogkivonat ellenőrzéséhez. Igen n/a

Használat

Használati megjegyzések

  • A hozzáférés-korlátozási szabályzatokat különböző hatókörökben, különböző célokra használhatja. Például a teljes API-t biztonságossá teheti a Microsoft Entra-hitelesítéssel a szabályzat API-szinten történő alkalmazásával validate-azure-ad-token , vagy alkalmazhatja az API-művelet szintjén, és részletesebb vezérlésre használhatja claims .
  • Az ügyfelek Microsoft Entra-azonosítója (előzetes verzió) nem támogatott.

Példák

Egyszerű jogkivonat érvényesítése

Az alábbi szabályzat a szabályzat minimális formája validate-azure-ad-token . Elvárja, hogy a JWT az alapértelmezett Authorization fejlécben legyen megadva a Bearer sémával. Ebben a példában a Microsoft Entra-bérlőazonosító és az ügyfélalkalmazás-azonosító nevesített értékekkel van megadva.

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

Jogkivonat érvényesítése visszafejtési kulccsal

Ez a példa bemutatja, hogyan használható a validate-azure-ad-token szabályzat egy visszafejthető jogkivonat ellenőrzésére egy visszafejtési kulccsal. A Microsoft Entra bérlőazonosítója és ügyfélalkalmazás-azonosítója nevesített értékekkel van megadva. A kulcs a nyilvános kulcsot tartalmazó feltöltött tanúsítvány azonosítójával van megadva (PFX formátumban).

<validate-azure-ad-token tenant-id="{{aad-tenant-id}}">
    <client-application-ids>
        <application-id>{{aad-client-application-id}}</application-id>
    </client-application-ids>
    <decryption-keys>
        <key certificate-id="mycertificate"/>
    </decryption-keys>
</validate-azure-ad-token>

Annak ellenőrzése, hogy a célközönség és a jogcím helyes-e

Az alábbi szabályzat ellenőrzi, hogy a célközönség az API Management-példány állomásneve-e, és hogy a ctry jogcím az US. A Microsoft-bérlőazonosító a jól ismert organizations bérlő, amely lehetővé teszi a jogkivonatokat bármely szervezeti címtárban lévő fiókokból. A gazdagépnév egy szabályzatkifejezéssel van megadva, az ügyfélalkalmazás azonosítója pedig névvel ellátott érték használatával. A dekódolt JWT az ellenőrzés után szerepel a jwt változóban.

Az opcionális jogcímekkel kapcsolatos további részletekért olvassa el az Opcionális jogcímek megadása az alkalmazásnak című témakört.

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

Kapcsolódó tartalom

A szabályzatok használatával kapcsolatos további információkért lásd: