Választható jogcímek referenciája

  • Cikk

A nem kötelező jogcímekkel:

  • Válassza ki az alkalmazás jogkivonataiban felvenni kívánt jogcímeket.
  • Módosíthatja a Microsoft Identitásplatform által a tokenekben visszaadott egyes jogcímek viselkedését.
  • Hozzáadhat egyéni jogcímeket az alkalmazáshoz, és elérheti őket.

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ásplatform 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áshoz kért hozzáférési jogkivonatokra (webes API-ra) 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.

Feljegyzés

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, ezért 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 Jegyzetek
acct Felhasználók fiókállapota a bérlőben JWT, SAML Ha a felhasználó a bérlő tagja, az érték a következő 0: . Ha vendég, akkor az érték .1
acrs Hitelesítési környezet azonosítói JWT Microsoft Entra ID 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 az xms_cc állítással 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 az adatok elérésére. Ha az e-mail-jogcímet használja engedélyezésre, javasoljuk, hogy végezzen migrálást egy biztonságosabb jogcímre való áttéréshez. 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 az, app amikor 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 login_hint összes folyamat OAuth paraméteréhez az egyszeri bejelentkezés lekéréséhez. Továbbítható az alkalmazások között, hogy segítsen nekik az egyszeri bejelentkezésben is – 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áshoz 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óival való használatra szolgál, azonban azokat közzéteheti.
sid Munkamenet-azonosító, amelyet munkamenet-felhasználónkénti kijelentkezéshez használnak JWT Személyes és Microsoft Entra-fiókok.
tenant_ctry Erőforrás-bérlő országa/régiója JWT Ugyanaz, mint ctry a rendszergazda által bérlői szinten beállított érték. 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 paraméterrel username_hint 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 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 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 használati jogcímet login_hint kell használnia – az login_hint 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 ID 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ímekkel acrsegyütt. 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. cp1 A hozzáférési jogkivonat é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 rendelkeznek ellenőrzött tartományokkal. Ahhoz, hogy ezt az 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ókért tekintse meg a Microsoft Entra Csatlakozás előnyben részesített adathelyre vonatkozó dokumentációját.
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 használt Windows AutoPiloteszközidentitás.

Figyelmeztetés

Soha ne használjon email vagy upn igényeljen értékeket az adatok tárolására, illetve annak meghatározására, hogy a hozzáférési jogkivonatban lévő 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 Jegyzetek
ipaddr IP Address 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árati idejét iat követő 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. Az MFA megbízható IP-beállításai 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 hatókört profile 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 hatókört profile igényli.
upn Felhasználó egyszerű neve A paraméterrel username_hint 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 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 az alábbi preferred_username jogcímet a bejelentkezési állapot felhasználónak való megjelenítéséhez. A hatókört profile 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 Jegyzetek
aud Célközönsé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. Ezzel additionalProperties a jogcímmel biztosíthatja, hogy mindig az erőforrás ügyfél-azonosítójára legyen á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, upn hogy használ, vagy unique_name. v1 azonosító jogkivonatok és hozzáférési jogkivonatok

additionalProperties választható jogcímek

Néhány választható jogcím konfigurálható úgy, hogy módosítsa a jogcím visszaadásának módját. Ezek additionalProperties többnyire a különböző adatmegáltalással rendelkező helyszíni alkalmazások migrálásának elősegítésére szolgálnak. Segít például azoknak az ügyfeleknek, include_externally_authenticated_upn_without_hash amelyek nem tudják kezelni a kivonatjeleket (#) az UPN-ben.

Tulajdonság neve additionalProperty név 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 jogcím formátumának aud 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 az 00001111-aaaa-2222-bbbb-3333cccc4444, minden olyan alkalmazás, amely hozzáférési jogkivonatot kér az adott erőforráshoz, a következővel kap hozzáférési jogkivonatot aud : 00001111-aaaa-2222-bbbb-3333cccc4444. A jogcímkészlet nélkül az API-k jogkivonatokat kaphatnak az adott API-hoz tartozó alkalmazásazonosító URI-jaként beállított, api://MyApi.com/illetve az erőforrás ügyfélazonosítójával rendelkező jogkivonatokkal audapi://MyApi.com. api://myapi.com/AdditionalRegisteredField
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 idtyp felhasználói jogkivonat 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 az optionalClaims objektum azt eredményezi, hogy az ügyfélnek visszaadott azonosító jogkivonat egy jogcímet upn tartalmaz a többi otthoni bérlői és erőforrás-bérlői információval együtt. A upn jogcím csak akkor módosul a jogkivonatban, ha a felhasználó vendég a bérlőben (amely egy másik identitásszolgáltatót használ a hitelesítéshez).

Lásd még

Következő lépések