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. De verificatiecodestroom vereist een gebruikersagent die ondersteuning biedt voor omleiding vanaf de autorisatieserver (de Microsoft identity platform) terug naar uw toepassing. 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 doorgaans alleen nodig zijn bij het handmatig maken en uitgeven van onbewerkte HTTP-aanvragen om de stroom uit te voeren. Dit wordt niet aanbevolen. 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 Connect (OIDC) om toegangstokens en id-tokens in deze typen apps op te halen:

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 naar resources die worden beveiligd door de Microsoft identity platform (meestal API's). Apps kunnen ook nieuwe id- en toegangstokens aanvragen voor eerder geverifieerde entiteiten met behulp van een vernieuwingsmechanisme.

Tip

Probeer deze aanvraag uit te voeren in Postman
Probeer deze aanvraag uit te voeren en meer in Postman. Vergeet niet om tokens en id's te vervangen.

In dit diagram ziet u een weergave op hoog niveau van de verificatiestroom:

Diagram toont de OAuth-autorisatiecodestroom. Systeemeigen app en Web A P I werken met behulp van tokens zoals beschreven in dit artikel.

Omleidings-URI's voor apps met één pagina (SPA's)

Omleidings-URI's voor SPA's die gebruikmaken van de verificatiecodestroom, vereisen speciale configuratie.

Het spa omleidingstype is achterwaarts compatibel met de impliciete stroom. Apps die momenteel gebruikmaken van de impliciete stroom om tokens op te halen, kunnen zonder problemen naar het spa omleidings-URI-type worden verplaatst 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.

Als dit het probleem is, gaat u naar uw app-registratie en werkt u 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 de Microsoft identity platform een fout als u probeert een spa omleidings-URI te gebruiken zonder headerOrigin. Op dezelfde manier voorkomt de Microsoft identity platform ook het gebruik van clientreferenties in alle stromen in de aanwezigheid van een Origin header, om ervoor te zorgen dat geheimen niet vanuit de browser worden gebruikt.

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 bij een globale beheerder. 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 zich aan te melden bij de enige huidige gebruiker, 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Tip

Selecteer de onderstaande koppeling om deze aanvraag uit te voeren. Nadat u zich hebt aangemeld, moet uw browser worden omgeleid http://localhost/myapp/ naar een code adresbalk in de adresbalk. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parameter Vereist/optioneel 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. Voor gastscenario's waarbij u een gebruiker van de ene tenant ondertekent in een andere tenant, 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 de Azure Portal – App-registraties ervaring is toegewezen aan uw app.
response_type vereist Moet de autorisatiecodestroom bevatten code . 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 waarvoor de gebruiker toestemming moet 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. Biedt 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. Wordt 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 het tokenantwoord. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om vervalsingsaanvallen op meerdere sites te voorkomen. De waarde kan ook informatie over de status van de gebruiker in de app coderen voordat de verificatieaanvraag is opgetreden. Het kan bijvoorbeeld de pagina coderen of weergeven waarop ze zich bevonden.
prompt optioneel Geeft het type gebruikersinteractie aan dat vereist is. Geldige waarden zijn login, none, consent en select_account.

- 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 de 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 met accountselectieervaring met alle accounts in sessie of een onthouden account 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. Bijvoorbeeld door ze naar hun federatieve id-provider te verzenden. Apps kunnen deze parameter gebruiken tijdens opnieuw verificatie door de tid parameter uit een eerdere 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 inbegrepen. Zie de PKCE RFC voor meer informatie. Deze parameter wordt nu aanbevolen voor alle toepassingstypen, zowel openbare als vertrouwelijke clients, en vereist voor de 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_verifiercode_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, code_challenge wordt ervan uitgegaan dat deze tekst zonder opmaak is opgenomen code_challenge . De Microsoft identity platform ondersteunt zowel als plainS256. 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. De 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. Zie Machtigingen en toestemming in de Microsoft identity platform voor meer informatie.

Zodra de gebruiker toestemming heeft geverifieerd en toestemming verleent, retourneert de Microsoft identity platform een antwoord op uw app op de aangegeven redirect_urimanier met behulp van de methode die is opgegeven in de response_mode parameter.

Geslaagde reactie

In dit voorbeeld ziet u een geslaagd antwoord met behulp van response_mode=query:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Parameter Beschrijving
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 kort. Normaal gesproken verlopen ze na ongeveer 10 minuten.
state Als een state parameter is opgenomen in de aanvraag, moet dezelfde waarde worden weergegeven in het antwoord. 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 id-token aanvraagt en de impliciete toekenning hebt ingeschakeld in uw toepassingsregistratie. Dit gedrag wordt soms ook wel de hybride stroom genoemd. Het wordt gebruikt door frameworks zoals ASP.NET.

Foutreactie

Foutreacties kunnen ook naar de redirect_uri app worden verzonden, zodat ze op de juiste wijze kunnen worden verwerkt:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
Parameter Beschrijving
error Een tekenreeks met foutcodes die kan worden gebruikt om typen fouten te classificeren en om te reageren op fouten. Dit deel van de fout wordt opgegeven, zodat de app op de juiste manier op de fout kan reageren, maar legt niet uitvoerig 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. Corrireer de aanvraag en verzend deze opnieuw. Deze fout is een ontwikkelingsfout die doorgaans is opgetreden tijdens de eerste test.
unauthorized_client De clienttoepassing mag geen autorisatiecode aanvragen. Deze fout treedt meestal op wanneer de clienttoepassing niet is geregistreerd in Azure AD of niet wordt toegevoegd aan de Azure AD tenant van de gebruiker. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Azure AD.
access_denied Toestemming van resource-eigenaar geweigerd De clienttoepassing kan de gebruiker waarschuwen dat deze niet kan worden voortgezet, tenzij de gebruiker toestemming geeft.
unsupported_response_type De autorisatieserver biedt geen ondersteuning voor het antwoordtype in de aanvraag. Corrireer de aanvraag en verzend deze opnieuw. 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 af te handelen. Probeer de aanvraag opnieuw. De clienttoepassing kan de gebruiker uitleggen dat het antwoord wordt vertraagd vanwege een tijdelijke voorwaarde.
invalid_resource De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of omdat deze 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 Azure AD.
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 Azure AD accounts actief en één Microsoft-account zijn en consumers wordt 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 de impliciete toekenning combineert met de autorisatiecodestroom.

De hybride stroom wordt vaak gebruikt in web-apps om een pagina voor een gebruiker weer te geven zonder te blokkeren voor 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 eerder beschreven autorisatiecodestroom, 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 Beschrijving
response_type vereist De toevoeging aan id_token de server geeft 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 is opgenomen in de resulterende id_token claim. De app kan deze waarde vervolgens verifiëren om tokenherplayaanvallen 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 alleen voor een autorisatiecode, maar fragment als de aanvraag een id_tokenresponse_type zoals opgegeven in de OpenID-specificatie bevat. U wordt aangeraden apps te gebruiken form_post, vooral 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.

Geslaagde reactie

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 Beschrijving
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, wordt dezelfde waarde weergegeven in het antwoord. 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 de Microsoft identity platform. Certificaatreferenties zijn asymmetrische sleutels die door de ontwikkelaar zijn geüpload. Zie Microsoft identity platform certificaatreferenties voor toepassingsverificatie voor meer informatie.

Voor de beste beveiliging raden we u aan 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 deze code inwisselen voor een access_token resource. Wissel de code aanvraag 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
Parameter Vereist/optioneel 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 de Azure Portal - App-registraties pagina is toegewezen aan uw app.
scope optioneel Een door spaties gescheiden lijst met bereiken. De bereiken moeten allemaal afkomstig zijn van één resource, samen met OIDC-bereiken (profile, openid, ). email Zie machtigingen en toestemming in de Microsoft identity platform voor meer informatie. 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 redirect_uri Dezelfde waarde die is gebruikt voor het verkrijgen van de authorization_code.
grant_type vereist Moet voor de autorisatiecodestroom zijn authorization_code .
code_verifier aanbevolen Hetzelfde code_verifier dat is gebruikt om de authorization_code te verkrijgen. Vereist als PKCE is gebruikt in de aanvraag voor het verlenen van 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 client_secret veilig op de server kunnen opslaan. Net als alle parameters hier moet het clientgeheim URL-gecodeerd zijn voordat het wordt verzonden. Deze stap wordt meestal uitgevoerd door de SDK. Zie de algemene syntaxisspecificatie van de URI voor meer informatie over URI-codering. Het basisverificatiepatroon van in plaats daarvan referenties op te geven in de autorisatieheader, per RFC 6749 wordt ook ondersteund.

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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 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 de Azure Portal - App-registraties pagina is toegewezen aan uw app.
scope optioneel Een door spaties gescheiden lijst met 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 redirect_uri Dezelfde waarde die is gebruikt voor het verkrijgen van de authorization_code.
grant_type vereist Moet voor de autorisatiecodestroom zijn authorization_code .
code_verifier aanbevolen Hetzelfde code_verifier dat is gebruikt om de authorization_code. Vereist als PKCE is gebruikt in de aanvraag voor het verlenen van autorisatiecode. Zie de PKCE RFC voor meer informatie.
client_assertion_type vereist voor vertrouwelijke web-apps De waarde moet worden ingesteld op urn:ietf:params:oauth:client-assertion-type:jwt-bearer het gebruik van een certificaatreferentie.
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.

Geslaagd antwoord

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 Beschrijving
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 Azure AD ondersteunt, 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 als u dit weglaat, is het token bedoeld voor de bereiken die zijn aangevraagd in het eerste deel 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 gedurende langere perioden toegang tot resources behouden. Raadpleeg het toegangstoken verderop in dit artikel voor meer informatie over het vernieuwen van een toegangstoken .
Notitie: Alleen opgegeven als offline_access het bereik 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 voor meer informatie over id_tokens de id_token reference.
Notitie: Alleen opgegeven als openid het bereik is aangevraagd.

Foutreactie

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 Beschrijving
error Een tekenreeks met foutcodes die kan worden gebruikt om typen fouten te classificeren 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 u kunnen helpen bij diagnostische gegevens.
timestamp Het tijdstip 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 verschillende onderdelen.

Foutcodes voor fouten met tokeneindpunten

Foutcode Beschrijving Clientactie
invalid_request Protocolfout, zoals een ontbrekende vereiste parameter. Corriseer de aanvraag of app-registratie en verzend de aanvraag opnieuw.
invalid_grant De autorisatiecode of PKCE-codeverifier 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 Azure AD of niet wordt toegevoegd aan de Azure AD tenant van de gebruiker. De toepassing kan de gebruiker vragen om instructies voor het installeren van de toepassing en deze toe te voegen aan Azure AD.
invalid_client Clientverificatie is mislukt. De clientreferenties zijn niet geldig. De toepassingsbeheerder werkt de referenties bij om dit op te lossen.
unsupported_grant_type De autorisatieserver biedt geen ondersteuning voor het type autorisatietoestemming. Wijzig het toekenningstype in de aanvraag. Dit type fout mag alleen optreden tijdens de ontwikkeling en tijdens de eerste test worden gedetecteerd.
invalid_resource De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of omdat deze niet juist is geconfigureerd. Deze code geeft aan dat de resource, indien aanwezig, 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 Azure AD.
interaction_required Niet-standaard, omdat de OIDC-specificatie alleen voor deze code op het /authorize eindpunt aanroept. Voor de aanvraag is gebruikersinteractie vereist. Een andere verificatiestap is bijvoorbeeld vereist. Probeer de /authorize aanvraag opnieuw met dezelfde bereiken.
temporarily_unavailable De server is tijdelijk te druk om de aanvraag af te handelen. Voer de aanvraag na een kleine vertraging opnieuw uit. De clienttoepassing kan de gebruiker uitleggen dat het antwoord wordt vertraagd vanwege een tijdelijke voorwaarde.
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 cross-origin token inwisseling 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 over het inschakelen van deze stroom.

Het toegangstoken gebruiken

Nu u een access_tokentoken hebt verkregen, 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 zijn kort. 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 aan te vragen voor scope=api://contoso.com/api/UseResource.

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 er 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. Het moet worden gedaan in een frame op het hoogste niveau, ofwel 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 dat u het oude vernieuwingstoken negeert. 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, hebben die verlooptijd, 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 zelfs geen gebruikerservaring, alleen een herload 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 de Azure Portal – App-registraties ervaring is toegewezen aan uw app.
grant_type vereist Moet voor dit deel van de autorisatiecodestroom zijn refresh_token .
scope optioneel Een door spaties gescheiden lijst met bereiken. De bereiken die in dit been zijn aangevraagd, moeten gelijk zijn aan of een subset van de bereiken die zijn aangevraagd in het oorspronkelijke authorization_code aanvraagbestel. Als de bereiken die zijn opgegeven in deze aanvraag meerdere resourceservers omvatten, retourneert de Microsoft identity platform een token voor de resource die is opgegeven in het eerste bereik. Zie Machtigingen en toestemming in de Microsoft identity platform voor meer informatie.
refresh_token vereist De refresh_token die u in het tweede been van de stroom hebt verkregen.
client_secret vereist voor web-apps Het toepassingsgeheim dat u hebt gemaakt in de portal voor app-registratie 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 client_secret opslag veilig aan de serverzijde kunnen opslaan. Dit geheim moet url-gecodeerd zijn. Zie de algemene syntaxisspecificatie van de URI voor meer informatie.

Geslaagde reactie

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 Beschrijving
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 Azure AD ondersteunt, is Bearer.
expires_in Hoe lang het toegangstoken geldig is, in seconden.
scope De bereiken waarvoor de access_token bereiken geldig zijn.
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.
Notitie: Alleen opgegeven als offline_access het bereik 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 er mag geen gebruik van worden gemaakt voor autorisatie- of beveiligingsgrenzen. Zie de Microsoft identity platform ID-tokens voor meer informatie.id_token
Notitie: Alleen opgegeven als openid het bereik is aangevraagd.

Waarschuwing

Probeer geen tokens te valideren of te lezen voor een API die u niet bezit, inclusief de tokens in dit voorbeeld, in uw code. Tokens voor Microsoft-services kunnen gebruikmaken van een speciale indeling die niet als JWT wordt gevalideerd, en kan ook worden versleuteld voor gebruikers van consumenten (Microsoft-account). Hoewel het lezen van tokens een handig hulpprogramma voor foutopsporing en leren is, neemt u hier geen afhankelijkheden van in uw code of gaat u ervan uit dat u specifieke informatie over tokens gebruikt die niet voor een API die u beheert.

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 Beschrijving
error Een tekenreeks met foutcodes die kan worden gebruikt om typen fouten te classificeren 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 u kunnen helpen bij diagnostische gegevens.
timestamp Het tijdstip 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 verschillende onderdelen.

Zie Foutcodes voor eindpuntfouten voor tokens voor een beschrijving van de foutcodes en de aanbevolen clientactie.

Volgende stappen