Referens för ID-tokenanspråk

Artikel
10/24/2023

ID-token är JSON-webbtoken (JWT). ID-token v1.0 och v2.0 har skillnader i den information som de har. Versionen baseras på slutpunkten där den begärdes. Även om befintliga program troligen använder Azure AD v1.0-slutpunkten bör nya program använda v2.0-slutpunkten.

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

Alla JWT-anspråk som anges i följande avsnitt visas i både v1.0- och v2.0-token om inget annat anges. ID-token består av en rubrik, nyttolast och signatur. Rubriken och signaturen används för att verifiera tokens äkthet, medan nyttolasten innehåller den information om användaren som begärs av klienten.

Rubrikanspråk

I följande tabell visas rubrikanspråk som finns i ID-token.

Anspråk	Format	beskrivning
`typ`	Sträng – alltid "JWT"	Anger att token är en JWT-token.
`alg`	String	Anger den algoritm som användes för att signera token. Till exempel: "RS256"
`kid`	String	Anger tumavtrycket för den offentliga nyckeln som kan användas för att verifiera tokens signatur. Genereras i både v1.0- och v2.0-ID-token.
`x5t`	String	Fungerar på samma sätt (används och är värde) som `kid`. `x5t` är ett äldre anspråk som endast genereras i v1.0-ID-token i kompatibilitetssyfte.

Nyttolastanspråk

I följande tabell visas de anspråk som finns i de flesta ID-token som standard (förutom där det anges). Din app kan dock använda valfria anspråk för att begära fler anspråk i ID-token. Valfria anspråk kan sträcka sig från anspråket groups till information om användarens namn.

Anspråk	Format	beskrivning
`aud`	Sträng, ett app-ID-GUID	Identifierar den avsedda mottagaren av token. I `id_tokens`är målgruppen appens program-ID, tilldelat till din app i Azure Portal. Det här värdet ska verifieras. Token bör avvisas om den inte matchar appens program-ID.
`iss`	String, en utfärdar-URI	Identifierar utfärdaren eller "auktoriseringsservern" som konstruerar och returnerar token. Den identifierar också klientorganisationen som användaren autentiserades för. Om token har utfärdats av v2.0-slutpunkten slutar URI:n i `/v2.0`. DET GUID som anger att användaren är en konsumentanvändare från ett Microsoft-konto är `9188040d-6c67-4c5b-b112-36a304b66dad`. Din app bör använda GUID-delen av anspråket för att begränsa den uppsättning klienter som kan logga in på appen, om tillämpligt.
`iat`	int, en Unix-tidsstämpel	Anger när autentiseringen för token inträffade.
`idp`	Sträng, vanligtvis en STS-URI	Registrerar den identitetsprovider som har autentiserat subjektet för token. Det här värdet är identiskt med värdet för utfärdaranspråket om inte användarkontot inte finns i samma klientorganisation som utfärdaren – gäster, till exempel. Om anspråket inte finns innebär det att värdet `iss` för kan användas i stället. För personliga konton som används i en organisationskontext (till exempel ett personligt konto som bjuds in till en klientorganisation) kan anspråket `idp` vara "live.com" eller en STS-URI som innehåller Microsoft-kontoklientorganisationen `9188040d-6c67-4c5b-b112-36a304b66dad`.
`nbf`	int, en Unix-tidsstämpel	Identifierar den tid innan JWT inte kan accepteras för bearbetning.
`exp`	int, en Unix-tidsstämpel	Identifierar förfallotiden på eller efter vilken JWT inte kan accepteras för bearbetning. Under vissa omständigheter kan en resurs avvisa token före den här tiden. Om till exempel en ändring i autentisering krävs eller om ett tokenåterkallning har identifierats.
`c_hash`	String	Kodhash ingår endast i ID-token när ID-token utfärdas med en OAuth 2.0-auktoriseringskod. Den kan användas för att verifiera autenticiteten för en auktoriseringskod. Information om hur du gör den här valideringen finns i OpenID Connect-specifikationen. Det här anspråket returneras inte på ID-token från slutpunkten /token.
`at_hash`	String	Hashen för åtkomsttoken ingår endast i ID-token när ID-token utfärdas från `/authorize` slutpunkten med en OAuth 2.0-åtkomsttoken. Den kan användas för att verifiera autenticiteten för en åtkomsttoken. Information om hur du gör den här valideringen finns i OpenID Connect-specifikationen. Det här anspråket returneras inte på ID-token från `/token` slutpunkten.
`aio`	Ogenomskinlig sträng	Ett internt anspråk som används för att registrera data för återanvändning av token. Bör ignoreras.
`preferred_username`	String	Det primära användarnamnet som representerar användaren. Det kan vara en e-postadress, ett telefonnummer eller ett allmänt användarnamn utan ett angivet format. Dess värde kan ändras med tiden. Eftersom det är föränderligt kan det här värdet inte användas för att fatta auktoriseringsbeslut. Den kan användas för användarnamnstips och i användargränssnittet som ett användarnamn. Omfånget `profile` krävs för att ta emot det här anspråket. Finns endast i v2.0-token.
`email`	String	Finns som standard för gästkonton som har en e-postadress. Din app kan begära e-postanspråket för hanterade användare (från samma klientorganisation som resursen) med hjälp av det valfria anspråket `email` . Det här värdet är inte garanterat korrekt och kan ändras med tiden. Använd den aldrig för auktorisering eller för att spara data för en användare. Om du behöver en adresserbar e-postadress i din app kan du begära dessa data direkt från användaren genom att använda det här anspråket som ett förslag eller i förväg i ditt användargränssnitt. På v2.0-slutpunkten kan din app också begära `email` OpenID Connect-omfånget – du behöver inte begära både det valfria anspråket och omfånget för att hämta anspråket.
`name`	String	Anspråket `name` ger ett läsbart värde som identifierar tokens ämne. Värdet är inte garanterat unikt, det kan ändras och bör endast användas i visningssyfte. Omfånget `profile` krävs för att ta emot det här anspråket.
`nonce`	String	Nonce matchar parametern som ingår i den ursprungliga auktoriseringsbegäran till IDP:n. Om den inte matchar bör ditt program avvisa token.
`oid`	Sträng, ett GUID	Den oföränderliga identifieraren för ett objekt, i det här fallet ett användarkonto. Det här ID:t identifierar användaren unikt mellan program – två olika program som loggar in samma användare får samma värde i anspråket `oid` . Microsoft Graph returnerar detta ID som `id` egenskap för ett användarkonto. `oid` Eftersom tillåter flera appar att korrelera användare krävs omfånget för att ta emot det här anspråket`profile`. Om det finns en enskild användare i flera klientorganisationer innehåller användaren ett annat objekt-ID i varje klientorganisation – de betraktas som olika konton, även om användaren loggar in på varje konto med samma autentiseringsuppgifter. Anspråket `oid` är ett GUID och kan inte återanvändas.
`roles`	Strängmatris	Den uppsättning roller som har tilldelats till den användare som loggar in.
`rh`	Ogenomskinlig sträng	Ett internt anspråk som används för att återanvända token. Bör ignoreras.
`sub`	String	Ämnet för informationen i token. Till exempel användaren av en app. Det här värdet är oföränderligt och kan inte omtilldelas eller återanvändas. Ämnet är en parvis identifierare och är unik för ett program-ID. Om en enskild användare loggar in i två olika appar med två olika klient-ID:t får dessa appar två olika värden för ämnesanspråket. Du kanske eller kanske inte vill ha två värden beroende på din arkitektur och sekretesskrav.
`tid`	Sträng, ett GUID	Representerar den klientorganisation som användaren loggar in på. För arbets- och skolkonton är GUID det oföränderliga klientorganisations-ID för organisationen som användaren loggar in på. För inloggningar till den personliga Microsoft-kontoklientorganisationen (tjänster som Xbox, Teams for Life eller Outlook) är `9188040d-6c67-4c5b-b112-36a304b66dad`värdet .
`unique_name`	String	Finns endast i v1.0-token. Innehåller ett läsbart värde som identifierar subjektet för token. Det här värdet är inte garanterat unikt i en klientorganisation och bör endast användas i visningssyfte.
`uti`	String	Tokenidentifieraranspråk, motsvarande `jti` I JWT-specifikationen. Unik identifierare per token som är skiftlägeskänslig.
`ver`	Sträng, antingen 1.0 eller 2.0	Anger versionen av ID-token.
`hasgroups`	Booleskt	Om det finns, alltid sant, anges användaren i minst en grupp. Anger att klienten ska använda Microsoft Graph API för att fastställa användarens grupper (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	JSON-objekt	För tokenbegäranden som inte är begränsade i längd (se `hasgroups`) men fortfarande för stora för token inkluderas en länk till listan med fullständiga grupper för användaren. För JWTs som ett distribuerat anspråk för SAML som ett nytt anspråk i stället för anspråket `groups` . Exempel på JWT-värde: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Mer information finns i Överförbrukningsanspråk för grupper.

Använda anspråk för att på ett tillförlitligt sätt identifiera en användare

När du identifierar en användare är det viktigt att använda information som förblir konstant och unik över tid. Äldre program använder ibland fält som e-postadress, telefonnummer eller UPN. Alla dessa fält kan ändras över tid och kan också återanvändas över tid. Till exempel när en anställd ändrar sitt namn, eller om en anställd får en e-postadress som matchar en tidigare, inte längre presentera medarbetare. Ditt program får inte använda läsbara data för att identifiera en användare – mänsklig läsbar innebär i allmänhet att någon kan läsa den och vill ändra den. Använd i stället anspråken som tillhandahålls av OIDC-standarden eller tilläggsanspråken som tillhandahålls av Microsoft – anspråken sub och oid .

Om du vill lagra information per användare korrekt använder sub du eller oid ensam (som GUID:er är unika) med tid som används för routning eller horisontell partitionering om det behövs. Om du behöver dela data mellan tjänster oid och tid är bäst eftersom alla appar får samma oid tid och anspråk för en användare som agerar i en klientorganisation. Anspråket sub är ett parvis värde som är unikt. Värdet baseras på en kombination av tokenmottagaren, klientorganisationen och användaren. Två appar som begär ID-token för en användare får olika sub anspråk, men samma oid anspråk för den användaren.

Kommentar

Använd inte anspråket idp för att lagra information om en användare i ett försök att korrelera användare mellan klienter. Det fungerar inte, eftersom anspråken oid sub och för en användare ändras mellan klienter, avsiktligt, för att säkerställa att program inte kan spåra användare mellan klienter.

Gästscenarier, där en användare finns i en klientorganisation och autentiseras i en annan, bör behandla användaren som om användaren är en helt ny användare i tjänsten. Dina dokument och behörigheter i en klientorganisation bör inte gälla i en annan klientorganisation. Den här begränsningen är viktig för att förhindra oavsiktligt dataläckage mellan klienter och tillämpning av datalivscykler. Att ta bort en gäst från en klientorganisation bör också ta bort deras åtkomst till de data som de skapade i klientorganisationen.

Överförbrukningsanspråk för grupper

För att säkerställa att tokenstorleken inte överskrider storleksgränserna för HTTP-huvuden är antalet objekt-ID:t som ingår i anspråket groups begränsat. Om en användare är medlem i fler grupper än överförbrukningsgränsen (150 för SAML-token, 200 för JWT-token) ingår inte gruppanspråket i token. I stället innehåller den ett överförbrukningsanspråk i token som anger för programmet att fråga Microsoft Graph-API:et för att hämta användarens gruppmedlemskap.

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

Nästa steg

Läs mer om ID-token som används i Microsoft Entra-ID.

Dela via