Verwijzing naar toegangstokenclaims

Artikel
10/24/2023

Toegangstokens zijn JSON-webtokens (JWT). JWT's bevatten de volgende onderdelen:

Header : bevat informatie over het valideren van het token, inclusief informatie over het type token en de bijbehorende ondertekeningsmethode.
Payload : bevat alle belangrijke gegevens over de gebruiker of toepassing die de service probeert aan te roepen.
Handtekening : is de grondstof die wordt gebruikt om het token te valideren.

Elk stuk wordt gescheiden door een punt (.) en afzonderlijk met Base 64 gecodeerd.

Claims zijn alleen aanwezig als er een waarde bestaat om deze in te vullen. Een toepassing mag geen afhankelijkheid nemen van een claim die aanwezig is. Voorbeelden hiervan zijn pwd_exp (niet voor elke tenant zijn wachtwoorden vereist om te verlopen) en family_name (clientreferentiestromen zijn namens toepassingen die geen namen hebben). Het toegangstoken bevat altijd voldoende claims voor toegangsevaluatie.

Het Microsoft Identity Platform gebruikt enkele claims om tokens te beveiligen voor hergebruik. De beschrijving van Opaque deze claims wordt gemarkeerd als niet voor openbaar gebruik. Deze claims worden al dan niet weergegeven in een token en nieuwe claims kunnen zonder kennisgeving worden toegevoegd.

Headerclaims

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

Nettoladingclaims

Claim	Opmaak	Beschrijving	Overwegingen voor autorisatie
`acrs`	JSON-matrix met tekenreeksen	Geeft de verificatiecontext-id's aan van de bewerkingen die de bearer in aanmerking komt om uit te voeren. Verificatiecontext-id's kunnen worden gebruikt om een vraag naar stapsgewijze verificatie vanuit uw toepassing en services te activeren. Vaak gebruikt samen met de `xms_cc` claim.
`aud`	Tekenreeks, een URI of GUID voor de toepassings-id	Identificeert de beoogde doelgroep van het token. In v2.0-tokens is deze waarde altijd de client-id van de API. In v1.0-tokens kan dit de client-id of de resource-URI zijn die in de aanvraag wordt gebruikt. De waarde kan afhankelijk zijn van de wijze waarop de client het token heeft aangevraagd.	Deze waarde moet worden gevalideerd, het token afwijzen als de waarde niet overeenkomt met de beoogde doelgroep.
`iss`	Tekenreeks, een STS-URI (Security Token Service)	Identificeert de STS die het token samenricht en retourneert, en de Microsoft Entra-tenant van de geverifieerde gebruiker. Als het uitgegeven token een v2.0-token is (zie de `ver` claim), 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`.	De toepassing kan het GUID-gedeelte van de claim gebruiken om de set tenants te beperken die zich kunnen aanmelden bij de toepassing, indien van toepassing.
`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, zoals gasten. Gebruik de waarde van `iss` als de claim niet aanwezig is. Voor persoonlijke accounts die worden gebruikt in een organisatiecontext (bijvoorbeeld een persoonlijk account dat is uitgenodigd voor een Microsoft Entra-tenant), kan de `idp` claim 'live.com' zijn of een STS-URI die de Tenant `9188040d-6c67-4c5b-b112-36a304b66dad`van het Microsoft-account bevat.
`iat`	int, een Unix-tijdstempel	Hiermee geeft u op wanneer de verificatie voor dit token heeft plaatsgevonden.
`nbf`	int, een Unix-tijdstempel	Hiermee geeft u de tijd waarna de JWT kan worden verwerkt.
`exp`	int, een Unix-tijdstempel	Hiermee geeft u de verlooptijd op waarna de JWT kan worden geaccepteerd voor verwerking. Een resource kan het token ook vóór deze tijd afwijzen. De afwijzing kan optreden voor een vereiste wijziging in de verificatie of wanneer een token wordt ingetrokken.
`aio`	Ondoorzichtige tekenreeks	Een interne claim die door Microsoft Entra-id wordt gebruikt om gegevens vast te leggen voor hergebruik van tokens. Resources mogen deze claim niet gebruiken.
`acr`	Tekenreeks, a `0` of `1`, alleen aanwezig in v1.0-tokens	Een waarde van `0` de claim Verificatiecontextklasse geeft aan dat de verificatie door eindgebruikers niet voldoet aan de vereisten van ISO/IEC 29115.
`amr`	JSON-matrix met tekenreeksen, alleen aanwezig in v1.0-tokens	Identificeert de verificatiemethode van het onderwerp van het token.
`appid`	Tekenreeks, een GUID, alleen aanwezig in v1.0-tokens	De toepassings-id van de client met behulp van het token. De toepassing kan fungeren als zichzelf of namens een gebruiker. De toepassings-id vertegenwoordigt doorgaans een toepassingsobject, maar kan ook een service-principalobject in Microsoft Entra-id vertegenwoordigen.	`appid` kan worden gebruikt bij autorisatiebeslissingen.
`azp`	Tekenreeks, een GUID, alleen aanwezig in v2.0-tokens	Een vervanging voor `appid`. De toepassings-id van de client met behulp van het token. De toepassing kan fungeren als zichzelf of namens een gebruiker. De toepassings-id vertegenwoordigt doorgaans een toepassingsobject, maar kan ook een service-principalobject in Microsoft Entra-id vertegenwoordigen.	`azp` kan worden gebruikt bij autorisatiebeslissingen.
`appidacr`	Tekenreeks, een `0`, `1`of `2`, alleen aanwezig in v1.0-tokens	Hiermee wordt de verificatiemethode van de client aangegeven. Voor een openbare client is `0`de waarde . Wanneer u de client-id en het clientgeheim gebruikt, is `1`de waarde . Wanneer u een clientcertificaat gebruikt voor verificatie, is `2`de waarde .
`azpacr`	Tekenreeks, een `0`, `1`of `2`, alleen aanwezig in v2.0-tokens	Een vervanging voor `appidacr`. Geeft de verificatiemethode van de client aan. Voor een openbare client is `0`de waarde . Wanneer u de client-id en het clientgeheim gebruikt, is `1`de waarde . Wanneer u een clientcertificaat gebruikt voor verificatie, is `2`de waarde .
`preferred_username`	Tekenreeks, alleen aanwezig in v2.0-tokens.	De primaire gebruikersnaam die de gebruiker vertegenwoordigt. De waarde kan een e-mailadres, telefoonnummer of een algemene gebruikersnaam zijn zonder een opgegeven indeling. Gebruik de waarde voor hints voor gebruikersnamen en in de door mensen leesbare gebruikersinterface als gebruikersnaam. Gebruik het `profile` bereik om deze claim te ontvangen.	Omdat deze waarde veranderlijk is, moet u deze niet gebruiken om autorisatiebeslissingen te nemen.
`name`	String	Biedt een door mensen leesbare waarde waarmee het onderwerp van het token wordt geïdentificeerd. De waarde kan variëren, kan worden gedempt en is alleen voor weergavedoeleinden. Gebruik het `profile` bereik om deze claim te ontvangen.	Gebruik deze waarde niet om autorisatiebeslissingen te nemen.
`scp`	Tekenreeks, een door spaties gescheiden lijst met bereiken	De set bereiken die beschikbaar worden gesteld door de toepassing waarvoor de clienttoepassing toestemming heeft aangevraagd (en ontvangen). Alleen opgenomen voor gebruikerstokens.	De toepassing moet controleren of deze bereiken geldig zijn die door de toepassing worden weergegeven en autorisatiebeslissingen nemen op basis van de waarde van deze bereiken.
`roles`	Matrix met tekenreeksen, een lijst met machtigingen	De set machtigingen die beschikbaar worden gesteld door de toepassing die de aanvragende toepassing of gebruiker heeft gekregen, is gemachtigd om aan te roepen. De clientreferentiestroom gebruikt deze set machtigingen in plaats van gebruikersbereiken voor toepassingstokens. Voor gebruikerstokens bevat deze set waarden de toegewezen rollen van de gebruiker in de doeltoepassing.	Deze waarden kunnen worden gebruikt voor het beheren van toegang, zoals het afdwingen van autorisatie voor toegang tot een resource.
`wids`	Matrix van RoleTemplateID-GUID's	Geeft de tenantbrede rollen aan die aan deze gebruiker zijn toegewezen, uit de sectie met rollen die aanwezig zijn in ingebouwde Microsoft Entra-rollen. De `groupMembershipClaims` eigenschap van het toepassingsmanifest configureert deze claim per toepassing. Stel de claim in op `All` of `DirectoryRole`.	Deze waarden kunnen worden gebruikt voor het beheren van toegang, zoals het afdwingen van autorisatie voor toegang tot een resource.
`groups`	JSON-matrix met GUID's	Biedt object-id's die de groepslidmaatschappen van het onderwerp vertegenwoordigen. De `groupMembershipClaims` eigenschap van het toepassingsmanifest configureert de groepsclaim per toepassing. Een waarde van uitsluiting van `null` alle groepen, een waarde van `SecurityGroup` directoryrollen en Active Directory-groepslidmaatschappen, en een waarde van `All` omvat zowel beveiligingsgroepen als Microsoft 365-distributielijsten. Als voor andere stromen het aantal groepen in de gebruiker meer dan 150 gaat voor SAML en 200 voor JWT, voegt Microsoft Entra ID een overschrijdingsclaim toe aan de claimbronnen. De claimbronnen verwijzen naar het Microsoft Graph-eindpunt dat de lijst met groepen voor de gebruiker bevat.	Deze waarden kunnen worden gebruikt voor het beheren van toegang, zoals het afdwingen van autorisatie voor toegang tot een resource.
`hasgroups`	Booleaanse waarde	Als deze aanwezig is, geeft u altijd `true`aan of de gebruiker zich in ten minste één groep bevindt. Geeft aan dat de client de Microsoft Graph API moet gebruiken om de groepen (`https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects`) van de gebruiker te bepalen.
`groups:src1`	JSON-object	Bevat een koppeling naar de lijst met volledige groepen voor de gebruiker wanneer tokenaanvragen te groot zijn voor het token. 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" }`
`sub`	String	De principal die aan het token is gekoppeld. Bijvoorbeeld de gebruiker van een toepassing. Deze waarde is onveranderbaar, wijs deze niet opnieuw toe of gebruik deze opnieuw. Het onderwerp is een paargewijze id die uniek is voor een bepaalde toepassings-id. Als één gebruiker zich aanmeldt bij twee verschillende toepassingen met twee verschillende client-id's, ontvangen deze toepassingen twee verschillende waarden voor de onderwerpclaim. Het gebruik van de twee verschillende waarden is afhankelijk van architectuur- en privacyvereisten. Zie ook de `oid` claim, die hetzelfde blijft voor alle toepassingen binnen een tenant.	Deze waarde kan worden gebruikt om autorisatiecontroles uit te voeren, zoals wanneer het token wordt gebruikt voor toegang tot een resource en kan worden gebruikt als een sleutel in databasetabellen.
`oid`	Tekenreeks, een GUID	De onveranderbare id voor de aanvrager, de geverifieerde identiteit van de gebruiker of service-principal. Deze id identificeert de aanvrager uniek in verschillende toepassingen. Twee verschillende toepassingen die zich aanmelden bij dezelfde gebruiker, ontvangen dezelfde waarde in de `oid` claim. Deze `oid` kan worden gebruikt bij het maken van query's naar Microsoft onlineservices, zoals Microsoft Graph. Microsoft Graph retourneert deze id als de `id` eigenschap voor een bepaald gebruikersaccount. Omdat meerdere `oid` toepassingen principals kunnen correleren, kan deze claim voor gebruikers het `profile` bereik gebruiken. Als er één gebruiker in meerdere tenants bestaat, bevat de gebruiker een andere object-id in elke tenant. Hoewel de gebruiker zich aanmeldt bij elk account met dezelfde referenties, zijn de accounts verschillend.	Deze waarde kan worden gebruikt om autorisatiecontroles uit te voeren, zoals wanneer het token wordt gebruikt voor toegang tot een resource en kan worden gebruikt als een sleutel in databasetabellen.
`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 . Om deze claim te ontvangen, moet de toepassing het `profile` bereik aanvragen.	Deze waarde moet worden beschouwd in combinatie met andere claims in autorisatiebeslissingen.
`unique_name`	Tekenreeks, alleen aanwezig in v1.0-tokens	Biedt een voor mensen leesbare waarde waarmee het onderwerp van het token wordt geïdentificeerd.	Deze waarde kan binnen een tenant verschillen en deze alleen gebruiken voor weergavedoeleinden.
`uti`	String	Token-id-claim, gelijk aan `jti` in de JWT-specificatie. Unieke, per token-id die hoofdlettergevoelig is.
`rh`	Ondoorzichtige tekenreeks	Een interne claim die wordt gebruikt door Azure om tokens opnieuw te valideren. Resources mogen deze claim niet gebruiken.
`ver`	Tekenreeks, of `1.02.0`	Geeft de versie van het toegangstoken aan.
`xms_cc`	JSON-matrix met tekenreeksen	Geeft aan of de clienttoepassing die het token heeft verkregen, in staat is om problemen met claims te verwerken. Het wordt vaak samen met claim `acrs`gebruikt. Deze claim wordt vaak gebruikt in scenario's voor voorwaardelijke toegang en continue toegangsevaluatie. De bronserver of servicetoepassing die het token wordt uitgegeven voor het beheren van de aanwezigheid van deze claim in een token. Een waarde van `cp1` het toegangstoken is de gezaghebbende manier om te bepalen dat een clienttoepassing een claimvraag kan afhandelen. Zie Claims-uitdagingen, claimsaanvragen en clientmogelijkheden voor meer informatie.

Notitie

De rolesclaims , groupsen scpwids claims zijn geen volledige lijst van de wijze waarop een resource een gebruiker of toepassing kan autoriseren, noch een volledige lijst met machtigingen die aan de aanroeper zijn verleend. De doelresource kan een andere methode gebruiken om toegang tot de beveiligde resources te autoriseren.

Overschrijdingsclaim voor groepen

Microsoft Entra ID beperkt het aantal object-id's dat deze bevat in de groepsclaim om binnen de maximale grootte van de HTTP-header te blijven. Als een gebruiker lid is van meer groepen dan de overschrijdingslimiet (150 voor SAML-tokens, 200 voor JWT-tokens), verzendt Microsoft Entra ID de groepsclaim niet 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]"
        }   
    }
    ...
}

Gebruik de BulkCreateGroups.ps1 opgegeven map Scripts voor het maken van apps om overschrijdingsscenario's te testen.

Notitie

De geretourneerde URL is een Azure AD Graph-URL (dat wil gezegd graph.windows.net). In plaats van te vertrouwen op deze URL, moeten services in plaats daarvan de idtyp optionele claim gebruiken (waarmee wordt aangegeven of het token een app- of app+gebruikerstoken is) om een Microsoft Graph-URL te maken voor het uitvoeren van een query op de volledige lijst met groepen.

v1.0 basisclaims

De v1.0-tokens bevatten de volgende claims, indien van toepassing, maar niet standaard v2.0-tokens. Als u deze claims voor v2.0 wilt gebruiken, vraagt de toepassing ze aan met optionele claims.

Claim	Opmaak	Beschrijving
`ipaddr`	String	Het IP-adres waaruit de gebruiker is geverifieerd.
`onprem_sid`	Tekenreeks, in SID-indeling	In gevallen waarin de gebruiker een on-premises verificatie heeft, biedt deze claim zijn SID. Gebruik deze claim voor autorisatie in verouderde toepassingen.
`pwd_exp`	int, een Unix-tijdstempel	Geeft aan wanneer het wachtwoord van de gebruiker verloopt.
`pwd_url`	String	Een URL waar gebruikers hun wachtwoord opnieuw kunnen instellen.
`in_corp`	boolean	Signalen als de client zich aanmeldt vanuit het bedrijfsnetwerk.
`nickname`	String	Een andere naam voor de gebruiker, gescheiden van voor- of achternaam.
`family_name`	String	Hiermee geeft u de achternaam, achternaam of familienaam van de gebruiker op zoals gedefinieerd voor het gebruikersobject.
`given_name`	String	Geeft de voor- of opgegeven naam van de gebruiker op, zoals ingesteld op het gebruikersobject.
`upn`	String	De gebruikersnaam van de gebruiker. Dit kan een telefoonnummer, e-mailadres of niet-opgemaakte tekenreeks zijn. Gebruik dit alleen voor weergavedoeleinden en het bieden van hints voor gebruikersnamen in scenario's voor opnieuw verificatie.

amr claim

Identiteiten kunnen op verschillende manieren worden geverifieerd, wat mogelijk relevant is voor de toepassing. De amr claim is een matrix die meerdere items kan bevatten, zoals ["mfa", "rsa", "pwd"]voor een verificatie die zowel een wachtwoord als de Authenticator-app heeft gebruikt.

Weergegeven als	Beschrijving
`pwd`	Wachtwoordverificatie, het Microsoft-wachtwoord van een gebruiker of een clientgeheim van een toepassing.
`rsa`	Verificatie is gebaseerd op het bewijs van een RSA-sleutel, bijvoorbeeld met de Microsoft Authenticator-app. Deze waarde geeft ook het gebruik aan van een zelfondertekende JWT met een X509-certificaat in serviceeigendom in verificatie.
`otp`	Eenmalige wachtwoordcode met behulp van een e-mailbericht of een sms-bericht.
`fed`	Hiermee wordt het gebruik van een federatieve verificatieverklaring (zoals JWT of SAML) aangegeven.
`wia`	Geïntegreerde Windows-verificatie
`mfa`	Geeft het gebruik van meervoudige verificatie aan. Bevat de andere verificatiemethoden wanneer deze claim aanwezig is.
`ngcmfa`	Gelijk aan `mfa`, gebruikt voor het inrichten van bepaalde geavanceerde referentietypen.
`wiaormfa`	De gebruiker heeft Windows of een MFA-referentie gebruikt om te verifiëren.
`none`	Geeft geen voltooide verificatie aan.

Volgende stappen

Meer informatie over de toegangstokens die worden gebruikt in Microsoft Entra ID.

Delen via