Volitelné referenční informace k deklaracím

  • Článek

Možné případy použití volitelných deklarací identity:

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

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 – Podporováno
Účet Microsoft Entra Podporováno Podporováno

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. Když přidáte deklarace identity do přístupového tokenu, deklarace identity se vztahují na přístupové tokeny požadované pro aplikaci (webové rozhraní API), nikoli deklarace identitypožadované aplikací. 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.

Název Popis Typ tokenu Typ uživatele Notes
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 deklarací xms_cc 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í, jestli má uživatel oprávnění k přístupu k datům. Pokud k autorizaci používáte deklaraci identity e-mailu, doporučujeme provést migraci, abyste přešli na bezpečnější deklaraci 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 groups identity se používá s nastavením GroupMembershipClaims v manifestu 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 , když je token 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, aby jim pomohla bezobslužné jednotné přihlašování – aplikace A se může přihlásit uživatele, přečíst login_hint 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í, login_hint deklarace identity nezahrnuje aktuálního tenanta uživatele a při použití se jako výchozí hodnota použije domácího tenanta 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á k použití se stávajícími login_hint funkcemi sady SDK, ale je dostupná.
sid ID relace, které se používá pro odhlášení uživatele pro jednotlivé relace JWT Osobní účty a účty Microsoft Entra.
tenant_ctry Země nebo oblast tenanta prostředku JWT Totéž jako ctry s výjimkou nastaveného správcem na úrovni tenanta. 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 použijte ID objektu uživatele (oid) jako klíč databáze. 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 použití byste měli použít login_hint deklaraci login_hint identity – identifikátory čitelné pro člověka, jako je hlavní název uživatele (UPN), nejsou spolehlivé.
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 deklarací identity 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 v přístupovém cp1 tokenu je autoritativní způsob identifikace, že klientská aplikace dokáže zpracovat výzvu deklarací identity. Další informace najdete v tématu Výzvy k deklarace 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 email přítomnost deklarace identity.
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 programu Microsoft Entra Připojení 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žitá pro Windows AutoPilot.

Upozorňující

Nikdy nepoužívejte email nebo upn deklarujte hodnoty k ukládání nebo určování, 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 Název Popis Notes
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 iat deklaraci identity, ve 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. profile Vyžaduje obor.
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. profile Vyžaduje obor.
upn Hlavní název uživatele (UPN) 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 použijte ID objektu uživatele (oid) jako klíč databáze. 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í preferred_username deklaraci identity pro zobrazení stavu přihlášení uživateli. profile Vyžaduje obor.

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 Název Popis Notes
aud Cílová skupina 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. Tato deklarace identity se používá additionalProperties k zajištění, ž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 použít tuto volitelnou deklaraci identity místo použití nebo upnunique_name. 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. Nejčastěji se additionalProperties používají k migraci místních aplikací s různými očekáváními dat. Pomáhá například include_externally_authenticated_upn_without_hash klientům, kteří nemůžou zpracovat značky hash () v hlavním názvu uživatele (#UPN).

Název vlastnosti additionalProperty Jméno 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 v předchozím seznamu, s výjimkou toho, že se značky hash (#) nahradí 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 aud deklarace identity. 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 Generuje ID klienta prostředku (API) ve formátu GUID, protože aud deklarace identity vždy není 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 : aud00001111-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 jakoukoli 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 idtyp deklaraci identity pro token uživatele. Bez této volitelné další vlastnosti pro sadu deklarací identity idtyp získá rozhraní API pouze deklaraci pro tokeny aplikace.

additionalProperties Příklad

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

Tento optionalClaims objekt způsobí, že token ID vrácený klientovi zahrne upn deklaraci identity s informacemi o jiném domovském tenantovi a tenantovi prostředku. Deklarace upn identity 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é

Další kroky