Id-tokens voor Microsoft-identiteitsplatform

Het id-token is de kernextensie OpenID Connect OAuth 2.0 maakt. Id-tokens worden uitgegeven door de autorisatieserver en bevatten claims die informatie over de gebruiker bevatten. Ze kunnen naast of in plaats van een toegangsken worden verzonden. Met informatie in id-tokens kan de client controleren of een gebruiker is wie hij of zij claimt te zijn. Id-tokens zijn bedoeld om te worden begrepen door toepassingen van derden. Id-tokens mogen niet worden gebruikt voor autorisatiedoeleinden. Toegangstokens worden gebruikt voor autorisatie. De claims die worden geleverd door id-tokens kunnen worden gebruikt voor UX in uw toepassing, als sleutels in een databaseen om toegang te verlenen tot de clienttoepassing.

Vereisten

Het volgende artikel is nuttig voordat u dit artikel door neemt:

Claims in een id-token

Id-tokens zijn JSON-webtokens (JWT). Deze id-tokens bestaan uit een koptekst, nettolading en handtekening. De header en handtekening worden gebruikt om de echtheid van het token te controleren, terwijl de nettolading de informatie bevat over de gebruiker die is aangevraagd door uw client. De v1.0- en v2.0-id-tokens hebben verschillen in de informatie die ze bevatten. De versie is gebaseerd op het eindpunt van waar deze is aangevraagd. Hoewel bestaande toepassingen waarschijnlijk gebruikmaken van het Azure AD-eindpunt (v1.0), moeten nieuwe toepassingen gebruikmaken van het microsoft-identiteitsplatform-eindpunt (v2.0).

  • v1.0: Azure AD-eindpunt: https://login.microsoftonline.com/common/oauth2/authorize
  • v2.0: Microsoft Identity Platform-eindpunt: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Voorbeeld van v1.0-id-token

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyIsImtpZCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyJ9.eyJhdWQiOiJiMTRhNzUwNS05NmU5LTQ5MjctOTFlOC0wNjAxZDBmYzljYWEiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkvIiwiaWF0IjoxNTM2Mjc1MTI0LCJuYmYiOjE1MzYyNzUxMjQsImV4cCI6MTUzNjI3OTAyNCwiYWlvIjoiQVhRQWkvOElBQUFBcXhzdUIrUjREMnJGUXFPRVRPNFlkWGJMRDlrWjh4ZlhhZGVBTTBRMk5rTlQ1aXpmZzN1d2JXU1hodVNTajZVVDVoeTJENldxQXBCNWpLQTZaZ1o5ay9TVTI3dVY5Y2V0WGZMT3RwTnR0Z2s1RGNCdGsrTExzdHovSmcrZ1lSbXY5YlVVNFhscGhUYzZDODZKbWoxRkN3PT0iLCJhbXIiOlsicnNhIl0sImVtYWlsIjoiYWJlbGlAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiTGluY29sbiIsImdpdmVuX25hbWUiOiJBYmUiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaXBhZGRyIjoiMTMxLjEwNy4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJub25jZSI6IjEyMzUyMyIsIm9pZCI6IjA1ODMzYjZiLWFhMWQtNDJkNC05ZWMwLTFiMmJiOTE5NDQzOCIsInJoIjoiSSIsInN1YiI6IjVfSjlyU3NzOC1qdnRfSWN1NnVlUk5MOHhYYjhMRjRGc2dfS29vQzJSSlEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6IkFiZUxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJMeGVfNDZHcVRrT3BHU2ZUbG40RUFBIiwidmVyIjoiMS4wIn0=.UJQrCA6qn2bXq57qzGX_-D3HcPHqBMOKDPx4su1yKRLNErVD8xkxJLNLVRdASHqEcpyDctbdHccu6DPpkq5f0ibcaQFhejQNcABidJCTz0Bb2AbdUCTqAzdt9pdgQvMBnVH1xk3SCM6d4BbT4BkLLj10ZLasX7vRknaSjE_C5DI7Fg4WrZPwOhII1dB0HEZ_qpNaYXEiy-o94UJ94zCr07GgrqMsfYQqFR7kn-mn68AjvLcgwSfZvyR_yIK75S_K37vC3QryQ7cNoafDe9upql_6pB2ybMVlgWPs_DmbJ8g0om-sPlwyn74Cc1tW3ze-Xptw_2uVdPgWyqfuWAfq6Q

Bekijk dit v1.0-voorbeeld token in jwt.ms.

Voorbeeld van v2.0-id-token

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFMVE16YWtpaGlSbGFfOHoyQkVKVlhlV01xbyJ9.eyJ2ZXIiOiIyLjAiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vOTEyMjA0MGQtNmM2Ny00YzViLWIxMTItMzZhMzA0YjY2ZGFkL3YyLjAiLCJzdWIiOiJBQUFBQUFBQUFBQUFBQUFBQUFBQUFJa3pxRlZyU2FTYUZIeTc4MmJidGFRIiwiYXVkIjoiNmNiMDQwMTgtYTNmNS00NmE3LWI5OTUtOTQwYzc4ZjVhZWYzIiwiZXhwIjoxNTM2MzYxNDExLCJpYXQiOjE1MzYyNzQ3MTEsIm5iZiI6MTUzNjI3NDcxMSwibmFtZSI6IkFiZSBMaW5jb2xuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiQWJlTGlAbWljcm9zb2Z0LmNvbSIsIm9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC02NmYzLTMzMzJlY2E3ZWE4MSIsInRpZCI6IjkxMjIwNDBkLTZjNjctNGM1Yi1iMTEyLTM2YTMwNGI2NmRhZCIsIm5vbmNlIjoiMTIzNTIzIiwiYWlvIjoiRGYyVVZYTDFpeCFsTUNXTVNPSkJjRmF0emNHZnZGR2hqS3Y4cTVnMHg3MzJkUjVNQjVCaXN2R1FPN1lXQnlqZDhpUURMcSFlR2JJRGFreXA1bW5PcmNkcUhlWVNubHRlcFFtUnA2QUlaOGpZIn0.1AFWW-Ck5nROwSlltm7GzZvDwUkqvhSQpm55TQsmVo9Y59cLhRXpvB8n-55HCr9Z6G_31_UbeUkoz612I2j_Sm9FFShSDDjoaLQr54CreGIJvjtmS3EkK9a7SJBbcpL1MpUtlfygow39tFjY7EVNW9plWUvRrTgVk7lYLprvfzw-CIqw3gHC-T7IK_m_xkr08INERBtaecwhTeN4chPC4W3jdmw_lIxzC48YoQ0dB1L9-ImX98Egypfrlbm0IBL5spFzL6JDZIRRJOu8vecJvj1mq-IUhGt0MacxX8jdxYLP-KUu2d9MbNKpCKJuZ7p8gwTL5B7NlUdh_dmSviPWrw

Bekijk dit v2.0-voorbeeld token in jwt.ms.

Alle hieronder vermelde JWT-claims worden weergegeven in zowel v1.0- als v2.0-tokens, tenzij anders aangegeven.

Headerclaims

In de onderstaande tabel worden headerclaims weergegeven die aanwezig zijn in id-tokens.

Claim Indeling Beschrijving
typ Tekenreeks - altijd 'JWT' Geeft aan dat het token een JWT-token is.
alg Tekenreeks Geeft het algoritme aan dat is gebruikt om het token te ondertekenen. Voorbeeld: RS256
kid Tekenreeks Vingerafdruk voor de openbare sleutel die wordt gebruikt om dit token te verifiëren. Worden zowel in v1.0 als v2.0 id_tokens uitgezonden.
x5t Tekenreeks Hetzelfde (in gebruik en waarde) als kid . Dit is echter een verouderde claim die alleen wordt ingediend in v1.0 id_tokens voor compatibiliteitsdoeleinden.

Nettoladingclaims

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

Claim Indeling Beschrijving
aud Tekenreeks, een APP ID GUID Identificeert de beoogde ontvanger van het token. In is de doelgroep de toepassings-id van uw id_tokens app, die is toegewezen aan uw app in de Azure Portal. Deze waarde moet worden gevalideerd. Het token moet worden geweigerd als het niet voldoet aan de toepassings-id van uw app.
iss Tekenreeks, een URI van de vergever Identificeert de verlener of 'autorisatieserver' die het token maakt en retourneert. Ook wordt de Azure AD-tenant geïdentificeerd waarvoor de gebruiker is geverifieerd. Als het token is uitgegeven door het v2.0-eindpunt, eindigt de URI op /v2.0 . De GUID die aangeeft dat de gebruiker een consumentgebruiker van een Microsoft-account 9188040d-6c67-4c5b-b112-36a304b66dad is. 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 'Uitgegeven om' geeft aan wanneer de verificatie voor dit 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 claim vergever, tenzij het gebruikersaccount zich niet in dezelfde tenant als de vergever -gasten, bijvoorbeeld. Als de claim niet aanwezig is, betekent dit dat de waarde iss van in plaats daarvan kan worden gebruikt. Voor persoonlijke accounts die worden gebruikt in een organisatiecontext (bijvoorbeeld een persoonlijk account dat is uitgenodigd voor een Azure AD-tenant), kan de idp claim 'live.com' zijn of een STS-URI met de Microsoft-account-tenant. 9188040d-6c67-4c5b-b112-36a304b66dad
nbf int, een UNIX-tijdstempel De "nbf" (niet vóór) claim identificeert de tijd voordat de JWT NIET mag worden geaccepteerd voor verwerking.
exp int, een UNIX-tijdstempel De claim exp (vervaltijd) identificeert de vervaltijd op of waarna de JWT NIET mag worden geaccepteerd voor verwerking. Het is belangrijk te weten dat in bepaalde omstandigheden een resource het token vóór deze tijd kan afwijzen. Bijvoorbeeld als er een wijziging in de verificatie is vereist of als er een token is intrekken.
c_hash Tekenreeks De code-hash is alleen opgenomen in id-tokens wanneer het id-token is uitgegeven met een OAuth 2.0-autorisatiecode. Het kan worden gebruikt om de echtheid van een autorisatiecode te valideren. Zie de specificatie van de OpenID Connect voor meer OpenID Connect validatie.
at_hash Tekenreeks De hash van het toegangstoken is alleen opgenomen in id-tokens wanneer het id-token is uitgegeven vanaf het eindpunt met een /authorize OAuth 2.0-toegangstoken. Het kan worden gebruikt om de echtheid van een toegangs token te valideren. Zie de specificatie van de OpenID Connect voor meer OpenID Connect validatie. Dit wordt niet geretourneerd op id-tokens van /token het eindpunt.
aio Ondoorzichtige tekenreeks Een interne claim die door Azure AD wordt gebruikt om gegevens vast te stellen voor hergebruik van token. Moet worden genegeerd.
preferred_username Tekenreeks 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 een periode veranderen. Omdat deze waarde kan worden gewijzigd, moet deze niet worden gebruikt om autorisatiebeslissingen te nemen. Het profile bereik is vereist om deze claim te ontvangen.
email Tekenreeks De email claim is standaard aanwezig voor gastaccounts met een e-mailadres. Uw app kan de e-mailclaim aanvragen voor beheerde gebruikers (die afkomstig zijn van dezelfde tenant als de resource) met behulp van de email optionele claim. Op het v2.0-eindpunt kan uw app ook het OpenID Connect-bereik aanvragen. U hoeft niet zowel de optionele claim als het bereik aan te vragen om de claim op te email halen. De e-mailclaim ondersteunt alleen adresseerbare e-mail uit de profielgegevens van de gebruiker.
name Tekenreeks De name claim biedt een door mensen leesbare waarde die het onderwerp van het token identificeert. De waarde is niet gegarandeerd uniek, kan worden gewijzigd en is ontworpen om alleen te worden gebruikt voor weergavedoeleinden. Het profile bereik is vereist om deze claim te ontvangen.
nonce Tekenreeks De nonce komt overeen met de parameter die is opgenomen in de oorspronkelijke /autoriseringsaanvraag voor de IDP. Als deze niet overeenkomen, moet uw toepassing het token afwijzen.
oid Tekenreeks, een GUID De onveranderbare id voor een object in het Microsoft-identiteitssysteem, in dit geval een gebruikersaccount. Deze id identificeert de gebruiker op unieke manier in toepassingen: twee verschillende toepassingen die zich bij dezelfde gebruiker aanmelden, ontvangen dezelfde waarde in de oid claim. De Microsoft Graph retourneren deze id als id de eigenschap voor een bepaald gebruikersaccount. Omdat met oid meerdere apps gebruikers kunnen worden gecorreleerd, is het bereik vereist om deze claim te profile ontvangen. Houd er rekening mee dat als één gebruiker in meerdere tenants bestaat, de gebruiker een andere object-id in elke tenant bevat. Ze worden beschouwd als verschillende accounts, zelfs als de gebruiker zich met dezelfde referenties bij elk account aanmeldt. De oid claim is een GUID en kan niet opnieuw worden gebruikt.
roles Matrix van tekenreeksen De set rollen die zijn toegewezen aan de gebruiker die zich wil aanmelden.
rh Ondoorzichtige tekenreeks Een interne claim die door Azure wordt gebruikt om tokens opnieuw tevalideren. Moet worden genegeerd.
sub Tekenreeks De principal waarover het token informatie bevestigt, zoals de gebruiker van een app. Deze waarde is onveranderbaar en kan niet opnieuw worden toegewezen of hergebruikt. Het onderwerp is een pairwise-id: deze is uniek voor een bepaalde toepassings-id. Als één gebruiker zich met twee verschillende client-ID's bij twee verschillende apps meldt, ontvangen deze apps twee verschillende waarden voor de onderwerpclaim. Dit kan al dan niet worden gezocht, afhankelijk van uw architectuur en privacyvereisten.
tid Tekenreeks, een GUID Een GUID die de Azure AD-tenant vertegenwoordigt waar de gebruiker vandaan komt. Voor werk- en schoolaccounts is de GUID de onveranderbare tenant-id van de organisatie waar de gebruiker bij hoort. Voor persoonlijke accounts is de waarde 9188040d-6c67-4c5b-b112-36a304b66dad . Het profile bereik is vereist om deze claim te ontvangen.
unique_name Tekenreeks Biedt een voor mensen leesbare waarde waarmee het onderwerp van het token wordt geïdentificeerd. Deze waarde is op elk moment uniek, maar omdat e-mailberichten en andere id's opnieuw kunnen worden gebruikt, kan deze waarde opnieuw worden gebruikt voor andere accounts. Daarom mag de waarde alleen worden gebruikt voor weergavedoeleinden. Alleen uitgegeven in v1.0 id_tokens .
uti Ondoorzichtige tekenreeks Een interne claim die door Azure wordt gebruikt om tokens opnieuw tevalideren. Moet worden genegeerd.
ver Tekenreeks, 1.0 of 2.0 Geeft de versie van de id_token.
hasgroups Booleaans Als de gebruiker aanwezig is, altijd waar, maakt de gebruiker er ten minste één groep van. Wordt gebruikt in plaats van de groepenclaim voor JWT's in impliciete toekenningsstromen als de claim voor volledige groepen het URI-fragment zou uitbreiden tot buiten de URL-lengtelimieten (momenteel 6 of meer groepen). Geeft aan dat de client de api voor Microsoft Graph 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 hierboven), maar die nog steeds te groot zijn voor het token, wordt een koppeling naar de volledige lijst met groepen voor de hasgroups 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 Claim voor uitval van groepen voor meer informatie.

Claims gebruiken om een gebruiker betrouwbaar te identificeren (onderwerp- en object-id)

Bij het identificeren van een gebruiker (bijvoorbeeld wanneer u deze opzoekt in een database of besluit welke machtigingen ze hebben), is het essentieel om informatie te gebruiken die constant en uniek blijft in de tijd. Oudere toepassingen gebruiken soms velden zoals het e-mailadres, een telefoonnummer of de UPN. Al deze kunnen in de tijd veranderen en kunnen ook in de tijd opnieuw worden gebruikt. Bijvoorbeeld wanneer een werknemer de naam wijzigt of een werknemer een e-mailadres krijgt dat overeenkomt met dat van een vorige, niet langer aanwezig werknemer is. Daarom is het essentieel dat uw toepassing geen door mensen leesbare gegevens gebruikt om een gebruiker te identificeren. Door mensen te lezen betekent dit meestal dat iemand deze leest en deze wil wijzigen. Gebruik in plaats daarvan de claims die worden geleverd door de OIDC-standaard of de uitbreidingsclaims die door Microsoft worden geleverd- de sub claims en oid .

Als u gegevens per gebruiker op de juiste manier wilt opslaan, gebruikt u of alleen (die guid's uniek zijn), met gebruikt voor routering of sub oid tid sharding, indien nodig. Als u gegevens wilt delen tussen services, is het beste omdat alle apps dezelfde en oid + tid claims voor een bepaalde oid gebruiker tid krijgen. De sub claim in het Microsoft Identity Platform is 'paarsgewijs'. Deze is uniek op basis van een combinatie van de ontvanger, tenant en gebruiker van het token. Daarom ontvangen twee apps die id-tokens voor een bepaalde gebruiker aanvragen verschillende sub claims, maar dezelfde oid claims voor die gebruiker.

Notitie

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

Gastscenario's, waarbij een gebruiker zich in de ene tenant thuis heeft en zich in een andere tenant verifieert, moet de gebruiker behandelen alsof deze een nieuwe gebruiker van de service is. Uw documenten en bevoegdheden in de Contoso-tenant mogen niet van toepassing zijn in de Fabrikam-tenant. Dit is belangrijk om onbedoelde gegevenslekken tussen tenants te voorkomen.

Claim voor uitval van groepen

Om ervoor te zorgen dat de tokengrootte de groottelimieten van de HTTP-header niet overschrijdt, beperkt Azure AD het aantal object-ID's dat de token in de groups claim bevat. Als een gebruiker lid is van meer groepen dan de limiet voor uitval (150 voor SAML-tokens, 200 voor JWT-tokens), stuurt Azure AD de claim groepen niet in het token. In plaats daarvan bevat het een uitvalclaim in het token dat de toepassing aangeeft 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]"
        }
       }
     }
  ...
}

Levensduur van id-token

Een id-token is standaard één uur geldig. Na één uur moet de client een nieuw id-token verkrijgen.

U kunt de levensduur van een id-token aanpassen om te bepalen hoe vaak de clienttoepassing de toepassingssessie verloopt en hoe vaak het vereist dat de gebruiker zich op de stille of interactieve manier opnieuw moet verifiëren. Lees Configureerbare levensduur van token voor meer informatie.

Een id-token valideren

Het valideren van een id-token is vergelijkbaar met de eerste stap van het valideren van een toegangs token. Uw client kan controleren of er met het token is geknoeid. Ook kan de vergever worden gevalideerd om ervoor te zorgen dat de juiste vergever het token heeft teruggestuurd. Omdat id-tokens altijd een JWT-token zijn, bestaan er veel bibliotheken om deze tokens te valideren. We raden u aan een van deze tokens te gebruiken in plaats van dit zelf te doen. Houd er rekening mee dat alleen vertrouwelijke clients (clients met een geheim) id-tokens moeten valideren. Openbare toepassingen (code die volledig op een apparaat of netwerk wordt uitgevoerd en die u niet controleert, zoals de browser van een gebruiker of het thuisnetwerk), profiteren niet van het valideren van het id-token. Dit komt doordat een kwaadwillende gebruiker de sleutels kan onderscheppen en bewerken die worden gebruikt voor validatie van het token.

Zie de stappen voor het valideren van een toegangsken om het token handmatig te valideren. De volgende JWT-claims moeten worden gevalideerd in het id-token nadat de handtekening op het token is gevalideerd. Deze claims kunnen ook worden gevalideerd door uw tokenvalidatiebibliotheek:

  • Tijdstempels: de tijdstempels , en moeten allemaal vóór of na de huidige tijd iat nbf exp vallen, indien van toepassing.
  • Doelgroep: de aud claim moet overeenkomen met de app-id voor uw toepassing.
  • Nonce: de claim in de nettolading moet overeenkomen met de parameter nonce die tijdens de eerste aanvraag is doorgegeven aan het nonce /authorize-eindpunt.

Volgende stappen