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

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>
    <decryption-keys>
        <key>Base64 encoded signing key | certificate-id="mycertificate"</key>
        <!-- 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 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 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ő
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
visszafejtési kulcsok A base64 kódolású kulcsok listája alelemekben key , a jogkivonatok visszafejtéséhez. Ha több biztonsági kulcs is található, 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.

Az aszimmetrikus kulccsal titkosított jogkivonat visszafejtéséhez opcionálisan meg kell adnia a nyilvános kulcsot egy certificate-id , az 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. 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: