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

Választható jogcímek referenciája

  • Cikk

A választható jogcímek a következőhöz használhatók:

  • Válassza ki az alkalmazás jogkivonataiban felvenni kívánt jogcímeket.
  • Módosíthatja bizonyos jogcímek viselkedését, amelyeket a Microsoft identitásplatform tokenekben ad vissza.
  • Egyéni jogcímek hozzáadása és elérése az alkalmazáshoz.

Bár az opcionális jogcímek támogatottak mind az 1.0-s, mind a 2.0-s formátumú jogkivonatokban, mind az SAML-jogkivonatokban, az értékük nagy részét az 1.0-s verzióról a 2.0-s verzióra való áttéréskor biztosítják. A Microsoft identitásplatformon kisebb tokenméretekkel biztosítják az ügyfelek optimális teljesítményét. Ennek eredményeképpen a hozzáférési és azonosító jogkivonatokban korábban szereplő jogcímek már nem szerepelnek a 2.0-s verziójú jogkivonatokban, és kifejezetten alkalmazásonként kell kérni.

Fiók típusa 1.0-s jogkivonatok 2.0-s verziós jogkivonatok
Személyes Microsoft-fiók N/A Támogatott
Microsoft Entra-fiók Támogatott Támogatott

v1.0 és v2.0 opcionális jogcímkészlet

A használni kívánt alkalmazásokhoz alapértelmezés szerint elérhető választható jogcímek listája az alábbi táblázatban található. Az egyéni adatok bővítményattribútumokban és címtárbővítményekben használhatók opcionális jogcímek hozzáadásához az alkalmazáshoz. Amikor jogcímeket ad hozzá a hozzáférési jogkivonathoz, a jogcímek az alkalmazás (webes API) kért hozzáférési jogkivonatokra vonatkoznak, nem pedig az alkalmazás által kért jogcímekre. Függetlenül attól, hogy az ügyfél hogyan fér hozzá az API-hoz, a megfelelő adatok megtalálhatók az API-val való hitelesítéshez használt hozzáférési jogkivonatban.

Jegyzet

Ezeknek a jogcímeknek a többsége az 1.0-s és a 2.0-s verziójú jogkivonatok JWT-jeibe is belefoglalható, SAML-jogkivonatok azonban nem, kivéve, ha a Jogkivonat típusa oszlopban szerepel. A fogyasztói fiókok támogatják ezeknek a jogcímeknek a felhasználótípus oszlopban megjelölt részhalmazát. A felsorolt jogcímek nagy része nem vonatkozik a fogyasztói felhasználókra (nincs bérlőjük, így tenant_ctry nincs értékük).

Az alábbi táblázat az 1.0-s és a 2.0-s verzió opcionális jogcímkészletét sorolja fel.

Név Leírás Jogkivonat típusa Felhasználó típusa Notes
acct Felhasználók fiókállapota a bérlőben JWT, SAML Ha a felhasználó a bérlő tagja, az érték 0. Ha vendég, akkor az érték 1.
acrs Hitelesítési környezet azonosítói JWT Microsoft Entra-azonosító Azoknak a műveleteknek a hitelesítési környezeti azonosítóit jelzi, amelyeket a tulajdonos végrehajthat. A hitelesítési környezeti azonosítók használatával igény léptethető fel az alkalmazáson és a szolgáltatásokon belülről a felfelé irányuló hitelesítésre. Gyakran használják a xms_cc jogcímgel együtt.
auth_time A felhasználó utolsó hitelesítésének időpontja. JWT
ctry Felhasználó országa/régiója JWT Ez a jogcím akkor jelenik meg, ha jelen van, és a mező értéke egy szabványos kétbetűs ország-/régiókód, például FR, JP, SZ stb.
email A felhasználó jelentett e-mail-címe JWT, SAML MSA, Microsoft Entra ID Ez az érték alapértelmezés szerint akkor jelenik meg, ha a felhasználó vendég a bérlőben. Felügyelt felhasználók (a bérlőn belüli felhasználók) esetében ezt az opcionális jogcímet kell kérni, vagy csak a 2.0-s verzió esetén az OpenID-hatókörrel. Ez az érték nem garantáltan helyes, és idővel módosítható – soha ne használja engedélyezésre vagy adatok mentésére egy felhasználó számára. További információ: Annak ellenőrzése, hogy a felhasználó jogosult-e hozzáférni ezekhez az adatokhoz. Ha az e-mail-jogcímet használja engedélyezésre, javasoljuk, hogy végezzen áttelepítést, hogy biztonságosabb jogcímre. Ha meg kell adnia egy címezhető e-mail-címet az alkalmazásban, közvetlenül kérje le ezeket az adatokat a felhasználótól, és használja ezt a jogcímet javaslatként, vagy töltse ki előre az UX-ben.
fwd IP-cím JWT Hozzáadja a kérelmező ügyfél eredeti címét (ha egy virtuális hálózaton belül van).
groups Csoportjogcímek nem kötelező formázása JWT, SAML A groups jogcím a GroupMembershipClaims beállítással együtt használatos az alkalmazásjegyzékben, amelyet szintén be kell állítani.
idtyp Jogkivonat típusa JWT hozzáférési jogkivonatok Speciális: csak alkalmazásalapú hozzáférési jogkivonatokban Az érték app, ha a jogkivonat csak alkalmazásalapú jogkivonat. Ez a jogcím a legpontosabb módszer az API-k számára annak megállapítására, hogy egy jogkivonat alkalmazásjogkivonat vagy alkalmazás-+felhasználói jogkivonat-e.
login_hint Bejelentkezési tipp JWT MSA, Microsoft Entra ID Egy átlátszatlan, megbízható bejelentkezési tipp azt állítja, hogy ez alap 64 kódolású. Ne módosítsa ezt az értéket. Ez a jogcím a legjobb érték az összes folyamat login_hint OAuth paraméteréhez az egyszeri bejelentkezés lekéréséhez. Továbbítható az alkalmazások között, hogy csendben is segítsen nekik az egyszeri bejelentkezésben – az A alkalmazás bejelentkezhet egy felhasználóba, elolvashatja a login_hint jogcímet, majd elküldheti a jogcímet és az aktuális bérlői környezetet a B alkalmazásnak a lekérdezési sztringben vagy -töredékben, amikor a felhasználó kiválaszt egy hivatkozást, amely a B alkalmazásba viszi őket. A versenyfeltételek és a megbízhatósági problémák elkerülése érdekében a login_hint jogcím nem tartalmazza a felhasználó aktuális bérlőjét, és használat esetén alapértelmezés szerint a felhasználó otthoni bérlőjét. Olyan vendégforgatókönyvben, amelyben a felhasználó egy másik bérlőtől származik, a bejelentkezési kérelemben meg kell adnia egy bérlőazonosítót. és adja át ugyanezt az alkalmazásnak, amellyel partneri kapcsolatban van. Ez a jogcím az SDK meglévő login_hint funkciójával való használatra szolgál, azonban az elérhető.
tenant_ctry Erőforrás-bérlő országa/régiója JWT Ugyanaz, mint ctry, kivéve, ha egy rendszergazda bérlői szinten van beállítva. Szabványos kétbetűs értéknek is kell lennie.
tenant_region_scope Az erőforrás-bérlő régiója JWT
upn UserPrincipalName JWT, SAML A username_hint paraméterrel használható felhasználó azonosítója. Nem tartós azonosító a felhasználó számára, és nem használható engedélyezéshez vagy egyedi azonosító felhasználói adatokhoz (például adatbáziskulcsként). Ehelyett használja a felhasználói objektum azonosítóját (oid) adatbáziskulcsként. További információ: Biztonságos alkalmazások és API-k a jogcímekérvényesítésével. A másodlagos bejelentkezési azonosítóval bejelentkező felhasználóknak nem szabad megjeleníteniük a felhasználónevet (UPN). Ehelyett használja a következő azonosítójogkivonat-jogcímeket a bejelentkezési állapot felhasználónak való megjelenítéséhez: preferred_username vagy unique_name v1-jogkivonatokhoz, és preferred_username a v2-jogkivonatokhoz. Bár ez a jogcím automatikusan szerepel benne, opcionális jogcímként megadhatja, hogy más tulajdonságokat is csatoljon a vendégfelhasználói eset viselkedésének módosításához. A login_hint használathoz a login_hint jogcímet kell használnia – az olyan emberi olvasásra alkalmas azonosítók, mint az UPN, megbízhatatlanok.
verified_primary_email Forrás: a felhasználó PrimaryAuthoritativeEmail üzenete JWT
verified_secondary_email Forrás: a felhasználó SecondaryAuthoritativeEmail üzenete JWT
vnet A VNET-jelölő adatai. JWT
xms_cc Ügyfélképességek JWT Microsoft Entra-azonosító Azt jelzi, hogy a jogkivonatot beszerző ügyfélalkalmazás képes-e kezelni a jogcímekkel kapcsolatos problémákat. Gyakran használják a jogcím acrs. Ezt a jogcímet gyakran használják a feltételes hozzáférés és a folyamatos hozzáférés kiértékelése forgatókönyvekben. A jogkivonat által kibocsátott erőforrás-kiszolgáló vagy szolgáltatásalkalmazás szabályozza a jogcím jelenlétét egy jogkivonatban. A hozzáférési jogkivonatban lévő cp1 értéke mérvadó módszer annak azonosítására, hogy egy ügyfélalkalmazás képes-e kezelni a jogcímekkel kapcsolatos kihívásokat. További információ: Jogcímekkel kapcsolatos kihívások, jogcímkérelmek és ügyfélképességek.
xms_edov Logikai érték, amely azt jelzi, hogy a felhasználó e-mail-tartományának tulajdonosa ellenőrizve lett-e. JWT Az e-mailek akkor minősülnek ellenőrzött tartománynak, ha annak a bérlőnek a tagja, ahol a felhasználói fiók található, és a bérlő rendszergazdája ellenőrizte a tartományt. Emellett az e-mailnek Egy Microsoft-fiókból (MSA), egy Google-fiókból kell származnia, vagy az egyszeri pin-kód (OTP) folyamattal történő hitelesítéshez kell használnia. A Facebook- és SAML-/WS-Fed-fiókok nem igazolt tartományokkal. Ahhoz, hogy ezt a jogcímet vissza lehessen adni a jogkivonatban, szükség van a email jogcím jelenlétére.
xms_pdl Előnyben részesített adathely JWT A Multi-Geo-bérlők esetében az előnyben részesített adathely a felhasználó földrajzi régióját megjelenítő hárombetűs kód. További információ: Microsoft Entra Connect dokumentációja az előnyben részesített adathely.
xms_pl Felhasználó által előnyben részesített nyelv JWT Ha be van állítva, a felhasználó által előnyben részesített nyelv. A forrás az otthoni bérlőből származik, vendéghozzáférés esetén. Formázott LL-CC ("en-us").
xms_tpl Bérlő által előnyben részesített nyelv JWT Ha be van állítva, az erőforrás-bérlő előnyben részesített nyelve. Formázott LL ("en").
ztdid Nulla érintéses üzembehelyezési azonosító JWT A Windows AutoPiloteszközidentitás.

Figyelmeztetés

Soha ne használjon email vagy upn jogcímértékeket az adatok tárolására, illetve annak meghatározására, hogy a hozzáférési jogkivonatban szereplő felhasználónak hozzáféréssel kell-e rendelkeznie az adatokhoz. Az ilyen változó jogcímértékek idővel változhatnak, így nem biztonságosak és megbízhatatlanok az engedélyezéshez.

v2.0-specifikus választható jogcímkészlet

Ezek a jogcímek mindig az 1.0-s verziós jogkivonatok részét képezik, de a 2.0-s verziós jogkivonatokban nem szerepelnek, hacsak nem kérik. Ezek a jogcímek csak JWT-kre (azonosító jogkivonatokra és hozzáférési jogkivonatokra) vonatkoznak.

JWT-jogcím Név Leírás Notes
ipaddr IP-cím Az az IP-cím, amelyről az ügyfél bejelentkezett.
onprem_sid Helyszíni biztonsági azonosító
pwd_exp Jelszó lejárati ideje A jelszó lejáratának iat jogcímben eltelt idő utáni másodpercek száma. Ez a jogcím csak akkor jelenik meg, ha a jelszó hamarosan lejár (a jelszóházirendben meghatározott "értesítési napok" szerint).
pwd_url Jelszó URL-címének módosítása Egy URL- cím, amelyet a felhasználó meg tud látogatni a jelszó módosításához. Ez a jogcím csak akkor jelenik meg, ha a jelszó hamarosan lejár (a jelszóházirendben meghatározott "értesítési napok" szerint).
in_corp Vállalati hálózaton belül Jelzi, ha az ügyfél bejelentkezik a vállalati hálózatról. Ha nem, akkor a jogcím nem szerepel benne. A megbízható IP-címek MFA-beállítások alapján.
family_name Vezetéknév Megadja a felhasználó vezetéknevét, vezetéknevét vagy családi nevét a felhasználói objektumban meghatározott módon. Például "family_name":"Miller". Az MSA és a Microsoft Entra ID támogatja. A profile hatókört igényli.
given_name Keresztnév A felhasználó első vagy "adott" nevét adja meg a felhasználói objektumon beállított módon. Például "given_name": "Frank". Az MSA és a Microsoft Entra ID támogatja. A profile hatókört igényli.
upn Egyszerű felhasználónév A username_hint paraméterrel használható felhasználó azonosítója. Nem tartós azonosító a felhasználó számára, és nem használható engedélyezéshez vagy egyedi azonosító felhasználói adatokhoz (például adatbáziskulcsként). További információ: Biztonságos alkalmazások és API-k a jogcímekérvényesítésével. Ehelyett használja a felhasználói objektum azonosítóját (oid) adatbáziskulcsként. A másodlagos bejelentkezési azonosítóval bejelentkező felhasználóknak nem szabad megjeleníteniük a felhasználónevet (UPN). Ehelyett használja a következő preferred_username jogcímet a bejelentkezési állapot felhasználónak való megjelenítéséhez. A profile hatókört igényli.

1.0-specifikus választható jogcímkészlet

A v2-jogkivonat-formátum néhány fejlesztése elérhető a v1 jogkivonat formátumot használó alkalmazások számára, mivel ezek segítenek a biztonság és a megbízhatóság javításában. Ezek a fejlesztések csak a JWT-kre vonatkoznak, az SAML-jogkivonatokra nem.

JWT-jogcím Név Leírás Notes
aud Hallgatóság Mindig JWT-kben van jelen, de az 1. verziójú hozzáférési jogkivonatokban különböző módokon bocsátható ki – bármilyen appID URI, záró perjellel vagy anélkül, valamint az erőforrás ügyfélazonosítójával. Ez a véletlenszerűség a jogkivonat érvényesítésekor nehezen kódolódhat. Az additionalProperties használatával győződjön meg arról, hogy mindig az erőforrás ügyfélazonosítójára van állítva az 1. verziójú hozzáférési jogkivonatokban. v1 JWT hozzáférési jogkivonatok csak
preferred_username Előnyben részesített felhasználónév Az előnyben részesített felhasználónév-jogcímet adja meg az 1. virtuális jogkivonaton belül. Ez az állítás megkönnyíti az alkalmazások számára a felhasználónév-tippek megadását és az emberi olvasható megjelenítendő nevek megjelenítését, a token típusától függetlenül. Javasoljuk, hogy ezt az opcionális jogcímet használja ahelyett, hogy használ, upn vagy unique_name. v1 azonosító jogkivonatok és hozzáférési jogkivonatok

választható jogcímek additionalProperties

Néhány választható jogcím konfigurálható úgy, hogy módosítsa a jogcím visszaadásának módját. Ezeket a additionalProperties elsősorban a különböző adatelvárásokkal rendelkező helyszíni alkalmazások migrálásához használják. A include_externally_authenticated_upn_without_hash például olyan ügyfeleknek nyújt segítséget, amelyek nem tudják kezelni a kivonatjeleket (#) az UPN-ben.

Tulajdonság neve additionalProperty neve Leírás
upn SAML- és JWT-válaszokhoz, valamint 1.0-s és v2.0-s jogkivonatokhoz is használható.
include_externally_authenticated_upn Tartalmazza az erőforrás-bérlőben tárolt vendég UPN-et. Például foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash Ugyanaz, mint korábban, kivéve, hogy a kivonatjelek (#) helyett aláhúzásjelek (_), például foo_hometenant.com_EXT_@resourcetenant.com.
aud Az 1. verziós hozzáférési jogkivonatokban ez a jogcím a aud jogcím formátumának módosítására szolgál. Ez a jogcím nincs hatással a v2-jogkivonatokra vagy a verzióazonosító-jogkivonatokra, ahol a aud jogcím mindig az ügyfélazonosító. Ezzel a konfigurációval biztosíthatja, hogy az API könnyebben elvégezhesse a célközönség érvényesítését. A hozzáférési jogkivonatot érintő összes opcionális jogcímhez hasonlóan a kérelemben szereplő erőforrásnak is be kell állítania ezt az opcionális jogcímet, mivel az erőforrásoké a hozzáférési jogkivonat.
use_guid Az erőforrás (API) ügyfélazonosítóját GUID formátumban bocsátja ki, mivel a aud jogcím mindig a futtatókörnyezettől való függés helyett mindig érvényes. Ha például egy erőforrás beállítja ezt a jelzőt, és az ügyfélazonosítója 00001111-aaaa-2222-bbbb-3333cccc4444, minden olyan alkalmazás, amely hozzáférési jogkivonatot kér az adott erőforráshoz, hozzáférési jogkivonatot kap aud: 00001111-aaaa-2222-bbbb-3333cccc4444. A jogcímkészlet nélkül az API-k jogkivonatokat szerezhetnek be audapi://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField vagy bármely más, alkalmazásazonosító URI-ként beállított értékkel, valamint az erőforrás ügyfélazonosítójával.
idtyp Ez a jogcím a jogkivonat típusának (alkalmazás, felhasználó, eszköz) lekérésére szolgál. Alapértelmezés szerint csak csak alkalmazásalapú jogkivonatok esetén lesz kibocsátva. A hozzáférési jogkivonatot érintő összes opcionális jogcímhez hasonlóan a kérelemben szereplő erőforrásnak is be kell állítania ezt az opcionális jogcímet, mivel az erőforrásoké a hozzáférési jogkivonat.
include_user_token Kibocsátja a felhasználói jogkivonat idtyp jogcímét. Az idtyp jogcímkészlet opcionális további tulajdonsága nélkül az API csak az alkalmazásjogkivonatokra vonatkozó jogcímet kapja meg.

additionalProperties példa

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

Ez a optionalClaims objektum miatt az ügyfélnek visszaadott azonosító jogkivonat egy upn jogcímet tartalmaz a többi otthoni bérlői és erőforrás-bérlői információval. A upn jogcím csak akkor módosul a jogkivonatban, ha a felhasználó vendég a bérlőben (amely a hitelesítéshez egy másik idP-t használ).

Lásd még:

Következő lépések

  • További információ a választható jogcímekkonfigurálásáról.