Volitelné referenční informace k deklaracím

Volitelné deklarace identity můžete použít k:

• Vyberte deklarace identity, které chcete zahrnout do tokenů pro vaši aplikaci.
• Změňte chování určitých deklarací identity, které platforma Microsoft Identity Platform vrací v tokenech.
• Přidejte a získejte přístup k vlastním deklaracím identity pro vaši aplikaci.

I když se volitelné deklarace identity podporují ve formátových tokenech v1.0 i v2.0 a tokenech SAML, poskytují při přesunu z verze 1.0 na v2.0 většinu jejich hodnoty. V platformě Microsoft Identity Platform se k zajištění optimálního výkonu klientů používají menší velikosti tokenů. V důsledku toho se v tokenech v2.0 už v tokenech v2.0 nezobrazuje několik deklarací identity, které byly dříve zahrnuté v tokenech přístupu a ID, a proto je nutné je požádat o konkrétní použití.

Typ účtu	Tokeny v1.0	Tokeny v2.0
Osobní účet Microsoft	Není k dispozici	Podporovaný
Účet Microsoft Entra	Podporovaný	Podporovaný

Volitelná sada deklarací identity v1.0 a v2.0

Sada volitelnýchdch Vlastní data můžete použít v atributech rozšíření a rozšířeních adresáře k přidání volitelných deklarací identity pro vaši aplikaci. Při přidávání deklarací identity do přístupového tokenu se deklarace identity vztahují na přístupové tokeny požadované pro aplikace (webové rozhraní API), nikoli deklarace identity požadované aplikace. Bez ohledu na to, jak klient přistupuje k rozhraní API, se správná data nacházejí v přístupovém tokenu, který se používá k ověření ve vašem rozhraní API.

Poznámka

Většinu těchto deklarací identity je možné zahrnout do JWT pro tokeny verze 1.0 a v2.0, ale ne tokeny SAML, s výjimkou případů, kdy je uvedeno ve sloupci Typ tokenu. Uživatelské účty podporují podmnožinu těchto deklarací identity označených ve sloupci Typ uživatele. Řada uvedených deklarací identity se nevztahuje na uživatele uživatelů (nemají žádného tenanta, takže tenant_ctry nemá žádnou hodnotu).

Následující tabulka uvádí volitelnou sadu deklarací identity v1.0 a v2.0.

Jméno	Popis	Typ tokenu	Typ uživatele	Poznámky
acct	Stav účtu uživatelé v tenantovi	JWT, SAML		Pokud je uživatel členem tenanta, hodnota je 0. Pokud jsou hostem, hodnota je 1.
acrs	ID kontextu ověřování	JWT	Microsoft Entra ID	Označuje ID kontextu ověřování operací, které nosný medvěd má nárok na provedení. Id kontextu ověřování se dají použít k aktivaci poptávky po zstupňovaném ověřování v rámci vaší aplikace a služeb. Často se používá spolu s xms_cc deklarací identity.
auth_time	Čas posledního ověření uživatele	JWT
ctry	Země/oblast uživatele	JWT		Tato deklarace identity se vrátí, pokud je k dispozici a hodnota pole je standardní dvoupísmenný kód země/oblasti, například FR, JP, SZ atd.
email	Nahlášená e-mailová adresa pro tohoto uživatele	JWT, SAML	MSA, Microsoft Entra ID	Tato hodnota je ve výchozím nastavení zahrnuta, pokud je uživatel hostem v tenantovi. U spravovaných uživatelů (uživatelů uvnitř tenanta) je nutné ho požádat prostřednictvím této volitelné deklarace identity nebo pouze u verze 2.0 s rozsahem OpenID. Tato hodnota není zaručená, že je správná a v průběhu času je proměnlivá – nikdy ji nepoužívejte k autorizaci ani k ukládání dat pro uživatele. Další informace najdete v tématu Ověření, zda má uživatel oprávnění k přístupu k tomutodat . Pokud k autorizaci používáte deklaraci identity e-mailu, doporučujeme migraci přesunout na bezpečnějšídeklarací identity. Pokud v aplikaci požadujete adresovatelnou e-mailovou adresu, požádejte uživatele o tato data přímo a použijte tuto deklaraci identity jako návrh nebo předvyplnění v uživatelském prostředí.
fwd	IP adresa	JWT		Přidá původní adresu žádajícího klienta (v rámci virtuální sítě).
groups	Volitelné formátování pro deklarace identity skupin	JWT, SAML		Deklarace identity se používá s nastavením GroupMembershipClaims vmanifestu aplikace , který musí být také nastaven.
idtyp	Typ tokenu	Přístupové tokeny JWT	Speciální: pouze v přístupových tokenech jen pro aplikace	Hodnota je app, pokud je tokenem jen pro aplikaci. Tato deklarace identity představuje nejpřesnější způsob, jak rozhraní API určit, jestli je tokenem aplikace nebo tokenem aplikace a uživatele.
login_hint	Nápověda pro přihlášení	JWT	MSA, Microsoft Entra ID	Neprůhlásná, spolehlivá deklarace nápovědy pro přihlášení, která je zakódovaná na bázi 64. Tuto hodnotu neupravujte. Tato deklarace identity je nejlepší hodnotou pro použití parametru login_hint OAuth ve všech tocích, aby bylo možné získat jednotné přihlašování. Dá se předat mezi aplikacemi, které jim pomůžou bezobslužné jednotné přihlašování – aplikace A se může přihlásit uživatele, přečíst deklaraci identity a pak odeslat deklaraci identity a aktuální kontext tenanta do aplikace B v řetězci dotazu nebo fragmentu, když uživatel vybere odkaz, který je přenese do aplikace B. Aby nedocházelo k problémům se stavem časování a spolehlivostí, deklarace identity nezahrnuje aktuálního tenanta uživatele a při použití se jako výchozí použije domovský tenant uživatele. Ve scénáři hosta, ve kterém je uživatel z jiného tenanta, musí být v žádosti o přihlášení zadaný identifikátor tenanta. a předejte to stejné aplikacím, se kterými spolupracujete. Tato deklarace identity je určená pro použití se stávajícími funkcemi sady SDK login_hint, ale je dostupná.
tenant_ctry	Země nebo oblast tenanta prostředku	JWT		Stejné jako ctry kromě nastavení na úrovni tenanta správcem. Musí být také standardní dvoumísmenná hodnota.
tenant_region_scope	Oblast tenanta prostředku	JWT
upn	UserPrincipalName	JWT, SAML		Identifikátor uživatele, který lze použít s parametrem username_hint. Nejedná se o trvalý identifikátor uživatele a neměl by se používat k autorizaci ani k jedinečné identitě informací o uživateli (například jako klíč databáze). Místo toho jako klíč databáze použijte ID objektu uživatele (oid). Další informace najdete v tématu Zabezpečení aplikací a rozhraní API ověřováním deklarací identity. Uživatelé, kteří se přihlašují pomocí alternativního přihlašovacího ID, by neměli zobrazovat hlavní název uživatele (UPN). Místo toho použijte následující deklarace identity tokenu ID pro zobrazení stavu přihlášení uživateli: preferred_username nebo unique_name pro tokeny v1 a preferred_username pro tokeny v2. I když se tato deklarace identity automaticky zahrne, můžete ji zadat jako volitelnou deklaraci identity pro připojení dalších vlastností, aby se změnilo jeho chování v případě uživatele typu host. K login_hint použití byste měli použít deklaraci identity login_hint – identifikátory čitelné pro člověka, jako je hlavní název uživatele (UPN), jsou nespolehlivé.
verified_primary_email	Zdroj z primaryAuthoritativeEmail uživatele	JWT
verified_secondary_email	Zdroj ze sekundárního ověřování uživatele	JWT
vnet	Informace o specifikátoru virtuální sítě	JWT
xms_cc	Možnosti klienta	JWT	Microsoft Entra ID	Určuje, jestli klientská aplikace, která token získala, dokáže řešit problémy s deklaracemi. Často se používá spolu s deklaracemi acrs. Tato deklarace identity se běžně používá ve scénářích podmíněného přístupu a průběžného vyhodnocování přístupu. Server prostředků nebo aplikace služby, které je token vydán pro řízení přítomnosti této deklarace identity v tokenu. Hodnota cp1 v přístupovém tokenu je autoritativní způsob identifikace, že klientská aplikace dokáže zpracovat výzvu deklarací identity. Další informace najdete v tématu Problémy s deklaracemi identity, žádosti o deklarace identity a možnosti klienta.
xms_edov	Logická hodnota označující, jestli byl ověřený vlastník e-mailové domény uživatele.	JWT		E-mail se považuje za ověřený doménou, pokud patří do tenanta, ve kterém se nachází uživatelský účet, a správce tenanta provedl ověření domény. E-mail musí být také z účtu Microsoft (MSA), účtu Google nebo používaného k ověřování pomocí jednorázového toku hesla (OTP). Účty Facebook a SAML/WS-Fed nemají ověřené domény. Aby se tato deklarace identity vrátila v tokenu, je vyžadována přítomnost deklarace identity email.
xms_pdl	Upřednostňované umístění dat	JWT		U tenantů Multi-Geo je upřednostňovaným umístěním dat třímísmenný kód zobrazující geografickou oblast, ve které je uživatel. Další informace najdete v dokumentaci k Microsoft Entra Connect o upřednostňovaném umístění dat.
xms_pl	Upřednostňovaný jazyk uživatele	JWT		Upřednostňovaný jazyk uživatele, pokud je nastavený. Zdroj z domovského tenanta ve scénářích přístupu hostů. Formátovaný LL-CC ("en-us").
xms_tpl	Upřednostňovaný jazyk tenanta	JWT		Upřednostňovaný jazyk tenanta prostředku( pokud je nastavený). Formátovaný LL ("en").
ztdid	ID nasazení s nulovým dotykem	JWT		Identita zařízení používaná pro Windows AutoPilot.

Varování

Nikdy nepoužívejte email nebo upn hodnoty deklarací identity k uložení nebo určení, jestli má mít uživatel v přístupovém tokenu přístup k datům. Proměnlivé hodnoty deklarací identity, jako jsou tyto, se můžou v průběhu času měnit, takže jsou nezabezpečené a nespolehlivé pro autorizaci.

Volitelná sada deklarací identity specifická pro v2.0

Tyto deklarace identity jsou vždy zahrnuty do tokenů verze 1.0, ale nejsou součástí tokenů verze 2.0, pokud nejsou požadovány. Tyto deklarace identity platí jenom pro JWT (tokeny ID a přístupové tokeny).

Deklarace identity JWT	Jméno	Popis	Poznámky
ipaddr	IP adresa	IP adresa, ze které se klient přihlásil.
onprem_sid	Místní identifikátor zabezpečení
pwd_exp	Čas vypršení platnosti hesla	Počet sekund po uplynutí doby v deklaraci identity iat, při které vyprší platnost hesla. Tato deklarace identity se zahrne jenom v případě, že brzy vyprší platnost hesla (jak je definováno "dny oznámení" v zásadách hesel).
pwd_url	Změnit adresu URL hesla	Adresa URL, kterou může uživatel navštívit, aby změnil heslo. Tato deklarace identity se zahrne jenom v případě, že brzy vyprší platnost hesla (jak je definováno "dny oznámení" v zásadách hesel).
in_corp	Uvnitř podnikové sítě	Signalizuje, jestli se klient přihlašuje z podnikové sítě. Pokud nejsou, deklarace identity není zahrnutá.	Na základě nastavení důvěryhodných IP adres v MFA.
family_name	Příjmení	Poskytuje příjmení, příjmení nebo rodinné jméno uživatele, jak je definováno v objektu uživatele. Například "family_name":"Miller".	Podporováno v MSA a Microsoft Entra ID. Vyžaduje rozsah profile.
given_name	Křestní jméno	Poskytuje první nebo "zadané" jméno uživatele, jak je nastaveno na objekt uživatele. Například "given_name": "Frank".	Podporováno v MSA a Microsoft Entra ID. Vyžaduje rozsah profile.
upn	Hlavní název uživatele	Identifikátor uživatele, který lze použít s parametrem username_hint. Nejedná se o trvalý identifikátor uživatele a neměl by se používat k autorizaci ani k jedinečné identitě informací o uživateli (například jako klíč databáze). Další informace najdete v tématu Zabezpečení aplikací a rozhraní API ověřováním deklarací identity. Místo toho jako klíč databáze použijte ID objektu uživatele (oid). Uživatelé, kteří se přihlašují pomocí alternativního přihlašovacího ID, by neměli zobrazovat hlavní název uživatele (UPN). Místo toho použijte následující deklaraci identity preferred_username k zobrazení stavu přihlášení uživateli.	Vyžaduje rozsah profile.

Volitelná sada deklarací identity specifická pro v1.0

Některá vylepšení formátu tokenu v2 jsou dostupná pro aplikace, které používají formát tokenu v1, protože pomáhají zlepšit zabezpečení a spolehlivost. Tato vylepšení platí jenom pro JWT, nikoli tokeny SAML.

Deklarace identity JWT	Jméno	Popis	Poznámky
aud	Obecenstvo	Vždy existují v JWT, ale v přístupových tokenech v1 se dají vygenerovat různými způsoby – libovolný identifikátor URI ID aplikace, s lomítkem nebo bez koncového lomítka a ID klienta prostředku. Tato náhodnost může být při ověřování tokenu obtížná vůči kódu. Pro tuto deklaraci identity použijte additionalProperties, abyste zajistili, že je vždy nastavené na ID klienta prostředku v přístupových tokenech v1.	Pouze přístupové tokeny JWT v1
preferred_username	Upřednostňované uživatelské jméno	Poskytuje upřednostňovanou deklaraci identity uživatelského jména v rámci tokenů v1. Tato deklarace identity usnadňuje aplikacím poskytování nápovědy uživatelského jména a zobrazování zobrazovaných názvů člověka bez ohledu na jejich typ tokenu. Doporučujeme místo použití, upn nebo unique_namepoužít tuto volitelnou deklaraci identity.	Tokeny ID v1 a přístupové tokeny

additionalProperties volitelných deklarací identity

Některé volitelné deklarace identity je možné nakonfigurovat tak, aby měnily způsob vrácení deklarace identity. Tyto additionalProperties se většinou používají k migraci místních aplikací s různými očekáváními dat. Například include_externally_authenticated_upn_without_hash pomáhá klientům, kteří nemůžou zpracovat značky hash (#) v hlavního názvu uživatele (UPN).

Název vlastnosti	název additionalProperty	Popis
upn		Lze použít pro odpovědi SAML i JWT a pro tokeny v1.0 a v2.0.
	include_externally_authenticated_upn	Zahrnuje hlavní název uživatele (UPN) hosta uložený v tenantovi prostředku. Například foo_hometenant.com#EXT#@resourcetenant.com.
	include_externally_authenticated_upn_without_hash	Stejné jako dříve, s výjimkou toho, že se značky hash (#) nahrazují podtržítky (_), například foo_hometenant.com_EXT_@resourcetenant.com.
aud		V přístupových tokenech v1 se tato deklarace identity používá ke změně formátu deklarace identity aud. Tato deklarace identity nemá žádný vliv na tokeny v2 ani v tokenech ID verze, kde aud deklarace identity je vždy ID klienta. Pomocí této konfigurace se ujistěte, že vaše rozhraní API může snadněji provádět ověřování cílové skupiny. Stejně jako všechny volitelné deklarace identity, které ovlivňují přístupový token, musí prostředek v požadavku nastavit tuto volitelnou deklaraci identity, protože prostředky vlastní přístupový token.
	use_guid	Vygeneruje ID klienta prostředku (API) ve formátu GUID jako deklarace identity aud vždy místo toho, aby byla závislá na modulu runtime. Pokud například prostředek nastaví tento příznak a jeho ID klienta je 00001111-aaaa-2222-bbbb-3333cccc4444, každá aplikace, která požádá o přístupový token pro tento prostředek, obdrží přístupový token s aud : 00001111-aaaa-2222-bbbb-3333cccc4444. Bez této sady deklarací identity může rozhraní API získat tokeny s aud deklarací identity api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField nebo jinou hodnotou nastavenou jako identifikátor URI ID aplikace pro toto rozhraní API a ID klienta prostředku.
idtyp		Tato deklarace identity se používá k získání typu tokenu (aplikace, uživatel, zařízení). Ve výchozím nastavení se vygeneruje jenom pro tokeny jen pro aplikace. Stejně jako všechny volitelné deklarace identity, které ovlivňují přístupový token, musí prostředek v požadavku nastavit tuto volitelnou deklaraci identity, protože prostředky vlastní přístupový token.
	include_user_token	Vygeneruje deklaraci identity idtyp pro token uživatele. Bez této volitelné další vlastnosti pro sadu deklarací identity idtyp získá rozhraní API pouze deklaraci pro tokeny aplikace.

příklad additionalProperties

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

Tento objekt optionalClaims způsobí, že token ID vrácený klientovi zahrne deklaraci identity upn s informacemi o druhém domovském tenantovi a tenantovi prostředků. Deklarace identity upn se v tokenu změní pouze v případě, že je uživatel hostem v tenantovi (který k ověřování používá jiný protokol IDP).

Viz také

• přístupového tokenu
• tokenu ID

Další kroky

• Přečtěte si další informace o konfiguraci volitelných deklarací identity.