Azonosító jogkivonat jogcímeinek referenciája

Cikk
10/24/2023

Az azonosító jogkivonatok JSON webes jogkivonatok (JWT). Az 1.0-s és a 2.0-s verziójú azonosító jogkivonatok különbségeket tartalmaznak az általuk hordozott információk között. A verzió azon a végponton alapul, ahonnan a kérelmet kérték. Bár a meglévő alkalmazások valószínűleg az Azure AD 1.0-s végpontot használják, az új alkalmazásoknak a 2.0-s verziójú végpontot kell használniuk.

1\.0-s verzió: https://login.microsoftonline.com/common/oauth2/authorize
2.0-s verzió: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Az alábbi szakaszokban felsorolt összes JWT-jogcím az 1.0-s és a 2.0-s verziójú jogkivonatokban is megjelenik, hacsak másként nem rendelkezik. Az azonosító jogkivonatok fejlécből, hasznos adatokból és aláírásból állnak. A fejléc és az aláírás a jogkivonat hitelességének ellenőrzésére szolgál, míg a hasznos adatok tartalmazzák az ügyfél által kért felhasználó adatait.

Fejléc jogcímek

Az alábbi táblázat az azonosító jogkivonatokban található fejlécjogcímeket mutatja be.

Jogcím	Format	Leírás
`typ`	Sztring – mindig "JWT"	Azt jelzi, hogy a jogkivonat egy JWT-jogkivonat.
`alg`	Sztring	A jogkivonat aláírásához használt algoritmust jelzi. Például: "RS256"
`kid`	Sztring	Megadja a nyilvános kulcs ujjlenyomatát, amely a jogkivonat aláírásának ellenőrzésére használható. 1.0-s és 2.0-s verziójú azonosító jogkivonatokban is kibocsátva.
`x5t`	Sztring	A függvények ugyanazt a függvényt használják (használatban és értékben), mint a `kid`. `x5t` egy örökölt jogcím, amelyet csak kompatibilitási célokból az 1.0-s verziójú azonosító jogkivonatokban bocsátanak ki.

Hasznos adatok jogcíme

Az alábbi táblázat alapértelmezés szerint a legtöbb azonosító jogkivonatban szereplő jogcímeket mutatja be (kivéve a feljegyzett jogcímeket). Az alkalmazás azonban opcionális jogcímekkel is kérhet további jogcímeket az azonosító jogkivonatában. A választható jogcímek a groups jogcímtől a felhasználó nevével kapcsolatos információkig terjedhetnek.

Jogcím	Format	Leírás
`aud`	Sztring, alkalmazásazonosító GUID azonosítója	A jogkivonat kívánt címzettjének azonosítása. Ebben `id_tokens`a célközönség az alkalmazás alkalmazásazonosítója, amely az Azure Portalon van hozzárendelve az alkalmazáshoz. Ezt az értéket ellenőrizni kell. A jogkivonatot el kell utasítani, ha nem felel meg az alkalmazás alkalmazásazonosítójának.
`iss`	Sztring, egy kiállító URI-ja	Azonosítja azt a kiállítót vagy "engedélyezési kiszolgálót", amely a jogkivonatot hozza létre és adja vissza. Azt a bérlőt is azonosítja, amelyhez a felhasználót hitelesítették. Ha a jogkivonatot a 2.0-s verziójú végpont adta ki, az URI a következő lesz `/v2.0`: . Az a GUID, amely azt jelzi, hogy a felhasználó egy Microsoft-fiók felhasználói felhasználója.`9188040d-6c67-4c5b-b112-36a304b66dad` Az alkalmazásnak a jogcím GUID-részét kell használnia az alkalmazásba bejelentkezni képes bérlők halmazának korlátozására, ha vannak ilyenek.
`iat`	int, unix-időbélyeg	Azt jelzi, hogy mikor történt a jogkivonat hitelesítése.
`idp`	Sztring, általában STS URI	A jogkivonat alanyát hitelesítő identitásszolgáltatót adja meg. Ez az érték megegyezik a kiállítói jogcím értékével, kivéve, ha a felhasználói fiók nem ugyanabban a bérlőben van, mint a kiállító – például vendégek. Ha a jogcím nem jelenik meg, az azt jelenti, hogy az érték `iss` használható helyette. A szervezeti környezetben használt személyes fiókok (például egy bérlőhöz meghívott személyes fiók) esetén a `idp` jogcím lehet "live.com" vagy a Microsoft-fiók bérlőt `9188040d-6c67-4c5b-b112-36a304b66dad`tartalmazó STS URI.
`nbf`	int, unix-időbélyeg	Azt az időpontot határozza meg, amely előtt a JWT nem fogadható el feldolgozásra.
`exp`	int, unix-időbélyeg	Azt a lejárati időt határozza meg, amely után a JWT nem fogadható el feldolgozásra. Bizonyos körülmények között egy erőforrás ezt megelőzően elutasíthatja a jogkivonatot. Ha például módosítani kell a hitelesítést, vagy jogkivonat-visszavonást észleltek.
`c_hash`	Sztring	A kódkivonat csak akkor szerepel az azonosító jogkivonatokban, ha az azonosító jogkivonatot OAuth 2.0 engedélyezési kóddal adják ki. Egy engedélyezési kód hitelességének ellenőrzésére használható. Az ellenőrzés módjának megismeréséhez tekintse meg az OpenID Csatlakozás specifikációját. Ezt a jogcímet a /token végpont azonosító jogkivonatai nem adják vissza.
`at_hash`	Sztring	A hozzáférési jogkivonat csak akkor szerepel az azonosító jogkivonatokban, ha az azonosító jogkivonatot OAuth 2.0 hozzáférési jogkivonattal bocsátják ki a `/authorize` végpontról. A hozzáférési jogkivonat hitelességének ellenőrzésére használható. Az ellenőrzés módjának megismeréséhez tekintse meg az OpenID Csatlakozás specifikációját. Ezt a jogcímet a végpont azonosító `/token` jogkivonatai nem adják vissza.
`aio`	Átlátszatlan sztring	Egy belső jogcím, amely a jogkivonatok újrafelhasználásához használt adatok rögzítésére szolgál. Figyelmen kívül kell hagyni.
`preferred_username`	Sztring	A felhasználót jelképező elsődleges felhasználónév. Ez lehet egy e-mail-cím, telefonszám vagy egy általános felhasználónév, amely nem rendelkezik megadott formátummal. Értéke nem módosítható, és idővel változhat. Mivel ez nem módosítható, ez az érték nem használható engedélyezési döntések meghozatalára. Felhasználónév-tippekhez és emberi olvasásra alkalmas felhasználói felületen felhasználónévként használható. A `profile` kérelem fogadásához a hatókörre van szükség. Csak v2.0-s jogkivonatokban jelenik meg.
`email`	Sztring	Alapértelmezés szerint az e-mail-címmel rendelkező vendégfiókok esetén jelenik meg. Az alkalmazás kérheti a felügyelt felhasználók e-mail-jogcímét (az erőforrással megegyező bérlőről) az `email`opcionális jogcím használatával. Ez az érték nem garantáltan helyes, és idővel módosítható. Soha ne használja az engedélyezéshez vagy a felhasználó adatainak mentéséhez. Ha meg kell adnia egy címezhető e-mail-címet az alkalmazásban, kérje le ezeket az adatokat közvetlenül a felhasználótól, ha ezt a jogcímet javaslatként használja, vagy előre kitölti az UX-ben. A 2.0-s verziójú végponton az alkalmazás az OpenID Csatlakozás hatókört is kérheti `email` – a jogcím lekéréséhez nem kell mind az opcionális jogcímet, mind a hatókört kérnie.
`name`	Sztring	A `name` jogcím egy ember által olvasható értéket biztosít, amely azonosítja a jogkivonat tárgyát. Az érték nem garantáltan egyedi, módosítható, és csak megjelenítési célokra használható. A `profile` kérelem fogadásához a hatókörre van szükség.
`nonce`	Sztring	A nonce megegyezik az identitásszolgáltatóhoz irányuló eredeti engedélyezési kérelemben szereplő paraméterrel. Ha nem egyezik, az alkalmazásnak el kell utasítania a jogkivonatot.
`oid`	Sztring, GUID	Egy objektum, ebben az esetben egy felhasználói fiók nem módosítható azonosítója. Ez az azonosító egyedileg azonosítja a felhasználót az alkalmazások között – az ugyanabban a felhasználóban bejelentkező két különböző alkalmazás ugyanazt az értéket kapja a `oid` jogcímben. A Microsoft Graph ezt az azonosítót adja vissza egy `id` felhasználói fiók tulajdonságaként. Mivel ez `oid` lehetővé teszi, hogy több alkalmazás is korrelálja a felhasználókat, a `profile` hatókörre szükség van a jogcím fogadásához. Ha egyetlen felhasználó több bérlőben is létezik, a felhasználó minden bérlőben más-más objektumazonosítót tartalmaz – más fióknak számít, annak ellenére, hogy a felhasználó ugyanazokkal a hitelesítő adatokkal jelentkezik be mindegyik fiókba. A `oid` jogcím EGY GUID, és nem használható újra.
`roles`	Sztringek tömbje	A bejelentkező felhasználóhoz rendelt szerepkörök készlete.
`rh`	Átlátszatlan sztring	A jogkivonatok újraértékelésére használt belső jogcím. Figyelmen kívül kell hagyni.
`sub`	Sztring	A jogkivonatban szereplő információk tárgya. Például egy alkalmazás felhasználója. Ez az érték nem módosítható, és nem rendelhető újra és nem használható újra. A tárgy egy párosított azonosító, és egyedi az alkalmazásazonosítóhoz. Ha egyetlen felhasználó két különböző alkalmazásba jelentkezik be két különböző ügyfélazonosító használatával, ezek az alkalmazások két különböző értéket kapnak a tárgy jogcíméhez. Az architektúrától és az adatvédelmi követelményektől függően előfordulhat, hogy két értéket szeretne vagy sem.
`tid`	Sztring, GUID	Azt a bérlőt jelöli, amelyikbe a felhasználó bejelentkezik. Munkahelyi és iskolai fiókok esetén a GUID annak a szervezetnek a nem módosítható bérlőazonosítója, amelybe a felhasználó bejelentkezik. A személyes Microsoft-fiók bérlőjéhez (például Xbox, Teams for Life vagy Outlook) való bejelentkezések esetén az érték .`9188040d-6c67-4c5b-b112-36a304b66dad`
`unique_name`	Sztring	Csak 1.0-s verziós jogkivonatokban van jelen. A jogkivonat alanyát azonosító, ember által olvasható értéket ad meg. Ez az érték nem garantáltan egyedi a bérlőn belül, és csak megjelenítési célokra használható.
`uti`	Sztring	Jogkivonat-azonosító jogcím, amely egyenértékű `jti` a JWT-specifikációval. Egyedi, jogkivonatonkénti azonosító, amely megkülönbözteti a kis- és nagybetűk számát.
`ver`	Sztring, 1.0 vagy 2.0	Az azonosító jogkivonat verzióját jelzi.
`hasgroups`	Logikai	Ha jelen van, mindig igaz, a felhasználó jelölése legalább egy csoportban történik. A JWT-kre vonatkozó csoportok igénylése helyett implicit engedélyezési folyamatokban használatos, ha a teljes csoportok jogcíme az URL-hosszkorláton (jelenleg hat vagy több csoport) túlterjed az URI-töredékre. Azt jelzi, hogy az ügyfélnek a Microsoft Graph API használatával kell meghatároznia a felhasználó csoportjait (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	JSON-objektum	Az olyan jogkivonat-kérelmek esetében, amelyek hossza nem korlátozott (lásd `hasgroups`), de még mindig túl nagy a jogkivonathoz, megjelenik a felhasználó teljes csoportlistájára mutató hivatkozás. Elosztott jogcímként a JWT-k esetében az SAML mint új jogcím a `groups` jogcím helyett. Példa JWT-értékre: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` További információ: Csoportok túlhasználati jogcíme.

Jogcímek használata a felhasználó megbízható azonosításához

A felhasználók azonosításakor fontos, hogy olyan információkat használjon, amelyek folyamatosan állandóak és egyediek maradnak. Az örökölt alkalmazások néha olyan mezőket használnak, mint az e-mail-cím, a telefonszám vagy az UPN. Ezek a mezők idővel változhatnak, és idővel újra felhasználhatók. Ha például egy alkalmazott megváltoztatja a nevét, vagy egy alkalmazott kap egy e-mail-címet, amely megegyezik egy korábbi, már nem létező alkalmazott nevével. Az alkalmazásnak nem szabad emberi olvasható adatokat használnia egy felhasználó azonosításához – az emberi olvashatóság általában azt jelenti, hogy valaki elolvashatja és módosítani szeretné azt. Ehelyett használja az OIDC szabvány által biztosított jogcímeket, vagy a Microsoft által biztosított kiterjesztési jogcímeket – a jogcímeket és oid a sub jogcímeket.

Az adatok felhasználónkénti helyes tárolásához használja vagy oid önállóan sub (amelyek grafikus felhasználói felületként egyediek), tid és szükség esetén útválasztásra vagy horizontális skálázásra használják. Ha adatokat kell megosztania a szolgáltatások között, és tid a legjobb, oid ha minden alkalmazás ugyanazt oid és tid jogcímeket kap egy bérlőben eljáró felhasználóhoz. Az sub állítás egy egyedi párszintű érték. Az érték a jogkivonat címzettjének, bérlőjének és felhasználójának kombinációján alapul. A felhasználó azonosító jogkivonatait kérő két alkalmazás eltérő sub jogcímeket kap, de ugyanezeket oid a jogcímeket az adott felhasználóhoz.

Megjegyzés:

Ne használja a idp jogcímet egy felhasználó adatainak tárolására a felhasználók bérlők közötti korrelációjának megkísérlése során. Nem működik, mivel a felhasználók jogcímei és sub a oid bérlők között a kialakításuk szerint változnak, így az alkalmazások nem tudják nyomon követni a bérlők felhasználóit.

A vendégforgatókönyvekben, ahol egy felhasználó egy bérlőben található, és egy másikban hitelesít, úgy kell kezelnie a felhasználót, mintha teljesen új felhasználó lennének a szolgáltatásban. Az egyik bérlő dokumentumai és jogosultságai nem alkalmazhatók egy másik bérlőre. Ez a korlátozás fontos a bérlők véletlen adatszivárgásának és az adatéletciklusok kényszerítésének megakadályozása érdekében. A vendég bérlőből való kizárásának azt is el kell távolítania, hogy hozzáférjenek az adott bérlőben létrehozott adatokhoz.

Csoportok túlhasználati jogcíme

Annak érdekében, hogy a jogkivonat mérete ne haladja meg a HTTP-fejléc méretkorlátjait, a jogcímben groups szereplő objektumazonosítók száma korlátozott. Ha egy felhasználó több csoportnak is tagja, mint a túllépési korlát (SAML-jogkivonatok esetén 150, JWT-jogkivonatok esetén 200), a csoportok jogcíme nem szerepel a jogkivonatban. Ehelyett tartalmaz egy túlhasználati jogcímet a jogkivonatban, amely azt jelzi az alkalmazásnak, hogy lekérdezi a Microsoft Graph API-t a felhasználó csoporttagságának lekéréséhez.

{
  ...
  "_claim_names": {
   "groups": "src1"
    },
    {
  "_claim_sources": {
    "src1": {
        "endpoint":"[Url to get this user's group membership from]"
        }
       }
     }
  ...
}

További lépések

További információ a Microsoft Entra ID-ban használt azonosító jogkivonatokról.