toegangstokens Microsoft identity platform

Met toegangstokens kunnen clients veilig beveiligde web-API's aanroepen. Toegangstokens worden door web-API's gebruikt om verificatie en autorisatie uit te voeren.

Volgens de OAuth-specificatie zijn toegangstokens ondoorzichtige tekenreeksen zonder een ingestelde indeling. Sommige id-providers (IDP's) gebruiken GUID's en andere maken gebruik van versleutelde blobs. De indeling van het toegangstoken kan afhankelijk zijn van de wijze waarop de API die het token accepteert, is geconfigureerd.

Aangepaste API's die zijn geregistreerd door ontwikkelaars op de Microsoft identity platform kunnen kiezen uit twee verschillende indelingen van JSON-webtokens (JWT's) met de naam v1.0 en v2.0. Door Microsoft ontwikkelde API's, zoals Microsoft Graph of API's in Azure, hebben andere eigen tokenindelingen. Deze eigen indelingen kunnen versleutelde tokens, JWT's of speciale JWT-achtige tokens zijn die niet worden gevalideerd.

Clients moeten toegangstokens behandelen als ondoorzichtige tekenreeksen, omdat de inhoud van het token alleen voor de API is bedoeld. Alleen voor validatie- en foutopsporingsdoeleinden kunnen ontwikkelaars JWT's decoderen met behulp van een site zoals jwt.ms. Tokens die worden ontvangen voor een Microsoft-API zijn mogelijk niet altijd een JWT en kunnen niet altijd worden gedecodeerd.

Voor meer informatie over wat zich in het toegangstoken bevindt, moeten clients de antwoordgegevens van het token gebruiken die worden geretourneerd met het toegangstoken naar de client. Wanneer de client een toegangstoken aanvraagt, retourneert de Microsoft identity platform ook enkele metagegevens over het toegangstoken voor het gebruik van de toepassing. Deze informatie omvat de verlooptijd van het toegangstoken en de bereiken waarvoor het geldig is. Met deze gegevens kan de toepassing intelligente caching van toegangstokens uitvoeren zonder dat het toegangstoken zelf hoeft te worden geparseerd.

Zie de volgende secties voor meer informatie over hoe een API de claims in een toegangstoken kan valideren en gebruiken.

Notitie

Alle documentatie op deze pagina, behalve waar vermeld, is alleen van toepassing op tokens die zijn uitgegeven voor geregistreerde API's. Het is niet van toepassing op tokens die zijn uitgegeven voor API's die eigendom zijn van Microsoft. Deze tokens kunnen ook niet worden gebruikt om te valideren hoe de Microsoft identity platform tokens voor een geregistreerde API uitgeeft.

Tokenindelingen

Er zijn twee versies van toegangstokens beschikbaar in de Microsoft identity platform: v1.0 en v2.0. Deze versies bepalen de claims die zich in het token bevinden en zorgen ervoor dat een web-API de inhoud van het token kan beheren.

Web-API's hebben tijdens de registratie standaard een van de volgende versies geselecteerd:

  • v1.0 voor Azure AD toepassingen. In het volgende voorbeeld ziet u een v1.0-token (dit tokenvoorbeeld wordt niet gevalideerd omdat de sleutels zijn gedraaid vóór de publicatie en persoonlijke gegevens zijn verwijderd):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd
    
  • v2.0 voor toepassingen die ondersteuning bieden voor consumentenaccounts. In het volgende voorbeeld ziet u een v2.0-token (dit tokenvoorbeeld wordt niet gevalideerd omdat de sleutels zijn geroteerd vóór de publicatie en persoonlijke gegevens zijn verwijderd):

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt
    

De versie kan worden ingesteld voor toepassingen door de juiste waarde op te geven voor de accessTokenAcceptedVersion instelling in het app-manifest. De waarden van null en 1 resulteren in v1.0-tokens en de waarde van 2 resultaten in v2.0-tokens.

Tokeneigendom

Er zijn twee partijen betrokken bij een toegangstokenaanvraag: de client, die het token aanvraagt, en de resource (web-API) die het token accepteert. De aud claim in een token geeft de resource aan waarvoor het token is bedoeld (de doelgroep). Clients gebruiken het token, maar moeten het niet begrijpen of proberen te parseren. Resources accepteren het token.

De Microsoft identity platform ondersteunt het uitgeven van een tokenversie vanaf een versie-eindpunt. Ze zijn niet gerelateerd. Wanneer accessTokenAcceptedVersion is ingesteld op 2, ontvangt een client die het v1.0-eindpunt aanroept om een token voor die resource op te halen een v2.0-toegangstoken.

Resources zijn altijd eigenaar van hun tokens met behulp van de aud claim en zijn de enige toepassingen die hun tokendetails kunnen wijzigen.

Claims in toegangstokens

JWT's zijn onderverdeeld in drie delen:

  • Header : bevat informatie over het valideren van het token, inclusief informatie over het type token en hoe het is ondertekend.
  • 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 Base64 gecodeerd.

Claims zijn alleen aanwezig als er een waarde bestaat om deze te vullen. Een toepassing mag niet afhankelijk zijn van een claim die aanwezig is. Voorbeelden hiervan zijn pwd_exp (niet elke tenant vereist dat wachtwoorden verlopen) en family_name (clientreferentiestromen zijn namens toepassingen die geen namen hebben). Claims die worden gebruikt voor validatie van toegangstokens zijn altijd aanwezig.

Sommige claims worden gebruikt om de Microsoft identity platform tokens te beveiligen voor hergebruik. Deze claims zijn gemarkeerd als niet voor openbaar gebruik in de beschrijving als Opaque. Deze claims kunnen al dan niet worden weergegeven in een token en nieuwe kunnen zonder kennisgeving worden toegevoegd.

Headerclaims

Claim Indeling Beschrijving
typ Tekenreeks - altijd JWT Geeft aan dat het token een JWT is.
alg Tekenreeks Geeft het algoritme aan dat is gebruikt om het token te ondertekenen, RS256bijvoorbeeld .
kid Tekenreeks Hiermee geeft u de vingerafdruk op voor de openbare sleutel die kan worden gebruikt om deze handtekening van het token te valideren. Verzonden in zowel v1.0- als v2.0-toegangstokens.
x5t Tekenreeks 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 Indeling Beschrijving
aud Tekenreeks, een toepassings-id-URI of GUID Identificeert de beoogde doelgroep van het token. De API moet deze waarde valideren en het token afwijzen als de waarde niet overeenkomt. 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.
iss Tekenreeks, een STS-URI (Security Token Service) Identificeert de STS die het token maakt en retourneert, en de Azure AD tenant waarin de gebruiker is geverifieerd. Als het uitgegeven token een v2.0-token is (zie de ver claim), eindigt de URI op /v2.0. De GUID die aangeeft dat de gebruiker een consumentgebruiker van een Microsoft-account is, 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 claim Issuer, tenzij het gebruikersaccount zich niet in dezelfde tenant bevindt als de verlener, zoals gasten. Als de claim niet aanwezig is, kan in plaats daarvan de waarde van iss 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' of een STS-URI zijn die de Microsoft-accounttenant 9188040d-6c67-4c5b-b112-36a304b66dadbevat.
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 het tijdstip op waarvoor de JWT niet moet worden geaccepteerd voor verwerking.
exp int, een Unix-tijdstempel Hiermee geeft u de verlooptijd op of waarna de JWT niet mag worden geaccepteerd voor verwerking. Een resource kan het token ook vóór deze tijd weigeren. De afwijzing kan optreden wanneer een wijziging in de verificatie is vereist of wanneer een tokenintrekking is gedetecteerd.
aio Ondoorzichtige tekenreeks Een interne claim die door Azure AD wordt gebruikt om gegevens vast te leggen voor hergebruik van tokens. Resources mogen deze claim niet gebruiken.
acr Tekenreeks, een 0 of 1, alleen aanwezig in v1.0-tokens Een waarde van 0 voor de claim 'Verificatiecontextklasse' geeft aan dat de verificatie van de eindgebruiker niet voldoet aan de vereisten van ISO/IEC 29115.
amr JSON-matrix met tekenreeksen, alleen aanwezig in v1.0-tokens Hiermee wordt aangegeven hoe het onderwerp van het token is geverifieerd.
appid Tekenreeks, een GUID, alleen aanwezig in v1.0-tokens De toepassings-id van de client die het token gebruikt. De toepassing kan optreden als zichzelf of namens een gebruiker. De toepassings-id vertegenwoordigt doorgaans een toepassingsobject, maar kan ook een service-principal-object in Azure AD vertegenwoordigen.
azp Tekenreeks, een GUID, alleen aanwezig in v2.0-tokens Een vervanging voor appid. De toepassings-id van de client die het token gebruikt. De toepassing kan optreden als zichzelf of namens een gebruiker. De toepassings-id vertegenwoordigt doorgaans een toepassingsobject, maar kan ook een service-principal-object in Azure AD vertegenwoordigen.
appidacr Tekenreeks, a 01, of 2, alleen aanwezig in v1.0-tokens Geeft aan hoe de client is geverifieerd. Voor een openbare client is 0de waarde . Als client-id en clientgeheim worden gebruikt, is 1de waarde . Als een clientcertificaat is gebruikt voor verificatie, is 2de waarde .
azpacr Tekenreeks, a 0, 1of 2, alleen aanwezig in v2.0-tokens Een vervanging voor appidacr. Geeft aan hoe de client is geverifieerd. Voor een openbare client is 0de waarde . Als client-id en clientgeheim worden gebruikt, is 1de waarde . Als een clientcertificaat is gebruikt voor verificatie, is 2de 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 zonder een opgegeven indeling zijn. De waarde is veranderlijk en kan na verloop van tijd veranderen. Omdat de waarde veranderlijk is, mag deze niet worden gebruikt om autorisatiebeslissingen te nemen. De waarde kan echter worden gebruikt voor hints voor gebruikersnaam en in een door mensen leesbare gebruikersinterface als een gebruikersnaam. Het profile bereik is vereist om deze claim te ontvangen.
name Tekenreeks Biedt een door mensen leesbare waarde die het onderwerp van het token identificeert. De waarde is niet gegarandeerd uniek, is veranderlijk en wordt alleen gebruikt voor weergavedoeleinden. Het profile bereik is vereist om deze claim te ontvangen.
scp Tekenreeks, een door spaties gescheiden lijst met bereiken De set bereiken die worden weergegeven door de toepassing waarvoor de clienttoepassing toestemming heeft aangevraagd (en ontvangen). 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. Alleen opgenomen voor gebruikerstokens.
roles Matrix van tekenreeksen, een lijst met machtigingen De set machtigingen die beschikbaar worden gesteld door de toepassing waarvoor de aanvragende toepassing of gebruiker toestemming heeft gekregen om aan te roepen. Voor toepassingstokens wordt deze set machtigingen gebruikt tijdens de clientreferentiestroom in plaats van gebruikersbereiken. Voor gebruikerstokens wordt deze set waarden ingevuld met de rollen waaraan de gebruiker is toegewezen in de doeltoepassing.
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 Azure AD ingebouwde rollen. Deze claim wordt per toepassing geconfigureerd via de groupMembershipClaims eigenschap van het toepassingsmanifest. instellen op All of DirectoryRole is vereist. Mogelijk niet aanwezig in tokens die zijn verkregen via de impliciete stroom vanwege problemen met de tokenlengte.
groups JSON-matrix met GUID's Biedt object-id's die de groepslidmaatschappen van het onderwerp vertegenwoordigen. Deze waarden zijn uniek en kunnen veilig worden gebruikt voor het beheren van toegang, zoals het afdwingen van autorisatie voor toegang tot een resource. De groepen die zijn opgenomen in de groepsclaim, worden per toepassing geconfigureerd via de groupMembershipClaims eigenschap van het toepassingsmanifest. Een waarde van null sluit alle groepen uit, een waarde van bevat alleen Lidmaatschappen van SecurityGroup Active Directory-beveiligingsgroepen en een waarde van All bevat zowel beveiligingsgroepen als Microsoft 365-distributielijsten.

Zie de hasgroups claim voor meer informatie over het gebruik van de groups claim met de impliciete toekenning. Als voor andere stromen het aantal groepen waarin de gebruiker zich bevindt, hoger is dan 150 voor SAML en 200 voor JWT, voegt Azure AD een overschrijdingsclaim toe aan de claimbronnen. De claimbronnen verwijzen naar het Microsoft Graph-eindpunt dat de lijst met groepen voor de gebruiker bevat.
hasgroups Booleaans Indien aanwezig, altijd true, geeft aan of de gebruiker zich in ten minste één groep bevindt. Wordt gebruikt in plaats van de groups claim voor JWT's in impliciete toekenningsstromen als de claim voor volledige groepen het URI-fragment uitbreidt tot buiten de URL-lengtelimieten (momenteel zes of meer groepen). 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 Voor tokenaanvragen die niet beperkt zijn (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" }
sub Tekenreeks De principal waarover het token informatie bevestigt, zoals de gebruiker van een toepassing. Deze waarde is onveranderbaar en kan niet opnieuw worden toegewezen of opnieuw worden gebruikt. Het kan worden gebruikt om autorisatiecontroles veilig uit te voeren, bijvoorbeeld wanneer het token wordt gebruikt voor toegang tot een resource, en kan worden gebruikt als een sleutel in databasetabellen. Omdat het onderwerp altijd aanwezig is in de tokens die Azure AD problemen, gebruikt u deze waarde in een autorisatiesysteem voor algemeen gebruik. Het onderwerp is echter een paarsgewijze id die uniek is voor een bepaalde toepassings-id. Als één gebruiker zich aanmeldt bij twee verschillende toepassingen met behulp van twee verschillende client-id's, ontvangen deze toepassingen twee verschillende waarden voor de onderwerpclaim. Afhankelijk van de architectuur en privacyvereisten kunnen twee verschillende waarden al dan niet gewenst zijn. Zie ook de oid claim (die hetzelfde blijft voor alle toepassingen binnen een tenant).
oid Tekenreeks, een GUID De onveranderbare id voor de aanvrager, de gebruiker of service-principal waarvan de identiteit is geverifieerd. Het kan ook worden gebruikt om autorisatiecontroles veilig en als sleutel in databasetabellen uit te voeren. Deze id identificeert de aanvrager uniek in alle toepassingen. Twee verschillende toepassingen die zich aanmelden bij dezelfde gebruiker, ontvangen dezelfde waarde in de oid claim. De 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 met oid meerdere toepassingen principals kunnen worden gecorreleerd, is het profile bereik vereist om deze claim voor gebruikers te ontvangen. Als één gebruiker in meerdere tenants bestaat, bevat de gebruiker een andere object-id in elke tenant. De accounts worden als verschillend beschouwd, ook al meldt de gebruiker zich bij elk account aan met dezelfde referenties.
tid Tekenreeks, een GUID Vertegenwoordigt de tenant waarbij de gebruiker zich aanmeldt. Voor werk- en schoolaccounts is de GUID de onveranderbare tenant-id van de organisatie waarbij de gebruiker zich aanmeldt. Voor aanmeldingen bij de persoonlijke Microsoft-accounttenant (services zoals Xbox, Teams for Life of Outlook) is 9188040d-6c67-4c5b-b112-36a304b66dadde waarde . Als u deze claim wilt ontvangen, moet de toepassing het profile bereik aanvragen.
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 is niet gegarandeerd uniek binnen een tenant en mag alleen worden gebruikt voor weergavedoeleinden.
uti Tekenreeks Claim voor token-id, gelijk aan jti in de JWT-specificatie. Unieke, per-token-id die hoofdlettergevoelig is.
rh Ondoorzichtige tekenreeks Een interne claim die door Azure wordt gebruikt om tokens opnieuw te valideren. Resources mogen deze claim niet gebruiken.
ver Tekenreeks, of 1.02.0 Geeft de versie van het toegangstoken aan.

Groepsoverschrijdingsclaim

Azure AD beperkt het aantal object-id's dat wordt opgenomen in de groepsclaim om binnen de groottelimiet 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 en slechts 6 als deze worden uitgegeven met behulp van de impliciete stroom), verzendt Azure AD de groepsclaim niet in het token. In plaats daarvan bevat het een overschrijdingsclaim in het token die aangeeft dat de toepassing een query moet uitvoeren 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 in de map Scripts voor het maken van apps om overschrijdingsscenario's te testen.

v1.0-basisclaims

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

Claim Indeling Beschrijving
ipaddr Tekenreeks Het IP-adres van waaruit de gebruiker is geverifieerd.
onprem_sid Tekenreeks, in SID-indeling In gevallen waarin de gebruiker een on-premises verificatie heeft, biedt deze claim hun 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 Tekenreeks Een URL waar gebruikers naartoe kunnen worden gestuurd om hun wachtwoord opnieuw in te stellen.
in_corp booleaans Geeft aan of de client zich aanmeldt vanuit het bedrijfsnetwerk. Als dat niet het geval is, wordt de claim niet opgenomen.
nickname Tekenreeks Een andere naam voor de gebruiker, gescheiden van de voor- of achternaam.
family_name Tekenreeks Geeft de achternaam, achternaam of familienaam van de gebruiker op zoals gedefinieerd voor het gebruikersobject.
given_name Tekenreeks Geeft de eerste of opgegeven naam van de gebruiker op, zoals ingesteld voor het gebruikersobject.
upn Tekenreeks De gebruikersnaam van de gebruiker. Dit kan een telefoonnummer, e-mailadres of niet-opgemaakte tekenreeks zijn. Mag alleen worden gebruikt voor weergavedoeleinden en het verstrekken van hints voor gebruikersnaam in scenario's voor opnieuw verificatie.

amr-claim

Identiteiten kunnen op verschillende manieren worden geverifieerd, wat relevant kan zijn 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.

Waarde 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 aan of verificatie is uitgevoerd door een zelfondertekende JWT met een X509-certificaat dat eigendom is van de service.
otp Eenmalige wachtwoordcode met behulp van een e-mailbericht of een sms-bericht.
fed Er is een federatieve verificatieverklaring (zoals JWT of SAML) gebruikt.
wia Geïntegreerde Windows-verificatie
mfa Meervoudige verificatie is gebruikt. Wanneer deze claim aanwezig is, worden de andere verificatiemethoden opgenomen.
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 Er is geen verificatie uitgevoerd.

Levensduur van toegangstoken

De standaard levensduur van een toegangstoken is variabel. Bij uitgifte wordt aan de standaardlevensduur van een toegangstoken een willekeurige waarde toegewezen tussen 60 en 90 minuten (gemiddeld 75 minuten). De variatie verbetert de tolerantie van de service door de vraag naar toegangstokens over een bepaalde tijd te spreiden, waardoor pieken in het verkeer naar Azure AD per uur worden voorkomen.

Tenants die geen gebruik maken van voorwaardelijke toegang hebben een standaard levensduur van twee uur voor toegangstokens voor clients zoals Microsoft Teams en Microsoft 365.

De levensduur van een toegangstoken kan worden aangepast om te bepalen hoe vaak de clienttoepassing de toepassingssessie verloopt en hoe vaak de gebruiker zich opnieuw moet verifiëren (op de achtergrond of interactief). Als u de variatie van de standaardlevensduur van het toegangstoken wilt overschrijven, stelt u een statische standaardlevensduur van het toegangstoken in met behulp van Configureerbare levensduur van tokens (CTL).

De standaardvariatie van de levensduur van tokens wordt toegepast op organisaties waarvoor CONTINUE toegangsevaluatie (CAE) is ingeschakeld. De standaardvariatie van de levensduur van tokens wordt toegepast, zelfs als de organisaties CTL-beleid gebruiken. De standaardtokenlevensduur voor de levensduur van tokens met een lange levensduur varieert van 20 tot 28 uur. Wanneer het toegangstoken verloopt, moet de client het vernieuwingstoken gebruiken om op de achtergrond een nieuw vernieuwingstoken en toegangstoken te verkrijgen.

Organisaties die gebruikmaken van de aanmeldingsfrequentie voor voorwaardelijke toegang (SIF) om af te dwingen hoe vaak aanmeldingen plaatsvinden, kunnen de standaardvariatie van de levensduur van toegangstokens niet overschrijven. Wanneer organisaties SIF gebruiken, is de tijd tussen referentieprompts voor een client de levensduur van het token dat varieert van 60 - 90 minuten plus het interval voor de aanmeldingsfrequentie.

Hier volgt een voorbeeld van hoe variatie in de levensduur van standaardtoken werkt met de aanmeldingsfrequentie. Stel dat een organisatie de aanmeldingsfrequentie elk uur instelt. Het werkelijke aanmeldingsinterval vindt plaats tussen 1 uur en 2,5 uur, omdat het token wordt uitgegeven met een levensduur tussen 60 en 90 minuten (vanwege variatie in de levensduur van tokens).

Als een gebruiker met een token met een levensduur van één uur een interactieve aanmelding uitvoert op 59 minuten (net voordat de aanmeldingsfrequentie wordt overschreden), wordt er geen referentieprompt weergegeven omdat de aanmelding onder de SIF-drempelwaarde ligt. Als een nieuw token wordt uitgegeven met een levensduur van 90 minuten, ziet de gebruiker nog anderhalf uur geen referentieprompt. Wanneer een stille verlenging van de levensduur van het token van 90 minuten wordt uitgevoerd, vereist Azure AD een referentieprompt omdat de totale sessielengte de instelling voor de aanmeldingsfrequentie van 1 uur heeft overschreden. In dit voorbeeld is het tijdsverschil tussen referentieprompts vanwege het SIF-interval en de levensduur van het token 2,5 uur.

Tokens valideren

Niet alle toepassingen moeten tokens valideren. Alleen in specifieke scenario's moeten toepassingen een token valideren:

  • Web-API's moeten toegangstokens valideren die door een client naar hen worden verzonden. Ze mogen alleen tokens accepteren die hun aud claim bevatten.
  • Vertrouwelijke webtoepassingen zoals ASP.NET Core moeten id-tokens valideren die naar hen worden verzonden met behulp van de browser van de gebruiker in de hybride stroom, voordat toegang tot de gegevens van een gebruiker wordt toegestaan of een sessie tot stand wordt gebracht.

Als geen van de bovenstaande scenario's van toepassing is, profiteert de toepassing niet van het valideren van het token en kan dit een beveiligings- en betrouwbaarheidsrisico vormen als beslissingen worden genomen op basis van de geldigheid van het token. Openbare clients, zoals systeemeigen toepassingen of toepassingen met één pagina, profiteren niet van het valideren van tokens omdat de toepassing rechtstreeks communiceert met de IDP, waarbij SSL-beveiliging ervoor zorgt dat de tokens geldig zijn.

API's en webtoepassingen moeten alleen tokens valideren die een aud claim hebben die overeenkomt met de toepassing. Andere resources hebben mogelijk aangepaste regels voor tokenvalidatie. Tokens voor Microsoft Graph worden bijvoorbeeld niet gevalideerd volgens deze regels vanwege hun eigen indeling. Het valideren en accepteren van tokens die voor een andere resource zijn bedoeld, is een voorbeeld van het verwarrende deputy-probleem .

Als de toepassing een id-token of een toegangstoken moet valideren, moet eerst de handtekening van het token en de verlener worden gevalideerd op basis van de waarden in het OpenID-detectiedocument. De tenantonafhankelijke versie van het document bevindt zich bijvoorbeeld op https://login.microsoftonline.com/common/.well-known/openid-configuration.

De Azure AD middleware ingebouwde mogelijkheden heeft voor het valideren van toegangstokens. Zie voorbeelden om er een te vinden in de juiste taal. Er zijn ook verschillende opensource-bibliotheken van derden beschikbaar voor JWT-validatie. Zie de verificatiebibliotheken voor meer informatie over Azure AD verificatiebibliotheken en codevoorbeelden.

De handtekening valideren

Een JWT bevat drie segmenten, die worden gescheiden door het . teken. Het eerste segment wordt de koptekst genoemd, het tweede als de hoofdtekst en het derde als de handtekening. Het handtekeningsegment kan worden gebruikt om de echtheid van het token te valideren, zodat het kan worden vertrouwd door de toepassing.

Tokens die zijn uitgegeven door Azure AD zijn ondertekend met behulp van industriestandaard asymmetrische versleutelingsalgoritmen, zoals RS256. De header van de JWT bevat informatie over de sleutel en versleutelingsmethode die worden gebruikt om het token te ondertekenen:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

De alg claim geeft het algoritme aan dat is gebruikt om het token te ondertekenen, terwijl de kid claim de specifieke openbare sleutel aangeeft die is gebruikt om het token te valideren.

Op een bepaald moment kan Azure AD een id-token ondertekenen met behulp van een bepaalde set openbaar-persoonlijke sleutelparen. Azure AD de mogelijke set sleutels periodiek roteert, dus de toepassing moet worden geschreven om deze sleutelwijzigingen automatisch af te handelen. Een redelijke frequentie om te controleren op updates van de openbare sleutels die door Azure AD worden gebruikt, is elke 24 uur.

Verkrijg de ondertekeningssleutelgegevens die nodig zijn om de handtekening te valideren met behulp van het OpenID Connect-metagegevensdocument op:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tip

Probeer dit in een browser: URL

In de volgende informatie wordt het document met metagegevens beschreven:

  • Is een JSON-object dat verschillende nuttige stukjes informatie bevat, zoals de locatie van de verschillende eindpunten die vereist zijn voor het uitvoeren van OpenID Connect-verificatie.
  • Bevat een jwks_uri, waarmee de locatie wordt opgegeven van de set openbare sleutels die overeenkomen met de persoonlijke sleutels die worden gebruikt om tokens te ondertekenen. De JSON-websleutel (JWK) op de jwks_uri bevat alle openbare sleutelgegevens die op dat specifieke moment in gebruik zijn. De JWK-indeling wordt beschreven in RFC 7517. De toepassing kan de kid claim in de JWT-header gebruiken om de openbare sleutel uit dit document te selecteren, die overeenkomt met de persoonlijke sleutel die is gebruikt om een bepaald token te ondertekenen. Vervolgens kan handtekeningvalidatie worden uitgevoerd met behulp van de juiste openbare sleutel en het aangegeven algoritme.

Notitie

Gebruik de kid claim om het token te valideren. Hoewel v1.0-tokens zowel de x5tkid claims als bevatten, bevatten v2.0-tokens alleen de kid claim.

Het uitvoeren van handtekeningvalidatie valt buiten het bereik van dit document. Er zijn veel opensourcebibliotheken beschikbaar voor hulp bij het valideren van handtekeningen, indien nodig. De Microsoft identity platform heeft echter één uitbreiding voor tokenondertekening ten opzichte van de standaarden, namelijk aangepaste ondertekeningssleutels.

Als de toepassing aangepaste ondertekeningssleutels heeft als gevolg van het gebruik van de functie claimtoewijzing , voegt u een appid queryparameter toe die de toepassings-id bevat om een jwks_uri op te halen die verwijst naar de ondertekeningssleutelgegevens van de toepassing, die moeten worden gebruikt voor validatie. Bijvoorbeeld: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e bevat een jwks_uri van https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Autorisatie op basis van claims

De bedrijfslogica van de toepassing bepaalt autorisatie op basis van claims. Hieronder vindt u enkele algemene autorisatiemethoden.

Het token valideren

Gebruik de aud -claim om ervoor te zorgen dat de gebruiker de toepassing wil aanroepen. Als de id van de resource zich niet in de claim bevindt, wijst u deze aud af.

Gebruikersmachtiging valideren

Gebruik de roles claims en wids om te controleren of de gebruiker gemachtigd is om de API aan te roepen. Een beheerder kan bijvoorbeeld gemachtigd zijn om naar de API te schrijven, maar niet een normale gebruiker. Controleer of de tid binnenkant van het token overeenkomt met de tenant-id die wordt gebruikt om de gegevens op te slaan in de API.

Wanneer een gebruiker gegevens opslaat in de API van één tenant, moet deze zich opnieuw aanmelden bij die tenant om toegang te krijgen tot die gegevens. Sta nooit toe dat gegevens in de ene tenant vanuit een andere tenant worden geopend.

Gebruik de amr claim om te controleren of de gebruiker MFA heeft uitgevoerd. Het afdwingen van MFA wordt uitgevoerd met behulp van voorwaardelijke toegang. Als roles of groups claims worden aangevraagd in het toegangstoken, controleert u of de gebruiker zich in de groep bevindt die deze actie mag uitvoeren.

Voor tokens die worden opgehaald met behulp van de impliciete stroom, voert u een query uit op microsoft Graph voor deze gegevens, omdat deze vaak te groot zijn om in het token te passen.

Gebruik email of upn claim geen waarden om te bepalen of de gebruiker in een toegangstoken toegang moet hebben tot gegevens. Veranderlijke claimwaarden zoals deze kunnen na verloop van tijd veranderen, waardoor ze onveilig en onbetrouwbaar worden voor autorisatie.

Gebruik onveranderbare claimwaarden tid en sub of oid als een gecombineerde sleutel om de gegevens van de API uniek te identificeren en te bepalen of een gebruiker toegang tot die gegevens moet krijgen.

  • Goede: tid + sub
  • Beter: tid + oid de oid is consistent in alle toepassingen, zodat een ecosysteem van toepassingen gebruikerstoegang tot gegevens kan controleren.

Gebruik geen veranderlijke, door mensen leesbare id's zoals email of upn voor unieke identificatiegegevens.

Aanmelding van toepassing valideren

  • Gebruik de scp claim om te controleren of de gebruiker de aanroepende app toestemming heeft gegeven om uw API aan te roepen.
  • Zorg ervoor dat de aanroepende client uw API mag aanroepen met behulp van de appid claim (voor v1.0-tokens) of de azp claim (voor v2.0-tokens).
    • U hoeft deze claims (appid, azp) alleen te valideren als u wilt beperken dat uw web-API alleen wordt aangeroepen door vooraf bepaalde toepassingen (bijvoorbeeld Line-Of-Business-toepassingen of web-API's die worden aangeroepen door bekende front-ends). API's die zijn bedoeld om toegang toe te staan vanuit elke aanroepende toepassing, hoeven deze claims niet te valideren.

Tokens voor gebruikers en toepassingen

Een toepassing kan tokens ontvangen voor een gebruiker of rechtstreeks van een toepassing via de clientreferentiestroom. Deze alleen-app-tokens geven aan dat deze aanroep afkomstig is van een toepassing en dat er geen gebruiker achter staat. Deze tokens worden grotendeels op dezelfde manier verwerkt:

  • Gebruik roles om machtigingen weer te geven die zijn verleend aan het onderwerp van het token.
  • Gebruik oid of sub om te controleren of de aanroepende service-principal de verwachte is.

Als de toepassing onderscheid moet maken tussen alleen-app-toegangstokens en toegangstokens voor gebruikers, gebruikt u de idtypoptionele claim. Als u alleen-app-toegangstokens wilt detecteren, voegt u de idtyp claim toe aan het accessToken veld en controleert u op de waarde app. Id-tokens en toegangstokens voor gebruikers hebben de idtyp claim niet opgenomen.

Token intrekken

Vernieuwingstokens kunnen op elk gewenst moment ongeldig worden gemaakt of ingetrokken, om verschillende redenen. De redenen vallen in de categorieën van time-outs en intrekkingen.

Time-outs van tokens

Wanneer een organisatie de levensduur van tokens gebruikt, kan de levensduur van vernieuwingstokens worden gewijzigd. Naar verwachting kunnen sommige tokens zonder gebruik worden gebruikt. De gebruiker opent de toepassing bijvoorbeeld drie maanden niet en vervolgens verloopt het token. Toepassingen kunnen scenario's tegenkomen waarin de aanmeldingsserver een vernieuwingstoken weigert vanwege de leeftijd.

  • MaxInactiveTime: als het vernieuwingstoken niet is gebruikt binnen de tijd die wordt bepaald door de MaxInactiveTime, is het vernieuwingstoken niet meer geldig.
  • MaxSessionAge: als MaxAgeSessionMultiFactor of MaxAgeSessionSingleFactor zijn ingesteld op iets anders dan de standaardinstelling (totdat ze zijn ingetrokken), is opnieuw verificatie vereist nadat de tijd die is ingesteld in maxAgeSession* is verstreken. Voorbeelden:
    • De tenant heeft een MaxInactiveTime van vijf dagen en de gebruiker is een week op vakantie geweest. Daarom heeft Azure AD al zeven dagen geen nieuwe tokenaanvraag van de gebruiker gezien. De volgende keer dat de gebruiker een nieuw token aanvraagt, ziet deze dat het vernieuwingstoken is ingetrokken en moet de gebruiker zijn referenties opnieuw invoeren.
    • Een gevoelige toepassing heeft een MaxAgeSessionSingleFactor van één dag. Als een gebruiker zich op maandag en dinsdag aanmeldt (nadat de 25 uur zijn verstreken), moet deze zich opnieuw verifiëren.

Tokenintrekkingen

Vernieuwingstokens kunnen door de server worden ingetrokken vanwege een wijziging in referenties, of vanwege een gebruiks- of beheeractie. Vernieuwingstokens bevinden zich in de klassen vertrouwelijke clients en openbare clients.

Wijziging Cookie op basis van een wachtwoord Op wachtwoorden gebaseerd token Niet-op wachtwoorden gebaseerde cookie Token dat niet op een wachtwoord is gebaseerd Vertrouwelijk clienttoken
Wachtwoord verloopt Blijft in leven Blijft in leven Blijft in leven Blijft in leven Blijft in leven
Wachtwoord gewijzigd door gebruiker Revoked Revoked Blijft in leven Blijft in leven Blijft in leven
Gebruiker voert SSPR uit Revoked Revoked Blijft in leven Blijft in leven Blijft in leven
Beheer stelt het wachtwoord opnieuw in Revoked Revoked Blijft in leven Blijft in leven Blijft in leven
Gebruiker trekt de vernieuwingstokens in met behulp van PowerShell Revoked Revoked Revoked Revoked Revoked
Beheer trekt alle vernieuwingstokens voor een gebruiker in met behulp van PowerShell Revoked Revoked Revoked Revoked Revoked
Eenmalige afmelding op internet Revoked Blijft in leven Revoked Blijft in leven Blijft in leven

Niet op basis van een wachtwoord

Een aanmelding die niet op een wachtwoord is gebaseerd , is een aanmelding waarbij de gebruiker geen wachtwoord heeft getypt om het te verkrijgen. Voorbeelden van aanmeldingen die niet op een wachtwoord zijn gebaseerd, zijn:

  • Uw gezicht gebruiken met Windows Hello
  • FIDO2-sleutel
  • Sms
  • Spraak
  • PIN

Zie Primaire vernieuwingstokens voor meer informatie.

Volgende stappen