Referenční informace k deklaracím přístupového tokenu

Článek
03/09/2024

Přístupové tokeny jsou webové tokeny JSON (JWT). JWT obsahují následující části:

Hlavička – poskytuje informace o tom, jak token ověřit, včetně informací o typu tokenu a jeho podpisové metodě.
Datová část – obsahuje všechna důležitá data o uživateli nebo aplikaci, která se pokouší službu volat.
Podpis – je surovina použitá k ověření tokenu.

Každá část je oddělena tečkou (.) a samostatně zakódovanou základní 64.

Deklarace identity jsou k dispozici pouze v případě, že existuje hodnota k vyplnění. Aplikace by neměla spoléhat na přítomnost deklarace identity. Mezi příklady patří pwd_exp (ne každý tenant vyžaduje vypršení platnosti hesel) a family_name (toky přihlašovacích údajů klienta jsou jménem aplikací, které nemají názvy). Přístupový token bude vždy obsahovat dostatečné deklarace identity pro vyhodnocení přístupu.

Platforma Microsoft Identity Platform používá některé deklarace identity, které pomáhají zabezpečit tokeny pro opakované použití. Popis Opaque těchto deklarací identity označuje, že nejsou určené pro veřejnou spotřebu. Tyto deklarace identity se můžou nebo nemusí zobrazovat v tokenu a nové se můžou přidat bez předchozího upozornění.

Deklarace identity hlaviček

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

Deklarace identity datové části

Deklarace identity	Formát	Popis	Důležité informace o autorizaci
`acrs`	Pole JSON řetězců	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.
`aud`	Řetězec, identifikátor URI nebo GUID ID aplikace	Identifikuje zamýšlenou cílovou skupinu tokenu. V tokenech v2.0 je tato hodnota vždy ID klienta rozhraní API. V tokenech v1.0 to může být ID klienta nebo identifikátor URI prostředku použitý v požadavku. Hodnota může záviset na tom, jak klient požadoval token.	Tato hodnota se musí ověřit, odmítnout token, pokud hodnota neodpovídá zamýšlené cílové skupině.
`iss`	Řetězec, identifikátor URI služby tokenů zabezpečení (STS)	Identifikuje službu TOKENS, která vytváří a vrací token, a tenanta Microsoft Entra ověřeného uživatele. Pokud je vystavený token v2.0 (viz `ver` deklarace identity), 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 může použít část deklarace identity GUID k omezení sady tenantů, kteří se mohou přihlásit k aplikaci, pokud je to možné.
`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 vystavitele, pokud uživatelský účet není ve stejném tenantovi jako vystavitel, například hosté. Použijte hodnotu `iss` , pokud deklarace identity není k dispozici. Pro osobní účty používané v kontextu organizace (například osobní účet pozvaný do tenanta Microsoft Entra) `idp` může být deklarace identity "live.com" nebo identifikátor URI služby STS obsahujícího tenanta `9188040d-6c67-4c5b-b112-36a304b66dad`účtu Microsoft .
`iat`	int, časové razítko Unixu	Určuje, kdy došlo k ověření tohoto tokenu.
`nbf`	int, časové razítko Unixu	Určuje čas, po kterém lze JWT zpracovat.
`exp`	int, časové razítko Unixu	Určuje dobu vypršení platnosti, před kterou lze přijmout JWT ke zpracování. Prostředek může token před tímto časem odmítnout. K zamítnutí může dojít při požadované změně ověřování nebo při odvolání tokenu.
`aio`	Neprůzný řetězec	Interní deklarace identity používaná ID Microsoft Entra k zaznamenání dat pro opakované použití tokenu. Prostředky by neměly tuto deklaraci identity používat.
`acr`	Řetězec, a `0` nebo `1`, pouze v tokenech verze 1.0	Hodnota `0` deklarace identity "Třída kontextu ověřování" značí, že ověřování koncového uživatele nesplní požadavky ISO/IEC 29115.
`amr`	Pole JSON řetězců, pouze v tokenech v1.0	Identifikuje metodu ověřování předmětu tokenu.
`appid`	Řetězec, identifikátor GUID, pouze v tokenech verze 1.0	ID aplikace klienta pomocí tokenu. Aplikace může jednat jako sám nebo jménem uživatele. ID aplikace obvykle představuje objekt aplikace, ale může také představovat instanční objekt v Microsoft Entra ID.	`appid` může být používán při rozhodování o autorizaci.
`azp`	Řetězec, identifikátor GUID, pouze v tokenech v2.0	Náhrada za `appid`. ID aplikace klienta pomocí tokenu. Aplikace může jednat jako sám nebo jménem uživatele. ID aplikace obvykle představuje objekt aplikace, ale může také představovat instanční objekt v Microsoft Entra ID.	`azp` může být používán při rozhodování o autorizaci.
`appidacr`	Řetězec, znak `0`, `1`nebo `2`, pouze v tokenech verze 1.0	Označuje metodu ověřování klienta. Pro veřejného klienta je `0`hodnota . Pokud použijete ID klienta a tajný klíč klienta, hodnota je `1`. Pokud k ověřování použijete klientský certifikát, hodnota je `2`.
`azpacr`	Řetězec, znak `0`, `1`nebo `2`, pouze v tokenech verze 2.0	Náhrada za `appidacr`. Označuje metodu ověřování klienta. Pro veřejného klienta je `0`hodnota . Pokud použijete ID klienta a tajný klíč klienta, hodnota je `1`. Pokud k ověřování použijete klientský certifikát, hodnota je `2`.
`preferred_username`	Řetězec, který se nachází pouze v tokenech v2.0	Primární uživatelské jméno, které představuje uživatele. Hodnota může být e-mailová adresa, telefonní číslo nebo obecné uživatelské jméno bez zadaného formátu. Jako uživatelské jméno použijte hodnotu nápovědy uživatelského jména a v uživatelském rozhraní, které je čitelné pro člověka. Pokud chcete tuto deklaraci identity získat, použijte `profile` obor.	Vzhledem k tomu, že tato hodnota je proměnlivá, nepoužívejte ji k rozhodování o autorizaci.
`name`	String	Poskytuje hodnotu čitelnou pro člověka, která identifikuje předmět tokenu. Hodnota se může lišit, je proměnlivá a je určená jenom pro účely zobrazení. Pokud chcete tuto deklaraci identity získat, použijte `profile` obor.	Tuto hodnotu nepoužívejte k rozhodování o autorizaci.
`scp`	Řetězec, seznam oborů oddělených mezerou	Sada oborů vystavených aplikací, pro kterou klientská aplikace požadovala (a přijala) souhlas. Součástí jsou pouze tokeny uživatele.	Aplikace by měla ověřit, že tyto obory jsou platné, které aplikace vystavuje, a provádět rozhodnutí o autorizaci na základě hodnoty těchto oborů.
`roles`	Pole řetězců, seznam oprávnění	Sada oprávnění vystavená aplikací, kterou žádající aplikace nebo uživatel udělila oprávnění k volání. Tok přihlašovacích údajů klienta používá tuto sadu oprávnění místo oborů uživatele pro tokeny aplikace. Pro tokeny uživatele obsahuje tato sada hodnot přiřazené role uživatele v cílové aplikaci.	Tyto hodnoty se dají použít ke správě přístupu, například k vynucení autorizace pro přístup k prostředku.
`wids`	Pole identifikátorů GUID roleTemplateID	Označuje role pro celého tenanta přiřazené tomuto uživateli z části rolí, které jsou přítomné v předdefinovaných rolích Microsoft Entra. Vlastnost `groupMembershipClaims` manifestu aplikace konfiguruje tuto deklaraci identity na základě jednotlivých aplikací. Nastavte deklaraci na `All` hodnotu nebo `DirectoryRole`. V tokenech získaných prostřednictvím implicitního toku se nemusí vyskytovat kvůli obavám o délku tokenu.	Tyto hodnoty se dají použít ke správě přístupu, například k vynucení autorizace pro přístup k prostředku.
`groups`	Pole JSON identifikátorů GUID	Poskytuje ID objektů, která představují členství ve skupině předmětu. `groupMembershipClaims` Vlastnost manifestu aplikace konfiguruje deklaraci identity skupin pro jednotlivé aplikace. Hodnota `null` vyloučení všech skupin, hodnota `SecurityGroup` zahrnuje pouze členství ve skupinách zabezpečení služby Active Directory a hodnota `All` zahrnuje jak skupiny zabezpečení, tak distribuční seznamy Microsoftu 365. `hasgroups` Podrobnosti o použití `groups` deklarace identity s implicitní udělením najdete v deklaraci identity. U jiných toků platí, že pokud počet skupin, ve které se uživatel nachází, přesáhne 150 pro SAML a 200 pro JWT, pak Microsoft Entra ID přidá do zdrojů deklarací identity nadlimitní využití. Zdroje deklarací identity odkazují na koncový bod Microsoft Graphu, který obsahuje seznam skupin pro uživatele.	Tyto hodnoty se dají použít ke správě přístupu, například k vynucení autorizace pro přístup k prostředku.
`hasgroups`	Logická hodnota	Pokud je k dispozici, vždy `true`určuje, jestli je uživatel alespoň v jedné skupině. Používá se místo `groups` deklarace identity pro JWT v implicitních tocích udělení, pokud by úplná deklarace identity skupin rozšířila 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 uživatele`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects` použít rozhraní Microsoft Graph API.
`groups:src1`	Objekt JSON	Obsahuje odkaz na úplný seznam skupin pro uživatele, pokud jsou požadavky na token pro token příliš velké. 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" }`
`sub`	String	Objekt zabezpečení přidružený k tokenu. Například uživatel aplikace. Tato hodnota je neměnná, nepřiřaďte ji ani znovu nepoužívejte. Předmět je párový identifikátor, který je jedinečný pro konkrétní ID aplikace. Pokud se jeden uživatel přihlásí ke dvěma různým aplikacím pomocí dvou různých ID klienta, obdrží tyto aplikace dvě různé hodnoty pro deklaraci identity subjektu. Použití těchto dvou různých hodnot závisí na architektuře a požadavcích na ochranu osobních údajů. Viz také `oid` deklarace identity, která zůstává stejná napříč aplikacemi v rámci tenanta.	Tuto hodnotu je možné použít k provádění kontrol autorizace, například při použití tokenu pro přístup k prostředku, a lze ji použít jako klíč v databázových tabulkách.
`oid`	Řetězec, identifikátor GUID	Neměnný identifikátor žadatele, což je ověřená identita uživatele nebo instančního objektu. Toto ID jednoznačně identifikuje žadatele napříč aplikacemi. Dvě různé aplikace, které se přihlašuje ke stejnému `oid` uživateli, obdrží stejnou hodnotu v deklaraci identity. Dá `oid` se použít při vytváření dotazů do Microsoft online služby, jako je Například Microsoft Graph. Microsoft Graph vrátí toto ID jako `id` vlastnost daného uživatelského účtu. `oid` Vzhledem k tomu, že umožňuje více aplikacím korelovat objekty zabezpečení, aby tato deklarace identity pro uživatele používala `profile` obor. Pokud jeden uživatel existuje ve více tenantech, obsahuje uživatel v každém tenantovi jiné ID objektu. I když se uživatel přihlásí ke každému účtu se stejnými přihlašovacími údaji, liší se účty.	Tuto hodnotu je možné použít k provádění kontrol autorizace, například při použití tokenu pro přístup k prostředku, a lze ji použít jako klíč v databázových tabulkách.
`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 . Aby aplikace tuto deklaraci identity získala, musí požádat o `profile` obor.	Tato hodnota by se měla při rozhodování o autorizaci považovat za kombinaci s jinými deklaracemi.
`unique_name`	Řetězec, pouze v tokenech verze 1.0	Poskytuje lidsky čitelnou hodnotu, která identifikuje subjekt tokenu.	Tato hodnota se může v rámci tenanta lišit a používat ji 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.
`rh`	Neprůzný řetězec	Interní deklarace identity používaná Azure k opětovnému obnovení tokenů. Prostředky by neměly tuto deklaraci identity používat.
`ver`	Řetězec, buď `1.0` nebo `2.0`	Označuje verzi přístupového tokenu.
`xms_cc`	Pole JSON řetězců	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.

Deklarace nadlimitního využití skupin

Microsoft Entra ID omezuje počet ID objektů, které zahrnuje do deklarací identity skupin, aby zůstal v rámci limitu velikosti hlavičky HTTP. Pokud je uživatel členem více skupin, než je limit nadlimitního využití (150 pro tokeny SAML, 200 pro tokeny JWT a pouze 6, pokud je vydáno pomocí implicitního toku), Pak Microsoft Entra ID nevygeneruje deklaraci identity skupin v tokenu. Místo toho obsahuje deklaraci nadlimitního využití v tokenu, která značí aplikaci, aby dotazování rozhraní Microsoft Graph API načetla členství uživatele ve skupině.

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

Pomocí složky BulkCreateGroups.ps1Skripty pro vytváření aplikací můžete otestovat scénáře nadlimitního využití.

Poznámka:

Vrácená adresa URL bude adresa URL služby Azure AD Graph (tj. graph.windows.net). Místo spoléhání na tuto adresu URL by služby měly místo toho použít idtyp volitelnou deklaraci identity (která identifikuje, jestli je token aplikací nebo tokenem aplikace a uživatele) k vytvoření adresy URL Microsoft Graphu pro dotazování na úplný seznam skupin.

Základní deklarace identity v1.0

Tokeny v1.0 obsahují následující deklarace identity, pokud jsou k dispozici, ale ve výchozím nastavení ne tokeny v2.0. Pokud chcete tyto deklarace identity použít pro v2.0, aplikace je požádá o použití volitelných deklarací identity.

Deklarace identity	Formát	Popis
`ipaddr`	String	IP adresa, ze které se uživatel ověřil.
`onprem_sid`	Řetězec ve formátu SID	V případech, kdy má uživatel místní ověřování, tato deklarace identity poskytuje identifikátor SID. Tuto deklaraci identity použijte pro autorizaci ve starších aplikacích.
`pwd_exp`	int, časové razítko Unixu	Označuje, kdy vyprší platnost hesla uživatele.
`pwd_url`	String	Adresa URL, kde můžou uživatelé resetovat svoje heslo.
`in_corp`	boolean	Signalizuje, jestli se klient přihlašuje z podnikové sítě.
`nickname`	String	Jiné jméno uživatele, oddělené od jména nebo příjmení.
`family_name`	String	Poskytuje příjmení, příjmení nebo rodinné jméno uživatele, jak je definováno v objektu uživatele.
`given_name`	String	Poskytuje jméno nebo křestní jméno uživatele, jak je nastaveno na objektu uživatele.
`upn`	String	Uživatelské jméno uživatele. Může to být telefonní číslo, e-mailová adresa nebo neformátovaný řetězec. Používá se jenom pro účely zobrazení a poskytování nápovědy uživatelského jména ve scénářích opětovného ověření.

deklarace identity amr

Identity se můžou ověřovat různými způsoby, což může být relevantní pro aplikaci. Deklarace amr identity je pole, které může obsahovat více položek, například ["mfa", "rsa", "pwd"]pro ověřování, které používalo heslo i aplikaci Authenticator.

Hodnota	Popis
`pwd`	Ověřování heslem, buď heslo Microsoftu uživatele, nebo tajný klíč klienta aplikace.
`rsa`	Ověřování bylo založeno na ověření klíče RSA, například v aplikaci Microsoft Authenticator. Tato hodnota také označuje použití JWT podepsaného svým držitelem s certifikátem X509 ve vlastnictví služby při ověřování.
`otp`	Jednorázové heslo pomocí e-mailu nebo textové zprávy
`fed`	Označuje použití federovaného ověřovacího kontrolního výrazu (například JWT nebo SAML).
`wia`	Integrované ověřování systému Windows
`mfa`	Označuje použití vícefaktorového ověřování. Zahrnuje další metody ověřování, pokud je tato deklarace identity přítomna.
`ngcmfa`	Ekvivalent k `mfa`zřizování některých pokročilých typů přihlašovacích údajů.
`wiaormfa`	Uživatel k ověření použil Windows nebo přihlašovací údaje vícefaktorového ověřování.
`none`	Označuje žádné dokončené ověřování.

Další kroky

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