Microsoft identity platform en OAuth 2.0-autorisatiecodestroom
Met het toekenningstype OAuth 2.0-autorisatiecode of verificatiecodestroom kan een clienttoepassing geautoriseerde toegang verkrijgen tot beveiligde resources, zoals web-API's. Voor de verificatiecodestroom is een gebruikersagent vereist die omleiding vanaf de autorisatieserver (het Microsoft Identity Platform) weer naar uw toepassing ondersteunt. Een webbrowser, desktop of mobiele toepassing die wordt beheerd door een gebruiker om zich aan te melden bij uw app en toegang te krijgen tot hun gegevens.
In dit artikel worden protocoldetails op laag niveau beschreven die alleen vereist zijn bij het handmatig maken en uitgeven van onbewerkte HTTP-aanvragen om de stroom uit te voeren. Dit wordt afgeraden . Gebruik in plaats daarvan een door Microsoft gebouwde en ondersteunde verificatiebibliotheek om beveiligingstokens op te halen en beveiligde web-API's aan te roepen in uw apps.
Toepassingen die ondersteuning bieden voor de verificatiecodestroom
Gebruik de verificatiecodestroom die is gekoppeld aan Proof Key for Code Exchange (PKCE) en OpenID Verbinding maken (OIDC) om toegangstokens en id-tokens op te halen in deze typen apps:
- Webtoepassing met één pagina (SPA)
- Standaardwebtoepassing (servergebaseerde)
- Desktop- en mobiele apps
Protocoldetails
De OAuth 2.0-autorisatiecodestroom wordt beschreven in sectie 4.1 van de OAuth 2.0-specificatie. Apps die de OAuth 2.0-autorisatiecodestroom gebruiken, verkrijgen een access_token om op te nemen in aanvragen voor resources die worden beveiligd door het Microsoft Identity Platform (meestal API's). Apps kunnen ook nieuwe id's en toegangstokens aanvragen voor eerder geverifieerde entiteiten met behulp van een vernieuwingsmechanisme.
In dit diagram ziet u een weergave op hoog niveau van de verificatiestroom:
Omleidings-URI's voor apps met één pagina (SPA's)
Omleidings-URI's voor SPA's die gebruikmaken van de verificatiecodestroom, vereisen speciale configuratie.
- Voeg een omleidings-URI toe die ondersteuning biedt voor de verificatiecodestroom met PKCE en CORS (Cross-Origin Resource Sharing): volg de stappen in omleidings-URI: MSAL.js 2.0 met de verificatiecodestroom.
- Een omleidings-URI bijwerken: stel de omleidings-URI's
typespain met behulp van de manifesteditor van de toepassing in het Microsoft Entra-beheercentrum.
Het spa omleidingstype is compatibel met eerdere versies met de impliciete stroom. Apps die momenteel de impliciete stroom gebruiken om tokens op te halen, kunnen zonder problemen worden verplaatst naar het spa type omleidings-URI en de impliciete stroom blijven gebruiken.
Als u de autorisatiecodestroom probeert te gebruiken zonder CORS in te stellen voor uw omleidings-URI, ziet u deze fout in de console:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Zo ja, ga naar uw app-registratie en werk de omleidings-URI voor uw app bij om het spa type te gebruiken.
Toepassingen kunnen geen omleidings-URI gebruiken spa met niet-BEVEILIGD-WACHTWOORDVERIFICATIE-stromen, bijvoorbeeld systeemeigen toepassingen of clientreferentiestromen. Om beveiliging en best practices te garanderen, retourneert het Microsoft Identity Platform een fout als u een spa omleidings-URI zonder header Origin probeert te gebruiken. Op dezelfde manier voorkomt het Microsoft Identity Platform ook het gebruik van clientreferenties in alle stromen in aanwezigheid van een Origin header, om ervoor te zorgen dat geheimen niet worden gebruikt vanuit de browser.
Een autorisatiecode aanvragen
De autorisatiecodestroom begint met de client die de gebruiker naar het /authorize eindpunt leidt. In deze aanvraag vraagt de client de openid, offline_accessen https://graph.microsoft.com/mail.read machtigingen van de gebruiker aan.
Sommige machtigingen zijn beperkt door beheerders, bijvoorbeeld het schrijven van gegevens naar de adreslijst van een organisatie met behulp van Directory.ReadWrite.All. Als uw toepassing toegang vraagt tot een van deze machtigingen van een organisatiegebruiker, ontvangt de gebruiker een foutbericht met de mededeling dat deze niet gemachtigd is om toestemming te geven voor de machtigingen van uw app. Als u toegang wilt aanvragen tot bereiken met beheerdersbeperking, moet u deze rechtstreeks aanvragen vanuit een globale Beheer istrator. Zie Beheer-beperkte machtigingen voor meer informatie.
Tenzij anders is opgegeven, zijn er geen standaardwaarden voor optionele parameters. Er is echter standaardgedrag voor een aanvraag die optionele parameters weglaat. Het standaardgedrag is om de enige huidige gebruiker aan te melden, de accountkiezer weer te geven als er meerdere gebruikers zijn of om de aanmeldingspagina weer te geven als er geen gebruikers zijn aangemeld.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parameter | Vereist/optioneel | Description |
|---|---|---|
tenant |
vereist | De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. Geldige waarden zijn common, organizationsen consumerstenant-id's. Voor gastscenario's waarbij u een gebruiker van de ene tenant in een andere tenant ondertekent, moet u de tenant-id opgeven om ze aan te melden bij de resourcetenant. Zie Eindpunten voor meer informatie. |
client_id |
vereist | De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties ervaring toegewezen aan uw app. |
response_type |
vereist | Moet worden opgenomen code voor de autorisatiecodestroom. Kan ook de hybride stroom opnemen id_token of token gebruiken. |
redirect_uri |
vereist | De redirect_uri app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in de portal, behalve dat deze URL-gecodeerd moet zijn. Gebruik voor systeemeigen en mobiele apps een van de aanbevolen waarden: https://login.microsoftonline.com/common/oauth2/nativeclient voor apps die ingesloten browsers gebruiken of http://localhost voor apps die systeembrowsers gebruiken. |
scope |
vereist | Een door spaties gescheiden lijst met bereiken waaraan u de gebruiker toestemming wilt geven. Voor het /authorize been van de aanvraag kan deze parameter meerdere resources omvatten. Met deze waarde kan uw app toestemming krijgen voor meerdere web-API's die u wilt aanroepen. |
response_mode |
aanbevolen | Hiermee geeft u op hoe het identiteitsplatform het aangevraagde token naar uw app moet retourneren. Ondersteunde waarden: - query: Standaard bij het aanvragen van een toegangstoken. Geeft de code als een queryreeksparameter op uw omleidings-URI. De query parameter wordt niet ondersteund bij het aanvragen van een id-token met behulp van de impliciete stroom. - fragment: Standaard bij het aanvragen van een id-token met behulp van de impliciete stroom. Ook ondersteund als u alleen een code aanvraagt.- form_post: voert een POST uit die de code bevat naar uw omleidings-URI. Ondersteund bij het aanvragen van een code. |
state |
aanbevolen | Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in de tokenreactie. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt voor om aanvallen van aanvraagvervalsing op meerdere sites te voorkomen. De waarde kan ook informatie coderen over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden. Het kan bijvoorbeeld de pagina coderen of weergeven waarop ze waren ingeschakeld. |
prompt |
optioneel | Geeft het type gebruikersinteractie aan dat vereist is. Geldige waarden zijnlogin, none, en select_accountconsent.- prompt=login dwingt de gebruiker om zijn referenties op die aanvraag in te voeren, waardoor eenmalige aanmelding wordt genegeerd.- prompt=none is het tegenovergestelde. Het zorgt ervoor dat de gebruiker geen interactieve prompt wordt weergegeven. Als de aanvraag niet op de achtergrond kan worden voltooid met behulp van eenmalige aanmelding, retourneert het Microsoft Identity Platform een interaction_required fout.- prompt=consent activeert het dialoogvenster OAuth-toestemming nadat de gebruiker zich heeft aangemeld en vraagt de gebruiker machtigingen te verlenen aan de app.- prompt=select_account onderbreekt eenmalige aanmelding die accountselectieervaring biedt, waarbij alle accounts in een sessie of een onthouden account worden vermeld of een optie om een ander account helemaal te gebruiken. |
login_hint |
optioneel | U kunt deze parameter gebruiken om de gebruikersnaam en het e-mailadresveld van de aanmeldingspagina voor de gebruiker vooraf in te vullen. Apps kunnen deze parameter gebruiken tijdens opnieuw verificatie, nadat de login_hintoptionele claim al is geëxtraheerd uit een eerdere aanmelding. |
domain_hint |
optioneel | Indien opgenomen, slaat de app het detectieproces op basis van e-mail over dat de gebruiker doorloopt op de aanmeldingspagina, wat leidt tot een iets gestroomlijndere gebruikerservaring. U kunt ze bijvoorbeeld verzenden naar hun federatieve id-provider. Apps kunnen deze parameter gebruiken tijdens opnieuw verificatie door de tid uit een vorige aanmelding te extraheren. |
code_challenge |
aanbevolen/vereist | Wordt gebruikt om autorisatiecode te beveiligen met behulp van Proof Key for Code Exchange (PKCE). Vereist indien code_challenge_method is inbegrepen. Zie de PKCE RFC voor meer informatie. Deze parameter wordt nu aanbevolen voor alle toepassingstypen, zowel openbare als vertrouwelijke clients, en vereist door het Microsoft Identity Platform voor apps met één pagina met behulp van de autorisatiecodestroom. |
code_challenge_method |
aanbevolen/vereist | De methode die wordt gebruikt om de code_verifier voor de code_challenge-parameter te coderen. Dit moet zijn S256, maar de specificatie staat het gebruik toe van plain als de client SHA256 niet kan ondersteunen. Indien uitgesloten, wordt ervan uitgegaan dat code_challenge niet-versleutelde tekst is als code_challenge is opgenomen. Het Microsoft Identity Platform ondersteunt zowel plain als S256. Zie de PKCE RFC voor meer informatie. Deze parameter is vereist voor apps met één pagina met behulp van de autorisatiecodestroom. |
Op dit moment wordt de gebruiker gevraagd om zijn referenties in te voeren en de verificatie te voltooien. Het Microsoft Identity Platform zorgt er ook voor dat de gebruiker toestemming heeft gegeven voor de machtigingen die zijn aangegeven in de scope queryparameter. Als de gebruiker geen toestemming heeft gegeven voor een van deze machtigingen, wordt de gebruiker gevraagd om toestemming te geven voor de vereiste machtigingen. Bekijk voor meer informatie Machtigingen en toestemming in het eindpunt van het Microsoft Identity-platform.
Zodra de gebruiker zich verifieert en toestemming verleent, retourneert het Microsoft Identity Platform een antwoord op uw app op de aangegeven redirect_uri, met behulp van de methode die is opgegeven in de response_mode parameter.
Succesvolle respons
In dit voorbeeld ziet u een geslaagd antwoord met behulp van response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parameter | Description |
|---|---|
code |
De authorization_code-app die door de app is aangevraagd. De app kan de autorisatiecode gebruiken om een toegangstoken aan te vragen voor de doelresource. Autorisatiecodes zijn kortlevend. Normaal gesproken verlopen ze na ongeveer 10 minuten. |
state |
Als een state-parameter is opgenomen in de aanvraag, zou dezelfde waarde moeten verschijnen in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn. |
U kunt ook een id-token ontvangen als u een aanvraag indient en de impliciete toekenning hebt ingeschakeld in uw toepassingsregistratie. Dit gedrag wordt soms de hybride stroom genoemd. Het wordt gebruikt door frameworks zoals ASP.NET.
Foutrespons
Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de app ze op de juiste wijze kan verwerken:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Description |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. Dit deel van de fout wordt opgegeven, zodat de app op de juiste wijze kan reageren op de fout, maar legt niet uitgebreid uit waarom er een fout is opgetreden. |
error_description |
Een specifiek foutbericht waarmee een ontwikkelaar de oorzaak van een verificatiefout kan identificeren. Dit deel van de fout bevat de meeste nuttige informatie over waarom de fout is opgetreden. |
Foutcodes voor autorisatie-eindpuntfouten
In de volgende tabel worden de verschillende foutcodes beschreven die kunnen worden geretourneerd in de error-parameter van het foutbericht.
| Foutcode | Beschrijving | Clientactie |
|---|---|---|
invalid_request |
Protocolfout, zoals een ontbrekende, vereiste parameter. | Herstel de aanvraag en dien ze opnieuw in. Deze fout is een ontwikkelingsfout die doorgaans is opgetreden tijdens de eerste test. |
unauthorized_client |
De clienttoepassing is niet toegestaan om een autorisatiecode aan te vragen. | Deze fout treedt meestal op wanneer de clienttoepassing niet is geregistreerd in Microsoft Entra-id of niet wordt toegevoegd aan de Microsoft Entra-tenant van de gebruiker. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Microsoft Entra ID. |
access_denied |
Toestemming door resource-eigenaar geweigerd | De clienttoepassing kan de gebruiker waarschuwen dat deze niet kan doorgaan, tenzij de gebruiker toestemming geeft. |
unsupported_response_type |
De autorisatieserver biedt geen ondersteuning voor het antwoordtype in de aanvraag. | Herstel de aanvraag en dien ze opnieuw in. Deze fout is een ontwikkelingsfout die doorgaans is opgetreden tijdens de eerste test. In de hybride stroom geeft deze fout aan dat u de impliciete toekenningsinstelling voor het id-token moet inschakelen voor de registratie van de client-app. |
server_error |
Er is een onverwachte fout opgetreden op de server. | Probeer de aanvraag opnieuw. Deze fouten kunnen worden veroorzaakt door tijdelijke voorwaarden. De clienttoepassing kan de gebruiker uitleggen dat het antwoord ervan is vertraagd op een tijdelijke fout. |
temporarily_unavailable |
De server is tijdelijk te druk om de aanvraag te verwerken. | Probeer de aanvraag opnieuw. De clienttoepassing kan de gebruiker uitleggen dat de reactie is vertraagd vanwege een tijdelijke toestand. |
invalid_resource |
De doelresource is ongeldig omdat deze niet bestaat, microsoft Entra-id kan deze niet vinden of niet juist is geconfigureerd. | Deze fout geeft aan dat de resource, als deze bestaat, niet is geconfigureerd in de tenant. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Microsoft Entra ID. |
login_required |
Te veel of geen gebruikers gevonden. | De client heeft stille verificatie aangevraagd (prompt=none), maar er is geen enkele gebruiker gevonden. Deze fout kan betekenen dat er meerdere gebruikers actief zijn in de sessie of dat er geen gebruikers zijn. Deze fout houdt rekening met de gekozen tenant. Als er bijvoorbeeld twee Microsoft Entra-accounts actief en één Microsoft-account zijn en consumers is gekozen, werkt stille verificatie. |
interaction_required |
Voor de aanvraag is gebruikersinteractie vereist. | Er is een andere verificatiestap of -toestemming vereist. Probeer de aanvraag opnieuw zonder prompt=none. |
Een id-token aanvragen of een hybride stroom
Als u wilt weten wie de gebruiker is voordat u een autorisatiecode inwisselt, is het gebruikelijk dat toepassingen ook een id-token aanvragen wanneer ze de autorisatiecode aanvragen. Deze benadering wordt de hybride stroom genoemd omdat deze OIDC combineert met de OAuth2-autorisatiecodestroom.
De hybride stroom wordt vaak gebruikt in web-apps om een pagina voor een gebruiker weer te geven zonder dat deze wordt geblokkeerd bij het inwisselen van code, met name in ASP.NET. Zowel apps met één pagina als traditionele web-apps profiteren van verminderde latentie in dit model.
De hybride stroom is hetzelfde als de autorisatiecodestroom die eerder is beschreven, maar met drie toevoegingen. Al deze toevoegingen zijn vereist om een id-token aan te vragen: nieuwe bereiken, een nieuwe response_type en een nieuwe nonce queryparameter.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parameter bijgewerkt | Vereist/optioneel | Description |
|---|---|---|
response_type |
vereist | De toevoeging van id_token geeft aan de server aan dat de toepassing een id-token in het antwoord van het /authorize eindpunt wil. |
scope |
vereist | Voor id-tokens moet deze parameter worden bijgewerkt om de id-tokenbereiken op te nemen: openid en optioneel profile en email. |
nonce |
vereist | Een waarde die is opgenomen in de aanvraag, gegenereerd door de app, die wordt opgenomen in de resulterende id_token als een claim. De app kan deze waarde vervolgens verifiëren om aanvallen waarbij tokens worden herhaald te beperken. De waarde is doorgaans een gerandomiseerde, unieke tekenreeks die kan worden gebruikt om de oorsprong van de aanvraag te identificeren. |
response_mode |
aanbevolen | Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. De standaardwaarde is query voor slechts een autorisatiecode, maar fragment als de aanvraag een id_tokenresponse_type zoals opgegeven in de OpenID-specificatie bevat. We raden aan om apps te gebruiken form_post, met name bij gebruik http://localhost als omleidings-URI. |
Het gebruik als fragment reactiemodus veroorzaakt problemen voor web-apps die de code van de omleiding lezen. Browsers geven het fragment niet door aan de webserver. In deze situaties moeten apps de form_post reactiemodus gebruiken om ervoor te zorgen dat alle gegevens naar de server worden verzonden.
Succesvolle respons
In dit voorbeeld ziet u een geslaagd antwoord met behulp van response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Parameter | Description |
|---|---|
code |
De autorisatiecode die de app heeft aangevraagd. De app kan de autorisatiecode gebruiken om een toegangstoken aan te vragen voor de doelresource. Autorisatiecodes zijn kortlevend, meestal verlopen na ongeveer 10 minuten. |
id_token |
Een id-token voor de gebruiker, uitgegeven met behulp van de impliciete toekenning. Bevat een speciale c_hash claim die de hash is van de code in dezelfde aanvraag. |
state |
Als een state-parameter is opgenomen in de aanvraag, zou dezelfde waarde moeten verschijnen in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn. |
Een code inwisselen voor een toegangstoken
Alle vertrouwelijke clients kunnen kiezen uit clientgeheimen of certificaatreferenties. Symmetrische gedeelde geheimen worden gegenereerd door het Microsoft Identity Platform. Certificaatreferenties zijn asymmetrische sleutels die zijn geüpload door de ontwikkelaar. Zie de referenties van het Microsoft Identity Platform-toepassingsverificatiecertificaat voor meer informatie.
Voor de beste beveiliging raden we u aan om certificaatreferenties te gebruiken. Openbare clients, waaronder systeemeigen toepassingen en apps met één pagina, mogen geen geheimen of certificaten gebruiken bij het inwisselen van een autorisatiecode. Zorg er altijd voor dat uw omleidings-URI's het type toepassing bevatten en uniek zijn.
Een toegangstoken aanvragen met een client_secret
Nu u een authorization_code machtiging hebt verkregen en bent verleend door de gebruiker, kunt u het code voor een access_token resource inwisselen. Wissel de code in door een POST aanvraag naar het /token eindpunt te verzenden:
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=204196ef-b7fd-461f-89b7-f778e1568c41
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Parameter | Vereist/optioneel | Description |
|---|---|---|
tenant |
vereist | De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. Geldige waarden zijn common, organizationsen consumerstenant-id's. Zie Eindpunten voor meer informatie. |
client_id |
vereist | De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties pagina toegewezen aan uw app. |
scope |
optioneel | Een door spaties gescheiden lijst van bereiken. De bereiken moeten allemaal afkomstig zijn van één resource, samen met OIDC-bereiken (profile, openid, email). Bekijk voor meer informatie Machtigingen en toestemming in het eindpunt van het Microsoft Identity-platform. Deze parameter is een Microsoft-extensie voor de autorisatiecodestroom, bedoeld om apps toe te staan de resource te declareren waarvoor ze het token willen inwisselen tijdens het inwisselen van tokens. |
code |
vereist | De authorization_code die u in het eerste deel van de stroom hebt verkregen. |
redirect_uri |
vereist | Dezelfde redirect_uri waarde die is gebruikt voor het verkrijgen van de authorization_code. |
grant_type |
vereist | Moet authorization_code zijn voor de autorisatiecodestroom. |
code_verifier |
aanbevolen | Hetzelfde code_verifier dat is gebruikt om de authorization_code te verkrijgen. Vereist als PKCE is gebruikt in de toekenningsaanvraag van de autorisatiecode. Zie de PKCE RFC voor meer informatie. |
client_secret |
vereist voor vertrouwelijke web-apps | Het toepassingsgeheim dat u hebt gemaakt in de app-registratieportal voor uw app. Gebruik het toepassingsgeheim niet in een systeemeigen app of app met één pagina, omdat een client_secret app niet betrouwbaar kan worden opgeslagen op apparaten of webpagina's. Het is vereist voor web-apps en web-API's, die de veilig op de client_secret server kunnen opslaan. Net als alle parameters hier moet het clientgeheim URL-gecodeerd zijn voordat het wordt verzonden. Deze stap wordt uitgevoerd door de SDK. Zie de algemene syntaxisspecificatie van URI's voor meer informatie over URI-codering. Het basispatroon voor verificatie, per RFC 6749 wordt ook ondersteund, in plaats van referenties opgeven in de autorisatieheader. |
Een toegangstoken aanvragen met een certificaatreferentie
POST /{tenant}/oauth2/v2.0/token HTTP/1.1 // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Parameter | Vereist/optioneel | Description |
|---|---|---|
tenant |
vereist | De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. Geldige waarden zijn common, organizationsen consumerstenant-id's. Zie Eindpunten voor meer informatie. |
client_id |
vereist | De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties pagina toegewezen aan uw app. |
scope |
optioneel | Een door spaties gescheiden lijst van bereiken. De bereiken moeten allemaal afkomstig zijn van één resource, samen met OIDC-bereiken (profile, openid, email). Zie machtigingen, toestemming en bereiken voor meer informatie. Deze parameter is een Microsoft-extensie voor de autorisatiecodestroom. Met deze extensie kunnen apps de resource declareren waarvoor ze het token willen inwisselen tijdens het inwisselen van tokens. |
code |
vereist | De authorization_code die u in het eerste deel van de stroom hebt verkregen. |
redirect_uri |
vereist | Dezelfde redirect_uri waarde die is gebruikt voor het verkrijgen van de authorization_code. |
grant_type |
vereist | Moet authorization_code zijn voor de autorisatiecodestroom. |
code_verifier |
aanbevolen | Hetzelfde code_verifier dat werd gebruikt om de authorization_code. Vereist als PKCE is gebruikt in de toekenningsaanvraag van de autorisatiecode. Zie de PKCE RFC voor meer informatie. |
client_assertion_type |
vereist voor vertrouwelijke web-apps | De waarde moet worden ingesteld om een certificaatreferentie te urn:ietf:params:oauth:client-assertion-type:jwt-bearer gebruiken. |
client_assertion |
vereist voor vertrouwelijke web-apps | Een assertie, een JSON-webtoken (JWT), die u moet maken en ondertekenen met het certificaat dat u hebt geregistreerd als referenties voor uw toepassing. Lees meer over certificaatreferenties voor meer informatie over het registreren van uw certificaat en de indeling van de assertie. |
De parameters zijn hetzelfde als de aanvraag door een gedeeld geheim, behalve dat de client_secret parameter wordt vervangen door twee parameters: a client_assertion_type en client_assertion.
Succesvolle respons
In dit voorbeeld ziet u een geslaagd tokenantwoord:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | Description |
|---|---|
access_token |
Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde resource, zoals een web-API. |
token_type |
Geeft de waarde van het tokentype aan. Het enige type dat door Microsoft Entra ID wordt ondersteund, is Bearer. |
expires_in |
Hoe lang het toegangstoken geldig is, in seconden. |
scope |
De bereiken waarvoor het access_token geldig is. Optioneel. Deze parameter is niet-standaard en, indien weggelaten, is het token voor de bereiken die zijn aangevraagd op het eerste been van de stroom. |
refresh_token |
Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om andere toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Vernieuwingstokens hebben een lange levensduur. Ze kunnen de toegang tot resources gedurende langere perioden behouden. Raadpleeg het toegangstoken vernieuwen verderop in dit artikel voor meer informatie over het vernieuwen van een toegangstoken . Opmerking: Alleen opgegeven als het bereik offline_access is aangevraagd. |
id_token |
Een JSON-webtoken. De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, en vertrouwelijke clients kunnen dit token gebruiken voor autorisatie. Zie de id_token reference voor meer informatie over id_tokens. Opmerking: Alleen opgegeven als het bereik openid is aangevraagd. |
Foutrespons
Dit voorbeeld is een foutreactie:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
"correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
| Parameter | Description |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee een ontwikkelaar de oorzaak van een verificatiefout kan identificeren. |
error_codes |
Een lijst met STS-specifieke foutcodes die kunnen helpen bij diagnostische gegevens. |
timestamp |
De tijd waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over onderdelen. |
Foutcodes voor tokeneindpuntfouten
| Foutcode | Beschrijving | Clientactie |
|---|---|---|
invalid_request |
Protocolfout, zoals een ontbrekende, vereiste parameter. | Herstel de aanvraag of app-registratie en verzend de aanvraag opnieuw. |
invalid_grant |
De autorisatiecode of PKCE-codeverificator is ongeldig of is verlopen. | Probeer een nieuwe aanvraag naar het /authorize eindpunt en controleer of de code_verifier parameter juist is. |
unauthorized_client |
De geverifieerde client is niet gemachtigd om dit autorisatietoestemmingstype te gebruiken. | Deze fout treedt meestal op wanneer de clienttoepassing niet is geregistreerd in Microsoft Entra-id of niet wordt toegevoegd aan de Microsoft Entra-tenant van de gebruiker. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Microsoft Entra ID. |
invalid_client |
De clientauthenticatie is mislukt. | De clientreferenties zijn niet geldig. De toepassing Beheer istrator werkt de referenties bij om dit probleem op te lossen. |
unsupported_grant_type |
De autorisatieserver biedt geen ondersteuning voor het autorisatietoestemmingstype. | Wijzig het toekenningstype in de aanvraag. Dit type fout mag alleen optreden tijdens de ontwikkeling en moet tijdens de eerste test worden gedetecteerd. |
invalid_resource |
De doelresource is ongeldig omdat deze niet bestaat, microsoft Entra-id kan deze niet vinden of niet juist is geconfigureerd. | Deze code geeft aan dat de resource, als deze bestaat, niet is geconfigureerd in de tenant. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Microsoft Entra ID. |
interaction_required |
Niet-standaard, omdat de OIDC-specificatie alleen voor deze code op het /authorize eindpunt aanroept. Voor de aanvraag is gebruikersinteractie vereist. Er is bijvoorbeeld een andere verificatiestap vereist. |
Voer de /authorize aanvraag opnieuw uit met dezelfde bereiken. |
temporarily_unavailable |
De server is tijdelijk te druk om de aanvraag te verwerken. | Voer de aanvraag na een kleine vertraging opnieuw uit. De clienttoepassing kan de gebruiker uitleggen dat de reactie is vertraagd vanwege een tijdelijke toestand. |
consent_required |
Voor de aanvraag is toestemming van de gebruiker vereist. Deze fout is niet standaard. Het wordt meestal alleen geretourneerd op het /authorize eindpunt per OIDC-specificaties. Geretourneerd toen een scope parameter werd gebruikt in de codewisselstroom die de client-app niet heeft gemachtigd om aan te vragen. |
De client moet de gebruiker terugsturen naar het /authorize eindpunt met het juiste bereik om toestemming te activeren. |
invalid_scope |
Het bereik dat door de app is aangevraagd, is ongeldig. | Werk de waarde van de scope parameter in de verificatieaanvraag bij naar een geldige waarde. |
Notitie
Apps met één pagina kunnen een invalid_request foutmelding krijgen die aangeeft dat het inwisselen van tokens voor meerdere pagina's alleen is toegestaan voor het clienttype 'Toepassing met één pagina'. Dit geeft aan dat de omleidings-URI die wordt gebruikt om het token aan te vragen, niet is gemarkeerd als een spa omleidings-URI. Bekijk de stappen voor toepassingsregistratie voor het inschakelen van deze stroom.
Het toegangstoken gebruiken
Nu u een token hebt verkregen access_token, kunt u het token gebruiken in aanvragen voor web-API's door het op te halen in de Authorization header:
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Het toegangstoken vernieuwen
Toegangstokens hebben een korte levensduur. Vernieuw ze nadat ze verlopen om toegang te blijven krijgen tot resources. U kunt dit doen door een andere POST aanvraag in te dienen bij het /token eindpunt. Geef de refresh_token in plaats van de code. Vernieuwingstokens zijn geldig voor alle machtigingen waarvoor uw client al toestemming heeft gekregen. Een vernieuwingstoken dat is uitgegeven op een aanvraag, scope=mail.read kan bijvoorbeeld worden gebruikt om een nieuw toegangstoken voor scope=api://contoso.com/api/UseResourceaan te vragen.
Vernieuwingstokens voor web-apps en systeemeigen apps hebben geen opgegeven levensduur. Normaal gesproken zijn de levensduur van vernieuwingstokens relatief lang. In sommige gevallen verlopen vernieuwingstokens echter, worden ingetrokken of ontbreken voldoende bevoegdheden voor de actie. Uw toepassing moet fouten verwachten en afhandelen die worden geretourneerd door het tokenuitgifte-eindpunt. Apps met één pagina krijgen een token met een levensduur van 24 uur, waarvoor elke dag een nieuwe verificatie is vereist. Deze actie kan op de achtergrond worden uitgevoerd in een iframe wanneer cookies van derden zijn ingeschakeld. Dit moet worden gedaan in een frame op het hoogste niveau, volledige paginanavigatie of een pop-upvenster, in browsers zonder cookies van derden, zoals Safari.
Vernieuwingstokens worden niet ingetrokken wanneer ze worden gebruikt om nieuwe toegangstokens te verkrijgen. U wordt verwacht het oude vernieuwingstoken te verwijderen. De OAuth 2.0-specificatie zegt: "De autorisatieserver kan een nieuw vernieuwingstoken uitgeven. In dat geval moet de client het oude vernieuwingstoken negeren en vervangen door het nieuwe vernieuwingstoken. De autorisatieserver kan het oude vernieuwingstoken intrekken na het uitgeven van een nieuw vernieuwingstoken aan de client.
Belangrijk
Voor vernieuwingstokens die zijn verzonden naar een omleidings-URI die is geregistreerd als spa, verloopt het vernieuwingstoken na 24 uur. Extra vernieuwingstokens die zijn verkregen met behulp van het initiële vernieuwingstoken, dragen die verlooptijd over, zodat apps moeten worden voorbereid om de autorisatiecodestroom opnieuw uit te voeren met behulp van een interactieve verificatie om elke 24 uur een nieuw vernieuwingstoken op te halen. Gebruikers hoeven hun referenties niet in te voeren en zien meestal niet eens een gebruikerservaring, maar alleen een nieuwe laad van uw toepassing. De browser moet de aanmeldingspagina in een frame op het hoogste niveau bezoeken om de aanmeldingssessie te kunnen zien. Dit komt door privacyfuncties in browsers die cookies van derden blokkeren.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Parameter | Type | Beschrijving |
|---|---|---|
tenant |
vereist | De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. Geldige waarden zijn common, organizationsen consumerstenant-id's. Zie Eindpunten voor meer informatie. |
client_id |
vereist | De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties ervaring toegewezen aan uw app. |
grant_type |
vereist | Moet voor dit deel van de autorisatiecodestroom zijn refresh_token . |
scope |
optioneel | Een door spaties gescheiden lijst van bereiken. De bereiken die in dit been zijn aangevraagd, moeten gelijk zijn aan of een subset van de bereiken die zijn aangevraagd in de oorspronkelijke authorization_code aanvraagfase. Als de bereiken die zijn opgegeven in deze aanvraag meerdere resourceservers omvatten, retourneert het Microsoft Identity Platform een token voor de resource die is opgegeven in het eerste bereik. Bekijk voor meer informatie Machtigingen en toestemming in het eindpunt van het Microsoft Identity-platform. |
refresh_token |
vereist | De refresh_token die u in het tweede deel van de stroom hebt verkregen. |
client_secret |
vereist voor web-apps | Het toepassingsgeheim dat u hebt gemaakt in de app-registratieportal voor uw app. Het mag niet worden gebruikt in een systeemeigen app, omdat een client_secret apparaat niet betrouwbaar kan worden opgeslagen op apparaten. Het is vereist voor web-apps en web-API's, die de veilig op de client_secret server kunnen opslaan. Dit geheim moet URL-gecodeerd zijn. Zie de algemene syntaxisspecificatie van de URI voor meer informatie. |
Succesvolle respons
In dit voorbeeld ziet u een geslaagd tokenantwoord:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | Description |
|---|---|
access_token |
Het aangevraagde toegangstoken. De app kan dit token gebruiken om te verifiëren bij de beveiligde resource, zoals een web-API. |
token_type |
Geeft de waarde van het tokentype aan. Het enige type dat door Microsoft Entra ID wordt ondersteund, is Bearer. |
expires_in |
Hoe lang het toegangstoken geldig is, in seconden. |
scope |
De bereiken waarvoor het access_token geldig is. |
refresh_token |
Een nieuw OAuth 2.0-vernieuwingstoken. Vervang het oude vernieuwingstoken door dit nieuw verkregen vernieuwingstoken om ervoor te zorgen dat uw vernieuwingstokens zo lang mogelijk geldig blijven. Opmerking: Alleen opgegeven als het bereik offline_access is aangevraagd. |
id_token |
Een niet-ondertekend JSON-webtoken. De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. Zie de Id-tokens van het Microsoft Identity Platform voor meer informatie.id_token Opmerking: Alleen opgegeven als het bereik openid is aangevraagd. |
Waarschuwing
Probeer geen tokens te valideren of te lezen voor een API waarvan u geen eigenaar bent, inclusief de tokens in dit voorbeeld, in uw code. Tokens voor Microsoft-services kunnen een speciale indeling gebruiken die niet wordt gevalideerd als een JWT, en kunnen ook worden versleuteld voor consumentengebruikers (Microsoft-account). Hoewel het lezen van tokens een handig hulpprogramma voor foutopsporing is en een leerfunctie heeft, hoeft u hier geen afhankelijkheden van te maken in uw code of uit te gaan van specifieke informatie over tokens die niet voor een API zijn die u beheert.
Foutrespons
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
"correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
| Parameter | Description |
|---|---|
error |
Een foutcodetekenreeks die kan worden gebruikt voor het classificeren van typen fouten en om te reageren op fouten. |
error_description |
Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren. |
error_codes |
Een lijst met STS-specifieke foutcodes die kunnen helpen bij diagnostische gegevens. |
timestamp |
De tijd waarop de fout is opgetreden. |
trace_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens. |
correlation_id |
Een unieke id voor de aanvraag die kan helpen bij diagnostische gegevens over onderdelen. |
Zie Error codes for token endpoint errors (Foutcodes voor tokeneindpuntfouten) voor een beschrijving van de foutcodes en de aanbevolen clientactie.
Volgende stappen
- Ga naar de MSAL JS-voorbeelden om aan de slag te gaan met coderen.
- Meer informatie over tokenuitwisselingsscenario's.