Referenční informace k deklaracím identity tokenů ID

Článek
12/11/2023

Tokeny ID jsou webové tokeny JSON (JWT). Tokeny ID v1.0 a v2.0 mají rozdíly v informacích, které obsahují. Verze je založená na koncovém bodu, ze kterého byla požadována. I když stávající aplikace pravděpodobně používají koncový bod Azure AD verze 1.0, nové aplikace by měly používat koncový bod verze 2.0.

Verze 1.0: https://login.microsoftonline.com/common/oauth2/authorize
v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Všechny deklarace identity JWT uvedené v následujících částech se zobrazí v tokenech v1.0 i v2.0, pokud nejsou uvedeny jinak. Tokeny ID se skládají z hlavičky, datové části a podpisu. Hlavička a podpis slouží k ověření pravosti tokenu, zatímco datová část obsahuje informace o uživateli požadovaném klientem.

Deklarace identity hlaviček

Následující tabulka uvádí deklarace identity hlaviček, které jsou přítomné v tokenech ID.

Deklarace identity	Formát	Popis
`typ`	Řetězec – vždy "JWT"	Označuje, že token je token JWT.
`alg`	String	Označuje algoritmus, který byl použit k podepsání tokenu. Příklad: RS256
`kid`	String	Určuje kryptografický otisk veřejného klíče, který lze použít k ověření podpisu tokenu. V tokenech ID v1.0 i v2.0 se vygeneruje.
`x5t`	String	Funkce jsou stejné (při použití a hodnotě) jako `kid`. `x5t` je starší deklarace identity vygenerovaná pouze v tokenech ID verze 1.0 pro účely kompatibility.

Deklarace identity datové části

Následující tabulka uvádí deklarace identity, které jsou ve většině tokenů ID ve výchozím nastavení (s výjimkou případů, kdy jsou zaznamenány). Vaše aplikace ale může k vyžádání dalších deklarací identity v tokenu ID použít volitelné deklarace identity . Volitelné deklarace identity můžou být v rozsahu groups od deklarace identity až po informace o jménu uživatele.

Deklarace identity	Formát	Popis
`aud`	Řetězec, identifikátor GUID ID aplikace	Identifikuje zamýšlený příjemce tokenu. Cílová `id_tokens`skupina je ID aplikace přiřazené vaší aplikaci na webu Azure Portal. Tato hodnota by se měla ověřit. Token by se měl zamítnout, pokud neodpovídá ID aplikace vaší aplikace.
`iss`	Řetězec, identifikátor URI vystavitele	Identifikuje vystavitele nebo "autorizační server", který vytváří a vrací token. Identifikuje také tenanta, pro kterého byl uživatel ověřen. Pokud token vydal koncový bod v2.0, končí `/v2.0`identifikátor URI . Identifikátor GUID, který označuje, že uživatel je uživatel uživatelem z účtu Microsoft, je `9188040d-6c67-4c5b-b112-36a304b66dad`. Aplikace by měla použít část deklarace identity GUID k omezení sady tenantů, kteří se můžou k aplikaci přihlásit, pokud je to možné.
`iat`	int, časové razítko Unixu	Označuje, kdy došlo k ověření tokenu.
`idp`	Řetězec, obvykle identifikátor URI stS	Zaznamenává zprostředkovatele identity, který ověřil subjekt tokenu. Tato hodnota je stejná jako hodnota deklarace identity vystavitele, pokud uživatelský účet není ve stejném tenantovi jako vystavitel – například hosté. Pokud deklarace identity neexistuje, znamená to, že se místo toho dá použít hodnota `iss` . Pro osobní účty, které se používají v kontextu organizace (například osobní účet pozvaný do tenanta), `idp` může být deklarace identity "live.com" nebo identifikátor URI stS obsahujícího tenanta `9188040d-6c67-4c5b-b112-36a304b66dad`účtu Microsoft .
`nbf`	int, časové razítko Unixu	Určuje čas, před kterým nelze přijmout JWT ke zpracování.
`exp`	int, časové razítko Unixu	Určuje dobu vypršení platnosti, po které není možné přijmout JWT ke zpracování. Za určitých okolností může prostředek token před tímto časem odmítnout. Pokud se například vyžaduje změna ověřování nebo bylo zjištěno odvolání tokenu.
`c_hash`	String	Hodnota hash kódu je součástí tokenů ID pouze v případech, kdy je token ID vystaven s autorizačním kódem OAuth 2.0. Dá se použít k ověření pravosti autorizačního kódu. Informace o tom, jak toto ověřování provést, najdete ve specifikaci OpenID Připojení. Tato deklarace identity se nevrací u tokenů ID z koncového bodu /token.
`at_hash`	String	Hodnota hash přístupového tokenu je součástí tokenů ID pouze v případech, kdy se token ID vydá z koncového `/authorize` bodu s přístupovým tokenem OAuth 2.0. Dá se použít k ověření pravosti přístupového tokenu. Informace o tom, jak toto ověřování provést, najdete ve specifikaci OpenID Připojení. Tato deklarace identity se nevrací u tokenů ID z koncového `/token` bodu.
`aio`	Neprůzný řetězec	Interní deklarace identity, která se používá k zaznamenání dat pro opakované použití tokenu. Měla by být ignorována.
`preferred_username`	String	Primární uživatelské jméno, které představuje uživatele. Může to být e-mailová adresa, telefonní číslo nebo obecné uživatelské jméno bez zadaného formátu. Jeho hodnota je proměnlivá a může se v průběhu času měnit. Protože je proměnlivá, tato hodnota se nedá použít k rozhodování o autorizaci. Dá se použít pro rady uživatelského jména a v uživatelském rozhraní čitelném pro člověka jako uživatelské jméno. Obor `profile` je nutný k získání této deklarace identity. Prezentovat pouze v tokenech v2.0.
`email`	String	Ve výchozím nastavení je k dispozici pro účty hostů, které mají e-mailovou adresu. Vaše aplikace může požádat o deklaraci identity e-mailu pro spravované uživatele (ze stejného tenanta jako prostředek) pomocí `email`volitelné deklarace identity. Tato hodnota není zaručená, že je správná a v průběhu času je proměnlivá. Nikdy ho nepoužívejte k autorizaci ani k ukládání dat pro uživatele. Pokud v aplikaci požadujete adresovatelnou e-mailovou adresu, požádejte uživatele o tato data přímo pomocí této deklarace identity jako návrh nebo předvyplnění v uživatelském prostředí. Na koncovém bodu v2.0 může vaše aplikace také požádat `email` o rozsah OpenID Připojení – k získání deklarace identity nemusíte požadovat jak volitelnou deklaraci identity, tak rozsah.
`name`	String	Deklarace `name` identity poskytuje hodnotu čitelnou pro člověka, která identifikuje předmět tokenu. Hodnota není zaručená jako jedinečná, dá se změnit a měla by se používat jenom pro účely zobrazení. Obor `profile` je nutný k získání této deklarace identity.
`nonce`	String	Hodnota nonce odpovídá parametru, který je součástí původního požadavku na autorizaci, na IDP. Pokud se neshoduje, měla by vaše aplikace token odmítnout.
`oid`	Řetězec, identifikátor GUID	Neměnný identifikátor objektu, v tomto případě uživatelský účet. Toto ID jednoznačně identifikuje uživatele napříč aplikacemi – dvě různé aplikace, které se přihlašují ke stejnému `oid` uživateli, obdrží stejnou hodnotu v deklaraci identity. Microsoft Graph vrátí toto ID jako `id` vlastnost uživatelského účtu. `oid` Vzhledem k tomu, že umožňuje více aplikacím korelovat uživatele, `profile` je obor potřebný k přijetí této deklarace identity. Pokud jeden uživatel existuje ve více tenantech, uživatel obsahuje v každém tenantovi jiné ID objektu – považuje se za jiné účty, i když se uživatel přihlásí ke každému účtu se stejnými přihlašovacími údaji. Deklarace `oid` identity je identifikátor GUID a nedá se znovu použít.
`roles`	Pole řetězců	Sada rolí, které byly přiřazeny uživateli, který se přihlašuje.
`rh`	Neprůzný řetězec	Interní deklarace identity použitá k opětovnému ověření tokenů. Měla by být ignorována.
`sub`	String	Předmět informací v tokenu. Například uživatel aplikace. Tato hodnota je neměnná a nedá se znovu přiřadit ani znovu použít. Předmět je párový identifikátor a je jedinečný pro ID aplikace. Pokud se jeden uživatel přihlásí ke dvěma různým aplikacím pomocí dvou různých ID klientů, obdrží tyto aplikace dvě různé hodnoty pro deklaraci identity subjektu. V závislosti na architektuře a požadavcích na ochranu osobních údajů můžete nebo nechcete chtít dvě hodnoty.
`tid`	Řetězec, identifikátor GUID	Představuje tenanta, ke kterému se uživatel přihlašuje. U pracovních a školních účtů je IDENTIFIKÁTOR GUID neměnným ID tenanta organizace, ke které se uživatel přihlašuje. Pro přihlášení k osobnímu tenantovi účtu Microsoft (služby, jako jsou Xbox, Teams for Life nebo Outlook), je `9188040d-6c67-4c5b-b112-36a304b66dad`hodnota .
`unique_name`	String	Pouze v tokenech v1.0. Poskytuje lidsky čitelnou hodnotu, která identifikuje subjekt tokenu. Tato hodnota není zaručená jedinečná v rámci tenanta a měla by se používat jenom pro účely zobrazení.
`uti`	String	Deklarace identity identifikátoru tokenu, která odpovídá `jti` specifikaci JWT. Jedinečný identifikátor jednotlivých tokenů, u kterého se rozlišují malá a velká písmena.
`ver`	Řetězec, buď 1.0, nebo 2.0	Označuje verzi tokenu ID.
`hasgroups`	Boolean	Pokud je k dispozici, vždy true, označující uživatele je alespoň v jedné skupině. Používá se místo deklarace identity skupin pro JWT v implicitních tocích udělení, když úplná deklarace identity skupin rozšíří fragment identifikátoru URI nad rámec limitů délky adresy URL (aktuálně šest nebo více skupin). Označuje, že klient by měl k určení skupin`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects` uživatele () použít rozhraní Microsoft Graph API.
`groups:src1`	Objekt JSON	Pro žádosti o tokeny, které nejsou omezené na délku (viz `hasgroups`) ale stále příliš velké pro token, je zahrnut odkaz na úplný seznam skupin pro uživatele. Pro JWT jako distribuovanou deklaraci identity pro SAML jako novou deklaraci identity místo `groups` deklarace. Příklad hodnoty JWT: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Další informace najdete v tématu Deklarace nadlimitního využití skupin.

Použití deklarací identity k spolehlivé identifikaci uživatele

Při identifikaci uživatele je důležité používat informace, které zůstávají konstantní a jedinečné v čase. Starší aplikace někdy používají pole, jako je e-mailová adresa, telefonní číslo nebo hlavní název uživatele (UPN). Všechna tato pole se můžou v průběhu času měnit a dají se také opakovaně používat v průběhu času. Když třeba zaměstnanec změní jméno nebo zaměstnanec dostane e-mailovou adresu, která odpovídá předchozímu zaměstnanci, přestane být přítomným zaměstnancem. Vaše aplikace nesmí k identifikaci uživatele používat čitelná data pro člověka – obvykle to znamená, že ho někdo může přečíst a chce ho změnit. Místo toho použijte deklarace identity poskytované standardem OIDC nebo deklarace identity rozšíření poskytované Microsoftem – a suboid deklarace identity.

Pokud chcete správně ukládat informace pro jednotlivé uživatele, použijte sub nebo oid použijte samostatně (které jsou jedinečné jako identifikátory GUID), které tid se v případě potřeby používají ke směrování nebo horizontálnímu dělení. Pokud potřebujete sdílet data mezi službami a tid je nejlepší, oid protože všechny aplikace získají stejné oid a tid deklarace identity pro uživatele fungující v tenantovi. Deklarace sub identity je hodnota, která je jedinečná. Hodnota je založená na kombinaci příjemce tokenu, tenanta a uživatele. Dvě aplikace, které požadují tokeny ID pro uživatele, obdrží různé sub deklarace identity, ale stejné oid deklarace identity pro daného uživatele.

Poznámka:

Nepoužívejte idp deklaraci identity k ukládání informací o uživateli při pokusu o korelaci uživatelů napříč tenanty. Nefunguje to, protože se oid deklarace identity sub uživatele v různých tenantech mění podle návrhu, aby se zajistilo, že aplikace nemůžou sledovat uživatele napříč tenanty.

Scénáře hosta, ve kterých je uživatel domovem v jednom tenantovi a ověřuje se v jiném, by měl uživatele považovat za úplně nového uživatele služby. Vaše dokumenty a oprávnění v jednom tenantovi by se neměly vztahovat na jiného tenanta. Toto omezení je důležité, aby se zabránilo náhodnému úniku dat napříč tenanty a vynucení životního cyklu dat. Vyřazení hosta z tenanta by také mělo odebrat přístup k datům, která vytvořili v daném tenantovi.

Deklarace nadlimitního využití skupin

Aby se zajistilo, že velikost tokenu nepřekračuje limity velikosti hlavičky HTTP, je omezený počet ID objektů, které zahrnuje do groups deklarace identity. Pokud je uživatel členem více skupin, než je limit nadlimitního využití (150 pro tokeny SAML, 200 pro tokeny JWT), deklarace identity skupin se do tokenu nezahrne. Místo toho obsahuje deklaraci nadlimitního využití v tokenu, která značí aplikaci, aby se dotazování rozhraní Microsoft Graph API načetla členství ve skupině uživatele.

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

Další kroky

Přečtěte si další informace o tokenech ID používaných v Microsoft Entra ID.