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

Egy másik identitásszolgáltató által biztosított JWT ellenőrzéséhez az API Management az általános validate-jwt szabályzatot is biztosítja.

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

Attribútumok

Attribútum Leírás Kötelező Alapértelmezett
bérlőazonosító A Microsoft Entra szolgáltatás bérlőazonosítója vagy URL-címe. 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 Karakterlánc. 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ő
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
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ö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

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
Mérkőzés 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ó Karakterlánc. 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.

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>

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 gazdagépnév egy szabályzatkifejezéssel van megadva, a Microsoft Entra bérlőazonosítóját és ügyfélalkalmazás-azonosítóját pedig névvel ellátott értékekkel adták meg. 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="{{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>

Kapcsolódó tartalom

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