Referentie voor id-tokenclaims

Artikel
10/24/2023

Id-tokens zijn JSON-webtokens (JWT). De v1.0- en v2.0-id-tokens hebben verschillen in de informatie die ze bevatten. De versie is gebaseerd op het eindpunt van waaruit het is aangevraagd. Hoewel bestaande toepassingen waarschijnlijk gebruikmaken van het Azure AD v1.0-eindpunt, moeten nieuwe toepassingen het v2.0-eindpunt gebruiken.

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

Alle JWT-claims die in de volgende secties worden vermeld, worden weergegeven in zowel v1.0- als v2.0-tokens, tenzij anders vermeld. Id-tokens bestaan uit een header, nettolading en handtekening. De header en handtekening worden gebruikt om de echtheid van het token te verifiëren, terwijl de nettolading de informatie bevat over de gebruiker die door uw client is aangevraagd.

Headerclaims

In de volgende tabel ziet u headerclaims die aanwezig zijn in id-tokens.

Claim	Indeling	Beschrijving
`typ`	Tekenreeks - altijd 'JWT'	Geeft aan dat het token een JWT-token is.
`alg`	String	Geeft het algoritme aan dat is gebruikt om het token te ondertekenen. Bijvoorbeeld: 'RS256'
`kid`	String	Hiermee geeft u de vingerafdruk op voor de openbare sleutel die kan worden gebruikt om de handtekening van het token te valideren. Verzonden in zowel v1.0- als v2.0-id-tokens.
`x5t`	String	Werkt hetzelfde (in gebruik en waarde) als `kid`. `x5t` is een verouderde claim die alleen wordt verzonden in v1.0 ID-tokens voor compatibiliteitsdoeleinden.

Nettoladingclaims

In de volgende tabel ziet u de claims die zich standaard in de meeste id-tokens bevinden (behalve waar vermeld). Uw app kan echter optionele claims gebruiken om meer claims aan te vragen in het id-token. Optionele claims kunnen variëren van de groups claim tot informatie over de naam van de gebruiker.

Claim	Indeling	Beschrijving
`aud`	Tekenreeks, een GUID van een app-id	Identificeert de beoogde ontvanger van het token. In `id_tokens`, de doelgroep is de toepassings-id van uw app, toegewezen aan uw app in Azure Portal. Deze waarde moet worden gevalideerd. Het token moet worden geweigerd als het niet overeenkomt met de toepassings-id van uw app.
`iss`	Tekenreeks, een URI van verlener	Identificeert de verlener of 'autorisatieserver' die het token samenwerkt en retourneert. Het identificeert ook de tenant waarvoor de gebruiker is geverifieerd. Als het token is uitgegeven door het v2.0-eindpunt, eindigt de URI in `/v2.0`. De GUID die aangeeft dat de gebruiker een consumentgebruiker is van een Microsoft-account is `9188040d-6c67-4c5b-b112-36a304b66dad`. Uw app moet het GUID-gedeelte van de claim gebruiken om de set tenants te beperken die zich kunnen aanmelden bij de app, indien van toepassing.
`iat`	int, een Unix-tijdstempel	Geeft aan wanneer de verificatie voor het token heeft plaatsgevonden.
`idp`	Tekenreeks, meestal een STS-URI	Registreert de identiteitsprovider waarmee het onderwerp van het token is geverifieerd. Deze waarde is identiek aan de waarde van de verlenerclaim, tenzij het gebruikersaccount zich niet in dezelfde tenant bevindt als de verlener: gasten, bijvoorbeeld. Als de claim niet aanwezig is, betekent dit dat de waarde ervan in plaats daarvan `iss` kan worden gebruikt. Voor persoonlijke accounts die worden gebruikt in een organisatiecontext (bijvoorbeeld een persoonlijk account dat is uitgenodigd voor een tenant), kan de `idp` claim 'live.com' of een STS-URI met de Tenant `9188040d-6c67-4c5b-b112-36a304b66dad`van het Microsoft-account zijn.
`nbf`	int, een Unix-tijdstempel	Identificeert de tijd voordat de JWT niet kan worden geaccepteerd voor verwerking.
`exp`	int, een Unix-tijdstempel	Identificeert de verlooptijd op of waarna de JWT niet kan worden geaccepteerd voor verwerking. In bepaalde omstandigheden kan een resource het token vóór deze tijd afwijzen. Als er bijvoorbeeld een wijziging in de verificatie is vereist of als er een tokenintrekking is gedetecteerd.
`c_hash`	String	De code-hash is alleen opgenomen in id-tokens wanneer het id-token wordt uitgegeven met een OAuth 2.0-autorisatiecode. Het kan worden gebruikt om de echtheid van een autorisatiecode te valideren. Zie de OpenID Verbinding maken specificatie voor meer informatie over hoe u deze validatie uitvoert. Deze claim wordt niet geretourneerd op id-tokens van het /token-eindpunt.
`at_hash`	String	De hash van het toegangstoken is alleen opgenomen in id-tokens wanneer het id-token wordt uitgegeven vanaf het `/authorize` eindpunt met een OAuth 2.0-toegangstoken. Het kan worden gebruikt om de echtheid van een toegangstoken te valideren. Zie de OpenID Verbinding maken specificatie voor meer informatie over hoe u deze validatie uitvoert. Deze claim wordt niet geretourneerd op id-tokens van het `/token` eindpunt.
`aio`	Ondoorzichtige tekenreeks	Een interne claim die wordt gebruikt om gegevens vast te leggen voor hergebruik van tokens. Moet worden genegeerd.
`preferred_username`	String	De primaire gebruikersnaam die de gebruiker vertegenwoordigt. Dit kan een e-mailadres, telefoonnummer of een algemene gebruikersnaam zijn zonder een opgegeven indeling. De waarde is veranderlijk en kan na verloop van tijd veranderen. Omdat deze waarde onveranderbaar is, kan deze waarde niet worden gebruikt om autorisatiebeslissingen te nemen. Het kan worden gebruikt voor hints voor gebruikersnamen en in de door mensen leesbare gebruikersinterface als gebruikersnaam. Het `profile` bereik is vereist om deze claim te ontvangen. Alleen aanwezig in v2.0-tokens.
`email`	String	Standaard aanwezig voor gastaccounts met een e-mailadres. Uw app kan de e-mailclaim aanvragen voor beheerde gebruikers (van dezelfde tenant als de resource) met behulp van de `email`optionele claim. Deze waarde is niet gegarandeerd correct en is in de loop van de tijd veranderlijk. Gebruik deze nooit voor autorisatie of om gegevens voor een gebruiker op te slaan. Als u een adresseerbaar e-mailadres in uw app nodig hebt, vraagt u deze gegevens rechtstreeks aan bij de gebruiker door deze claim als suggestie te gebruiken of vooraf in te vullen in uw UX. Op het v2.0-eindpunt kan uw app ook het `email` OpenID-Verbinding maken bereik aanvragen. U hoeft niet zowel de optionele claim als het bereik aan te vragen om de claim op te halen.
`name`	String	De `name` claim biedt een door mensen leesbare waarde waarmee het onderwerp van het token wordt geïdentificeerd. De waarde is niet gegarandeerd uniek, kan worden gewijzigd en mag alleen worden gebruikt voor weergavedoeleinden. Het `profile` bereik is vereist om deze claim te ontvangen.
`nonce`	String	De nonce komt overeen met de parameter die is opgenomen in de oorspronkelijke autorisatieaanvraag voor de IDP. Als dit niet overeenkomt, moet uw toepassing het token afwijzen.
`oid`	Tekenreeks, een GUID	De onveranderbare id voor een object, in dit geval, een gebruikersaccount. Deze id identificeert de gebruiker in verschillende toepassingen: twee verschillende toepassingen die zich aanmelden bij dezelfde gebruiker, ontvangen dezelfde waarde in de `oid` claim. Microsoft Graph retourneert deze id als de `id` eigenschap voor een gebruikersaccount. Omdat het `oid` toestaat dat meerdere apps gebruikers correleren, is het `profile` bereik vereist om deze claim te ontvangen. Als één gebruiker in meerdere tenants bestaat, bevat de gebruiker een andere object-id in elke tenant. Ze worden beschouwd als verschillende accounts, zelfs als de gebruiker zich aanmeldt bij elk account met dezelfde referenties. De `oid` claim is een GUID en kan niet opnieuw worden gebruikt.
`roles`	Matrix met tekenreeksen	De set rollen die zijn toegewezen aan de gebruiker die zich aanmeldt.
`rh`	Ondoorzichtige tekenreeks	Een interne claim die wordt gebruikt om tokens opnieuw te valideren. Moet worden genegeerd.
`sub`	String	Het onderwerp van de informatie in het token. Bijvoorbeeld de gebruiker van een app. Deze waarde is onveranderbaar en kan niet opnieuw worden toegewezen of opnieuw worden gebruikt. Het onderwerp is een paargewijze id en is uniek voor een toepassings-id. Als één gebruiker zich aanmeldt bij twee verschillende apps met twee verschillende client-id's, ontvangen deze apps twee verschillende waarden voor de onderwerpclaim. Mogelijk wilt u twee waarden al dan niet afhankelijk van uw architectuur- en privacyvereisten.
`tid`	Tekenreeks, een GUID	Vertegenwoordigt de tenant waarmee de gebruiker zich aanmeldt. Voor werk- en schoolaccounts is de GUID de onveranderbare tenant-id van de organisatie waarmee de gebruiker zich aanmeldt. Voor aanmeldingen bij de persoonlijke Microsoft-accounttenant (services zoals Xbox, Teams for Life of Outlook), is `9188040d-6c67-4c5b-b112-36a304b66dad`de waarde .
`unique_name`	String	Alleen aanwezig in v1.0-tokens. Biedt een voor mensen leesbare waarde waarmee het onderwerp van het token wordt geïdentificeerd. Deze waarde is niet gegarandeerd uniek binnen een tenant en mag alleen worden gebruikt voor weergavedoeleinden.
`uti`	String	Token-id-claim, gelijk aan `jti` in de JWT-specificatie. Unieke, per token-id die hoofdlettergevoelig is.
`ver`	Tekenreeks, 1.0 of 2.0	Geeft de versie van het id-token aan.
`hasgroups`	Boolean	Als deze aanwezig is, altijd waar, wordt opgegeven dat de gebruiker zich in ten minste één groep bevindt. Wordt gebruikt in plaats van de groepsclaim voor JWT's in impliciete toekenningsstromen wanneer de volledige groepsclaim het URI-fragment uitbreidt buiten de URL-lengtelimieten (momenteel zes of meer groepen). Geeft aan dat de client de Microsoft Graph API moet gebruiken om de groepen van de gebruiker te bepalen (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`).
`groups:src1`	JSON-object	Voor tokenaanvragen die niet beperkt zijn in lengte (zie `hasgroups`) maar nog steeds te groot zijn voor het token, wordt een koppeling naar de volledige lijst met groepen voor de gebruiker opgenomen. Voor JWT's als een gedistribueerde claim, voor SAML als een nieuwe claim in plaats van de `groups` claim. Voorbeeld van JWT-waarde: `"groups":"src1"` `"_claim_sources`: `"src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }` Zie Groepen-overschrijdingsclaim voor meer informatie.

Claims gebruiken om een gebruiker betrouwbaar te identificeren

Wanneer u een gebruiker identificeert, is het essentieel om informatie te gebruiken die constant en uniek blijft in de tijd. Oudere toepassingen gebruiken soms velden zoals het e-mailadres, telefoonnummer of UPN. Al deze velden kunnen na verloop van tijd worden gewijzigd en kunnen ook in de loop van de tijd opnieuw worden gebruikt. Als een werknemer bijvoorbeeld de naam wijzigt of een werknemer een e-mailadres krijgt dat overeenkomt met dat van een eerdere werknemer, wordt deze werknemer niet meer weergegeven. Uw toepassing mag geen door mensen leesbare gegevens gebruiken om een gebruiker te identificeren. Mensen die kunnen worden gelezen, betekent meestal dat iemand deze kan lezen en deze wil wijzigen. Gebruik in plaats daarvan de claims die worden geleverd door de OIDC-standaard of de uitbreidingsclaims die worden geleverd door Microsoft: de sub en oid claims.

Als u gegevens per gebruiker correct wilt opslaan, gebruikt sub of oid alleen (die als GUID's uniek zijn), waarbij tid deze indien nodig wordt gebruikt voor routering of sharding. Als u gegevens wilt delen tussen services oid en tid dit het beste is, krijgen alle apps hetzelfde oid en tid claims voor een gebruiker die in een tenant handelt. De sub claim is een paarsgewijze waarde die uniek is. De waarde is gebaseerd op een combinatie van de tokenontvanger, tenant en gebruiker. Twee apps die id-tokens voor een gebruiker aanvragen, ontvangen verschillende sub claims, maar dezelfde oid claims voor die gebruiker.

Notitie

Gebruik de idp claim niet om informatie over een gebruiker op te slaan in een poging om gebruikers in verschillende tenants te correleren. Het werkt niet, omdat de oid en sub claims voor een gebruiker per ontwerp worden gewijzigd in tenants om ervoor te zorgen dat toepassingen gebruikers in tenants niet kunnen bijhouden.

Gastscenario's, waarbij een gebruiker zich in de ene tenant bevindt en zich in een andere tenant verifieert, moet de gebruiker behandelen alsof deze een gloednieuwe gebruiker voor de service is. Uw documenten en bevoegdheden in de ene tenant mogen niet van toepassing zijn in een andere tenant. Deze beperking is belangrijk om onopzettelijke gegevenslekken in tenants te voorkomen en het afdwingen van gegevenslevenscycli. Het verwijderen van een gast uit een tenant moet ook de toegang tot de gegevens verwijderen die ze in die tenant hebben gemaakt.

Overschrijdingsclaim voor groepen

Om ervoor te zorgen dat de grootte van het token niet groter is dan de limieten voor HTTP-headers, is het aantal object-id's dat in de groups claim is opgenomen, beperkt. Als een gebruiker lid is van meer groepen dan de overschrijdingslimiet (150 voor SAML-tokens, 200 voor JWT-tokens), wordt de groepsclaim niet opgenomen in het token. In plaats daarvan bevat het een overschrijdingsclaim in het token dat aangeeft aan de toepassing om een query uit te voeren op de Microsoft Graph API om het groepslidmaatschap van de gebruiker op te halen.

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

Volgende stappen

Meer informatie over de id-tokens die worden gebruikt in Microsoft Entra ID.

Share via