Microsoft identity platform en OAuth 2.0-autorisatiecodestroom

De OAuth 2.0-autorisatiecode kan worden gebruikt in apps die zijn geïnstalleerd op een apparaat om toegang te krijgen tot beveiligde resources, zoals web-API's. Met behulp Microsoft identity platform implementatie van OAuth 2.0 kunt u aanmeldings- en API-toegang toevoegen aan uw mobiele apps en desktop-apps.

In dit artikel wordt beschreven hoe u in elke taal rechtstreeks kunt programmeren op basis van het protocol in uw toepassing. Indien mogelijk raden we u aan om in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken om tokens te verkrijgen en beveiligde web-API's aan te roepen. Bekijk ook de voorbeeld-apps die gebruikmaken van MSAL.

De OAuth 2.0-autorisatiecodestroom wordt beschreven in sectie 4.1 van de OAuth 2.0-specificatie. Het wordt gebruikt voor het uitvoeren van verificatie en autorisatie in de meeste app-typen, waaronder appsmet één pagina, web-appsen systeemeigen geïnstalleerde apps. Met de stroom kunnen apps veilig access_tokens verkrijgen die kunnen worden gebruikt voor toegang tot resources die worden beveiligd door de Microsoft identity platform, evenals vernieuwingstokens voor extra access_tokens en id-tokens voor de aangemelde gebruiker.

Tip

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

Protocoldiagram

Op hoog niveau ziet de volledige verificatiestroom voor een toepassing er een beetje als de volgende uit:

OAuth Auth Code Flow

Installatie van omleidings-URI vereist voor apps met één pagina

De autorisatiecodestroom voor toepassingen met één pagina vereist extra instellingen. Volg de instructies voor het maken van uw toepassing met één pagina om de omleidings-URI correct te markeren als ingeschakeld voor CORS. Als u een bestaande omleidings-URI wilt bijwerken om CORS in te kunnenschakelen, opent u de manifesteditor en stelt u het veld voor uw omleidings-URI type in op in de sectie spa replyUrlsWithType . U kunt ook klikken op de omleidings-URI in de sectie 'Web' van het tabblad Verificatie en de URI's selecteren die u wilt migreren met behulp van de autorisatiecodestroom.

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 gaan en doorgaan met het gebruik van de impliciete stroom.

Als u de autorisatiecodestroom probeert te gebruiken en deze fout ziet:

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.

Ga vervolgens naar uw app-registratie en werk de omleidings-URI voor uw app bij om te spa typen.

Toepassingen kunnen geen spa omleidings-URI gebruiken met niet-SPA-stromen, bijvoorbeeld native toepassingen of clientreferentiestromen. Om de beveiliging en best practices te garanderen, retournt het Microsoft Identity-platform een foutmelding als u probeert een omleidings-URI zonder header spa te Origin gebruiken. Op dezelfde manier voorkomt het Microsoft Identity-platform ook het gebruik van clientreferenties (in de OBO-stroom, clientreferentiestroom en auth-codestroom) in de aanwezigheid van een header, om ervoor te zorgen dat geheimen niet worden gebruikt vanuit de Origin browser.

Een autorisatiecode aanvragen

De autorisatiecodestroom begint met de client die de gebruiker naar het /authorize eindpunt stuurt. In deze aanvraag vraagt de client de openid offline_access machtigingen , en https://graph.microsoft.com/mail.read aan bij de gebruiker. Sommige machtigingen hebben beheerdersrechten, zoals het schrijven van gegevens naar de directory van een organisatie met behulp van Directory.ReadWrite.All . Als uw toepassing toegang tot een van deze machtigingen van een organisatiegebruiker aanvraagt, ontvangt de gebruiker een foutbericht met de melding dat deze niet is gemachtigd om toestemming te geven voor de machtigingen van uw app. Als u toegang wilt aanvragen tot bereiken met beperkte beheerdersrechten, moet u deze rechtstreeks aanvragen bij een globale beheerder. Lees Beheerdersmachtigingen voor meer informatie.

// 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%20api%3A%2F%2F
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Tip

Klik op de onderstaande koppeling om deze aanvraag uit te voeren. Na het aanmelden moet uw browser worden omgeleid naar http://localhost/myapp/ met een in de code adresbalk. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

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. De toegestane waarden zijn common organizations , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie. Voor gastscenario's waarbij u een gebruiker van de ene tenant bij een andere tenant ondertekent, moet u de tenant-id verstrekken om deze correct aan te melden bij de resource-tenant.
client_id vereist De toepassings-id (client-id) die Azure Portal - App-registraties-ervaring die aan uw app is toegewezen.
response_type vereist Moet opnemen code voor de autorisatiecodestroom. Kan ook of id_token opnemen als de hybride stroom wordt token gebruikt.
redirect_uri vereist De redirect_uri van uw app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de redirect_uris u hebt geregistreerd in de portal, behalve dat deze URL moet zijn gecodeerd. Voor systeemeigen & mobiele apps moet u een van de aanbevolen waarden gebruiken: (voor apps die gebruikmaken van ingesloten browsers) of (voor apps die gebruikmaken van https://login.microsoftonline.com/common/oauth2/nativeclient http://localhost systeembrowsers).
scope vereist Een door spatie gescheiden lijst met scopes waar de gebruiker toestemming voor moet geven. Dit kan betrekking hebben op meerdere resources, zodat uw app toestemming kan krijgen voor meerdere web-API's die /authorize u wilt aanroepen.
response_mode Aanbevolen Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. Kan een van de volgende zijn:

- query
- fragment
- form_post

query biedt de code als een queryreeksparameter op uw omleidings-URI. Als u een id-token aanvraagt met behulp van de impliciete stroom, kunt u niet gebruiken zoals opgegeven in de query OpenID-specificatie. Als u alleen de code aanvraagt, kunt u query , fragment of form_post gebruiken. form_post voert een POST met de code uit naar uw omleidings-URI.
state Aanbevolen Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in de tokenreactie. Dit kan een tekenreeks zijn van alle inhoud die u wilt. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om aanvallen met aanvraagvervalsing op andere plaatsen te voorkomen. De waarde kan ook informatie over de status van de gebruiker in de app coderen voordat de verificatieaanvraag plaatsvond, zoals de pagina of weergave waarin deze zich hebben voorgedaan.
prompt optioneel Geeft het type gebruikersinteractie aan dat vereist is. De enige geldige waarden op dit moment zijn login , none , en consent select_account .

- prompt=login dwingt de gebruiker om zijn of haar referenties op die aanvraag in te voeren, wat een een aanmelding onderhandelt.
- prompt=none is het tegenovergestelde: het zorgt ervoor dat de gebruiker helemaal geen interactieve prompt krijgt te zien. Als de aanvraag niet op de stilzwijgend kan worden voltooid via een aanmelding, wordt Microsoft identity platform interaction_required foutmelding weergegeven.
- prompt=consent activeert het OAuth-toestemmingsdialoogvenster nadat de gebruiker zich heeft meldt en vraagt de gebruiker om machtigingen voor de app te verlenen.
- prompt=select_account onderbreekt een aanmelding om een account te selecteren, zodat alle accounts in een sessie of een onthouden account worden vermeld, of een optie om ervoor te kiezen om helemaal een ander account te gebruiken.
login_hint Optioneel U kunt deze parameter gebruiken om vooraf de gebruikersnaam en het e-mailadresveld van de aanmeldingspagina voor de gebruiker in te vullen, als u de gebruikersnaam van tevoren kent. Vaak gebruiken apps deze parameter tijdens het opnieuw authenticatie, nadat de optionele claim al is geëxtraheert uit een login_hint eerdere aanmelding.
domain_hint optioneel Indien opgenomen, wordt het detectieproces op basis van e-mail overgeslagen dat de gebruiker op de aanmeldingspagina doormaakt, wat leidt tot een iets gestroomlijnder gebruikerservaring, bijvoorbeeld door ze naar hun federatief-id-provider te verzenden. Vaak gebruiken apps deze parameter tijdens het opnieuw verificatieproces, door de te tid extraheren uit een eerdere aanmelding.
code_challenge aanbevolen/vereist Wordt gebruikt voor het beveiligen van autorisatiecodetoestemmingen via Proof Key for Code Exchange (PKCE). Vereist als code_challenge_method is opgenomen. Zie de PKCE RFC voor meer informatie. Dit wordt nu aanbevolen voor alle toepassingstypen ( zowel openbare als vertrouwelijke clients) en vereist door 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 voor code_verifier de parameter te code_challenge coderen. Dit moet zijn, maar de specificatie staat het gebruik van toe als om een of andere reden S256 de client plain SHA256 niet kan ondersteunen.

Indien uitgesloten, code_challenge wordt ervan uitgegaan dat dit platte tekst is als code_challenge deze is opgenomen. De Microsoft identity platform ondersteunt zowel plain als S256 . Zie de PKCE RFC voor meer informatie. Dit is vereist voor apps met één pagina met behulp van de autorisatiecodestroom.

Op dit moment wordt de gebruiker gevraagd om zijn of haar 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 worden aangegeven in de scope queryparameter. Als de gebruiker geen toestemming heeft gegeven voor een van deze machtigingen, wordt de gebruiker gevraagd toestemming te geven voor de vereiste machtigingen. Meer informatie over machtigingen, toestemming en apps met meerdere tenants kunt u hier vinden.

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

Geslaagd antwoord

Een geslaagd antwoord met behulp van response_mode=query ziet er als volgende uit:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Parameter Beschrijving
code De authorization_code die de app heeft aangevraagd. De app kan de autorisatiecode gebruiken om een toegangs token aan te vragen voor de doelresource. Authorization_codes van korte duur zijn, verlopen ze meestal na ongeveer 10 minuten.
state Als een statusparameter 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 er een aanvraagt en de impliciete toekenning hebt ingeschakeld in de registratie van uw toepassing. Dit wordt ook wel de 'hybride stroom'genoemd en wordt gebruikt door frameworks zoals ASP.NET.

Foutbericht

Foutreacties kunnen ook naar de worden redirect_uri verzonden, zodat de app deze op de juiste wijze kan verwerken:

GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
Parameter Beschrijving
error Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht dat een ontwikkelaar kan helpen bij het identificeren van de hoofdoorzaak van een verificatiefout.

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 Description Clientactie
invalid_request Protocolfout, zoals een ontbrekende vereiste parameter. De aanvraag herstellen en opnieuw indienen. Dit 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 is toegevoegd aan de Azure AD-tenant van de gebruiker. De toepassing kan de gebruiker vragen met instructies voor het installeren van de toepassing en het toevoegen ervan aan Azure AD.
access_denied Resource-eigenaar heeft toestemming 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. De aanvraag herstellen en opnieuw indienen. Dit is een ontwikkelingsfout die doorgaans is opgetreden tijdens de eerste test. Wanneer u in de hybride stroom ziet,geeft dit aan dat u de instelling impliciete toekenning van het id-token moet inschakelen voor de registratie van de client-app.
server_error Er is een onverwachte fout opgetreden op de server. De aanvraag opnieuw proberen. Deze fouten kunnen het gevolg zijn van tijdelijke omstandigheden. De clienttoepassing kan de gebruiker uitleggen dat het antwoord op een tijdelijke fout is vertraagd.
temporarily_unavailable De server is tijdelijk te druk om de aanvraag te verwerken. De aanvraag opnieuw proberen. De clienttoepassing kan de gebruiker uitleggen dat het antwoord is vertraagd vanwege een tijdelijke voorwaarde.
invalid_resource De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of niet juist is geconfigureerd. Deze fout geeft aan dat de resource, indien deze bestaat, niet is geconfigureerd in de tenant. De toepassing kan de gebruiker vragen met instructies voor het installeren van de toepassing en het toevoegen ervan aan Azure AD.
login_required Te veel of geen gebruikers gevonden De client heeft stille verificatie aangevraagd ( prompt=none ), maar één gebruiker kan niet worden gevonden. Dit kan betekenen dat er meerdere gebruikers actief zijn in de sessie of dat er geen gebruikers zijn. Hiermee wordt rekening gehouden met de gekozen tenant (als er bijvoorbeeld twee Azure AD-accounts actief zijn en één Microsoft-account is gekozen, werkt stille consumers verificatie).
interaction_required Voor de aanvraag is gebruikersinteractie vereist. Er is een extra verificatiestap of -toestemming vereist. De aanvraag opnieuw proberen zonder prompt=none .

Vraag ook een id-token aan (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. Dit wordt de hybride stroom genoemd omdat de impliciete toekenning wordt gecombineerd met de autorisatiecodestroom. De hybride stroom wordt vaak gebruikt in web-apps die een pagina voor een gebruiker willen renderen zonder het inwisselen van code te blokkeren,met name ASP.NET . Zowel apps met één pagina als traditionele web-apps profiteren van een verminderde latentie in dit model.

De hybride stroom is hetzelfde als de autorisatiecodestroom die eerder is beschreven, maar met drie toevoegingen, die allemaal vereist zijn om een id-token aan te vragen: nieuwe scopes, 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
Bijgewerkte parameter Vereist/optioneel Beschrijving
response_type Vereist De toevoeging van geeft aan de server aan dat de toepassing een id-token in het antwoord van id_token het /authorize eindpunt wil.
scope Vereist Voor id-tokens moet worden bijgewerkt om de id-tokenbereiken - en optioneel en op openid profile te email nemen.
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 controleren om aanvallen met token opnieuw afspelen te beperken. De waarde is doorgaans een willekeurige, 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, fragment maar als de aanvraag een response_type id_token. Apps worden echter aanbevolen om te gebruiken, met form_post name bij gebruik als http://localhost omleidings-URI.

Het gebruik van als antwoordmodus veroorzaakt problemen voor web-apps die de code uit de omleiding lezen, omdat browsers het fragment niet doorgeven fragment aan de webserver. In dergelijke situaties moeten apps de responsmodus gebruiken om ervoor te form_post zorgen dat alle gegevens naar de server worden verzonden.

Geslaagd antwoord

Een geslaagd antwoord met behulp van response_mode=fragment ziet er als volgende uit:

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 toegangs token aan te vragen voor de doelresource. Autorisatiecodes zijn van korte duur en verlopen meestal na ongeveer 10 minuten.
id_token Een id-token voor de gebruiker, uitgegeven via impliciete toekenning. Bevat een speciale c_hash claim die de hash van de in dezelfde aanvraag code is.
state Als een statusparameter 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.

Een code inwisselen voor een toegangs token

Alle vertrouwelijke clients kunnen kiezen uit het gebruik van clientgeheimen (symmetrische gedeelde geheimen die zijn gegenereerd door de Microsoft identity platform) en certificaatreferenties(asymmetrische sleutels die door de ontwikkelaar zijn geüpload). Voor de beste beveiliging raden we u aan om certificaatreferenties te gebruiken. Openbare clients (native 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 correct aangeven en uniek zijn.

Een toegangs token met een client_secret

Nu u een authorization_code hebt verkregen en toestemming hebt gekregen van de gebruiker, kunt u de voor een inwisselen voor code access_token de gewenste resource. Dit doet u door een POST aanvraag naar het eindpunt te /token 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 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. De toegestane waarden zijn common organizations , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie.
client_id vereist De toepassings-id (client-id) Azure Portal - App-registraties aan uw app is toegewezen.
scope optioneel Een door spaties gescheiden lijst met scopes. De scopes moeten allemaal afkomstig zijn uit één resource, samen met OIDC-scopes ( profile , openid , email ). Raadpleeg machtigingen, toestemming en scopes voor een gedetailleerdere uitleg van scopes. Dit is een Microsoft-extensie voor de autorisatiecodestroom, die is bedoeld om apps toe te staan de resource te declaren voor welke resource ze het token willen gebruiken tijdens het inwisselen van het token.
code vereist De authorization_code die u hebt verkregen in het eerste deel van de stroom.
redirect_uri vereist Dezelfde waarde redirect_uri die is gebruikt voor het verkrijgen van de authorization_code.
grant_type vereist Moet voor authorization_code de autorisatiecodestroom zijn.
code_verifier Aanbevolen Dezelfde code_verifier die is gebruikt voor het verkrijgen van de authorization_code. 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 portal voor app-registratie voor uw app. Gebruik het toepassingsgeheim niet in een native app of app met één pagina, omdat client_secrets niet betrouwbaar kunnen worden opgeslagen op apparaten of webpagina's. Dit is vereist voor web-apps en web-API's, die de mogelijkheid hebben om de client_secret veilig op te slaan aan de serverzijde. Net als alle parameters die hier worden besproken, moet het clientgeheim URL-gecodeerd zijn voordat het wordt verzonden, een stap die doorgaans wordt uitgevoerd door de SDK. Zie de specificatie Algemene URI-syntaxis voor meer informatie over URI-codering. Het basisverkenningspatroon van in plaats van referenties op te geven in de autorisatie-header, per RFC 6749 wordt ook ondersteund.

Een toegangs token met een certificaatreferentie aanvragen

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 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. De toegestane waarden zijn common organizations , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie.
client_id vereist De toepassings-id (client-id) die Azure Portal - App-registraties aan uw app is toegewezen.
scope optioneel Een door spaties gescheiden lijst met scopes. De scopes moeten allemaal afkomstig zijn uit één resource, samen met OIDC-scopes ( profile , openid , email ). Raadpleeg machtigingen, toestemming en scopes voor een gedetailleerdere uitleg van scopes. Dit is een Microsoft-extensie voor de autorisatiecodestroom, die is bedoeld om apps toe te staan de resource te declaren voor welke resource ze het token willen gebruiken tijdens het inwisselen van het token.
code vereist De authorization_code die u hebt verkregen in het eerste deel van de stroom.
redirect_uri vereist Dezelfde waarde redirect_uri die is gebruikt voor het verkrijgen van de authorization_code.
grant_type vereist Moet voor authorization_code de autorisatiecodestroom zijn.
code_verifier Aanbevolen Dezelfde code_verifier die is gebruikt voor het verkrijgen van 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 om een certificaatreferentie te kunnen gebruiken.
client_assertion vereist voor vertrouwelijke web-apps Een verklaring (een JSON-web-token) die u moet maken en ondertekenen met het certificaat dat u hebt geregistreerd als referenties voor uw toepassing. Meer informatie over certificaatreferenties voor meer informatie over het registreren van uw certificaat en de indeling van de verklaring.

U ziet dat de parameters hetzelfde zijn als in het geval van de aanvraag door een gedeeld geheim, behalve dat de parameter wordt vervangen door twee client_secret parameters: a client_assertion_type en client_assertion .

Geslaagd antwoord

Een geslaagd token-antwoord ziet er als volgende uit:

{
    "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 toegang token. 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 Azure AD wordt ondersteund, is Bearer
expires_in Hoe lang het toegangs token geldig is (in seconden).
scope De scopes waar de access_token geldig voor is. Optioneel: dit is niet-standaard en als u dit weggelaten, is het token voor de scopes die zijn aangevraagd voor de eerste pijp van de stroom.
refresh_token Een OAuth 2.0-vernieuwingsteken. De app kan dit token gebruiken om extra toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Refresh_tokens lange duur zijn en kunnen worden gebruikt om de toegang tot resources gedurende langere tijd te behouden. Raadpleeg de sectie hieronder voor meer informatie over het vernieuwen van een toegangs token.
Opmerking: Alleen opgegeven als offline_access het bereik is aangevraagd.
id_token Een JSON Web Token (JWT). 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 cachen en weergeven, en vertrouwelijke clients kunnen deze gebruiken voor autorisatie. Zie voor meer informatie over id_tokens. id_token reference
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd.

Foutbericht

Foutreacties zien er als volgende uit:

{
  "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 foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht dat een ontwikkelaar kan helpen bij het identificeren van de hoofdoorzaak van een verificatiefout.
error_codes Een lijst met STS-specifieke foutcodes die 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 token-eindpuntfouten

Foutcode Description Clientactie
invalid_request Protocolfout, zoals een ontbrekende vereiste parameter. De aanvraag of app-registratie herstellen en de aanvraag opnieuw indienen
invalid_grant De autorisatiecode of PKCE-codeverlener is ongeldig of is verlopen. Probeer een nieuwe aanvraag naar het eindpunt en controleer of de parameter /authorize code_verifier juist is.
unauthorized_client De geverifieerde client is niet gemachtigd om dit type autorisatietoestemming te gebruiken. Dit gebeurt meestal wanneer de clienttoepassing niet is geregistreerd in Azure AD of niet is toegevoegd aan de Azure AD-tenant van de gebruiker. De toepassing kan de gebruiker vragen om de toepassing te installeren en toe te voegen aan Azure AD.
invalid_client Clientverificatie is mislukt. De clientreferenties zijn niet geldig. Om dit probleem op te lossen, werkt de toepassingsbeheerder de referenties bij.
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 wordt gedetecteerd tijdens de eerste test.
invalid_resource De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of niet juist is geconfigureerd. Dit geeft aan dat de resource, indien deze bestaat, niet is geconfigureerd in de tenant. De toepassing kan de gebruiker vragen met instructies voor het installeren van de toepassing en het toevoegen ervan aan Azure AD.
interaction_required Niet-standaard, omdat de OIDC-specificatie hiervoor alleen op het /authorize eindpunt aanroept. Voor de aanvraag is gebruikersinteractie vereist. Er is bijvoorbeeld een extra verificatiestap vereist. De aanvraag /authorize opnieuw proberen met dezelfde scopes.
temporarily_unavailable De server is tijdelijk te druk om de aanvraag te verwerken. Opnieuw proberen de aanvraag na een kleine vertraging. De clienttoepassing kan de gebruiker uitleggen dat het antwoord is vertraagd vanwege een tijdelijke voorwaarde.
consent_required Voor de aanvraag is toestemming van de gebruiker vereist. Deze fout is niet-standaard, omdat deze doorgaans alleen wordt geretourneerd op het /authorize eindpunt per OIDC-specificaties. Geretourneerd toen een scope parameter werd gebruikt in de codewisselstroom die de client-app niet heeft om aan te vragen. De client moet de gebruiker met het juiste bereik terugsturen naar het /authorize eindpunt om toestemming te activeren.
invalid_scope Het bereik dat is aangevraagd door de app is ongeldig. Werk de waarde van de bereikparameter in de verificatieaanvraag bij naar een geldige waarde.

Notitie

Apps met één pagina kunnen een foutmelding ontvangen die aangeeft dat het inwisselen van een cross-origin-token alleen is toegestaan voor het invalid_request 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 toegangsken gebruiken

Nu u een hebt verkregen, kunt u het token gebruiken in aanvragen voor web-API's door het op te nemen access_token in de Authorization header:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Het toegangsken vernieuwen

Access_tokens zijn van korte duur en u moet ze vernieuwen nadat ze zijn verlopen om toegang te blijven krijgen tot resources. U kunt dit doen door een andere aanvraag naar het eindpunt te verzenden. Deze keer geeft u de op POST in plaats van de /token refresh_token code . Vernieuwingstokens zijn geldig voor alle machtigingen waar uw client al toestemming voor heeft ontvangen. Daarom kan een vernieuwingstoken dat is uitgegeven bij een aanvraag voor worden gebruikt om een nieuw toegangstoken aan te scope=mail.read vragen voor scope=api://contoso.com/api/UseResource .

Vernieuwingstokens voor web-apps en native apps hebben geen opgegeven levensduur. Normaal gesproken is de levensduur van vernieuwingstokens relatief lang. In sommige gevallen verlopen vernieuwingstokens echter, worden ze ingetrokken of hebben ze onvoldoende bevoegdheden voor de gewenste actie. Uw toepassing moet fouten die door het tokenuitgifte-eindpunt worden geretourneerd, correct verwachten en verwerken. Apps met één pagina krijgen echter een token met een levensduur van 24 uur, waarvoor elke dag een nieuwe verificatie is vereist. Dit kan op de stille manier worden gedaan in een iframe wanneer cookies van derden zijn ingeschakeld, maar moeten worden uitgevoerd in een frame op het hoogste niveau (volledige paginanavigatie of een pop-up) in browsers zonder cookies van derden, zoals Safari.

Hoewel vernieuwingstokens niet worden ingetrokken wanneer ze worden gebruikt om nieuwe toegangstokens te verkrijgen, wordt verwacht dat u het oude vernieuwingstoken moet verwijderen. De OAuth 2.0-specificatie geeft het volgende weer: "De autorisatieserver kan een nieuw vernieuwingsteken uitgeven. In dat geval moet de client het oude vernieuwings token verwijderen en vervangen door het nieuwe vernieuwings token. De autorisatieserver kan het oude vernieuwings token intrekken na het uitgeven van een nieuw vernieuwings token aan de client.

Belangrijk

Voor vernieuwingstokens die worden verzonden naar een omleidings-URI die is geregistreerd als , verloopt het spa vernieuwingstoken na 24 uur. Aanvullende vernieuwingstokens die zijn verkregen met behulp van het initiële vernieuwingstoken, dragen die verlooptijd over. Apps moeten dus 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 moeten hun referenties niet invoeren en zien meestal zelfs geen UX, alleen een herload van uw toepassing. De browser moet echter de aanmeldingspagina in een frame op het hoogste niveau bezoeken om de aanmeldingssessie te 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 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. De toegestane waarden zijn common organizations , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie.
client_id vereist De toepassings-id (client) die Azure Portal - App-registraties-ervaring die aan uw app is toegewezen.
grant_type vereist Moet voor refresh_token dit deel van de autorisatiecodestroom zijn.
scope optioneel Een door spatie gescheiden lijst met scopes. De scopes die in dit deel worden aangevraagd, moeten gelijk zijn aan of een subset van de scopes die zijn aangevraagd in de oorspronkelijke authorization_code aanvraag. Als de in deze aanvraag opgegeven scopes meerdere resourceservers bespannen, retourneert de Microsoft identity platform een token voor de resource die is opgegeven in het eerste bereik. Raadpleeg machtigingen, toestemming en scopes voor een gedetailleerdere uitleg van scopes.
refresh_token vereist De refresh_token u hebt verkregen in het tweede deel van de stroom.
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 native app, omdat client_secrets betrouwbaar kunnen worden opgeslagen op apparaten. Dit is vereist voor web-apps en web-API's, die de mogelijkheid hebben om de client_secret aan de serverzijde op te slaan. Dit geheim moet URL-gecodeerd zijn. Zie URI Generic Syntax specification (Algemene syntaxisspecificatie voor URI) voor meer informatie.

Geslaagd antwoord

Een geslaagd token-antwoord ziet er als volgende uit:

{
    "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 toegangs token. 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 Azure AD wordt ondersteund, is Bearer
expires_in Hoe lang het toegangsken geldig is (in seconden).
scope De scopes waar de access_token geldig voor is.
refresh_token Een nieuw OAuth 2.0-vernieuwingsteken. Vervang het oude vernieuwingstoken door dit zojuist verkregen vernieuwingstoken om ervoor te zorgen dat uw vernieuwingstokens zo lang mogelijk geldig blijven.
Opmerking: Alleen opgegeven als offline_access het bereik is aangevraagd.
id_token Een niet-ondertekend JSON Web Token (JWT). 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 cachen en weergeven, maar deze mogen niet afhankelijk zijn van deze waarden voor autorisatie of beveiligingsgrenzen. Zie voor meer informatie over id_tokens. id_token reference
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd.

Waarschuwing

Probeer geen tokens te valideren of te lezen voor een API waarvan u geen eigenaar bent, met inbegrip van 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 die ook kan worden versleuteld voor gebruikers (Microsoft-account). Hoewel het lezen van tokens een nuttig hulpprogramma is voor het opsporen en leren van tokens, moet u hier geen afhankelijkheden van nemen in uw code of specifieke informatie aannemen over tokens die niet voor een API zijn die u controleert.

Foutbericht

{
  "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 foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht dat een ontwikkelaar kan helpen bij het identificeren van de hoofdoorzaak van een verificatiefout.
error_codes Een lijst met STS-specifieke foutcodes die 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 token-eindpuntfoutenvoor een beschrijving van de foutcodes en de aanbevolen clientactie.