Azure Active Directory-webtoepassingen toegang verlenen met de stroom voor het verlenen van de OAuth 2.0-code
Waarschuwing
Deze inhoud is voor het oudere Azure AD v1.0-eindpunt. Gebruik het Microsoft Identity Platform voor nieuwe projecten.
Notitie
Als u de server niet vertelt welke bon u wilt aanroepen, activeert de server het beleid voor voorwaardelijke toegang voor die bron niet. Voor een MFA-trigger moet u dus een resource opnemen in uw URL.
Azure Active Directory (Azure AD) maakt gebruik van OAuth 2.0 om het mogelijk te maken dat u toegang tot webtoepassingen en web-API's in uw Azure AD-tenant kunt autoriseren. In deze taalonafhankelijke handleiding wordt beschreven hoe u HTTP-berichten verzendt en ontvangt zonder onze open source-bibliotheken te gebruiken.
De OAuth 2.0-autorisatiecodestroom wordt beschreven in sectie 4.1 van de OAuth 2.0-specificatie. Het wordt gebruikt om verificatie en autorisatie uit te voeren in de meeste toepassingstypen, waaronder web-apps en systeemeigen geïnstalleerde toepassingen.
Uw toepassing registreren bij uw AD-tenant
U moet eerst uw toepassing registreren bij uw Azure Active Directory-tenant (Azure AD-tenant). Na registratie beschikt u over een toepassings-id voor uw toepassing en kan uw toepassing tokens ontvangen.
Meld u aan bij de Azure-portal.
Kies uw Azure Active Directory-tenant door in de rechterbovenhoek van deze pagina uw account te selecteren, gevolgd door de navigatie Directory schakelen te selecteren en vervolgens de juiste tenant te selecteren.
- Sla deze stap over als u maar één Azure AD-tenant in uw account hebt of als u al de juiste Azure AD-tenant hebt geselecteerd.
Zoek en selecteer in de Azure-portal de optie Azure Active Directory.
Selecteer in het linkermenu van de Azure Active Directory achtereenvolgens App-registraties en Nieuwe registratie.
Volg de aanwijzingen en maak een nieuwe toepassing. Voor deze zelfstudie maakt het niet uit of het een webtoepassing of een openbare clienttoepassing (mobiel & desktop) is, maar als u specifieke voorbeelden wilt voor webtoepassingen of openbare clienttoepassingen, raadpleegt u onze quickstarts.
- Naam is de naam van de toepassing en beschrijft de toepassing voor eindgebruikers.
- Selecteer onder Ondersteunde accounttypen de optie Accounts in een organisatieadreslijst en persoonlijke Microsoft-account.
- Geef de omleidings-URI op. Voor webtoepassingen is dit de basis-URL van uw toepassing, waar gebruikers zich kunnen aanmelden. Bijvoorbeeld
http://localhost:12345. Voor een openbare client (mobiele & desktop) gebruikt Azure AD deze om tokenantwoorden te retourneren. Voer een specifieke waarde in voor uw toepassing. Bijvoorbeeldhttp://MyFirstAADApp.
Nadat u de registratie hebt voltooid, wijst Azure AD aan uw toepassing een unieke client-id toe. Dit is de toepassings-id. U hebt deze waarde nodig in de volgende secties. Kopieer deze daarom vanaf de toepassingspagina.
Als u uw toepassing in de Azure Portal wilt vinden, selecteert u App-registraties en selecteert u vervolgens Alle toepassingen weergeven.
OAuth 2.0-autorisatiestroom
Op hoog niveau ziet de volledige autorisatiestroom voor een toepassing er ongeveer als volgt uit:
Een autorisatiecode aanvragen
De autorisatiecodestroom begint met de client die de gebruiker naar het /authorize eindpunt leidt. In deze aanvraag geeft de client de machtigingen aan die de client moet verkrijgen van de gebruiker. U kunt het OAuth 2.0-autorisatie-eindpunt voor uw tenant ophalen door App-registraties > Eindpunten te selecteren in het Azure Portal.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| 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 tenant-id's, bijvoorbeeld 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 of contoso.onmicrosoft.comcommon voor tenant-onafhankelijke tokens |
| client_id | vereist | De toepassings-id die aan uw toepassing is toegewezen toen u deze bij Azure AD hebt geregistreerd. U vindt dit in het Azure Portal. Klik op Azure Active Directory in de zijbalk van de services, klik op App-registraties en kies de toepassing. |
| response_type | vereist | Moet worden opgenomen code voor de autorisatiecodestroom. |
| redirect_uri | aanbevolen | De omleidings-URI van uw 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-codering moet hebben. Voor systeemeigen & mobiele apps moet u de standaardwaarde van https://login.microsoftonline.com/common/oauth2/nativeclientgebruiken. |
| response_mode | optioneel | Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. De waarde kan query, fragmentof form_post zijn. query biedt de code als een querytekenreeksparameter op uw omleidings-URI. Als u een id-token aanvraagt met behulp van de impliciete stroom, kunt u niet query gebruiken zoals opgegeven in de OpenID-specificatie. Als u alleen de code aanvraagt, kunt u query, fragment of form_post gebruiken. form_post voert een POST uit die de code bevat naar uw omleidings-URI. De standaardwaarde is query voor een codestroom. |
| staat | aanbevolen | Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in de tokenreactie. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt voor om aanvallen van aanvraagvervalsing op meerdere sites te voorkomen. De status wordt ook gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden. |
| resource | aanbevolen | De app-id-URI van de doelweb-API (beveiligde resource). Als u de app-id-URI wilt vinden, klikt u in de Azure Portal op Azure Active Directory, klikt u op Toepassingsregistraties, opent u de pagina Instellingen van de toepassing en klikt u vervolgens op Eigenschappen. Het kan ook een externe resource zijn, zoals https://graph.microsoft.com. Dit is vereist in een van de autorisatie- of tokenaanvragen. Om ervoor te zorgen dat er minder verificatieprompts worden weergegeven in de autorisatieaanvraag om ervoor te zorgen dat toestemming van de gebruiker wordt ontvangen. |
| scope | genegeerd | Voor v1 Azure AD-apps moeten bereiken statisch worden geconfigureerd in de Azure Portal onder de Instellingen van de toepassingen, Vereiste machtigingen. |
| vraag | optioneel | Geef het type gebruikersinteractie aan dat vereist is. Geldige waarden zijn: aanmelden: De gebruiker moet worden gevraagd om opnieuw te verifiëren. select_account: The De gebruiker wordt gevraagd een account te selecteren, waarbij eenmalige aanmelding wordt onderbroken. De gebruiker kan een bestaand aangemeld account selecteren, zijn referenties invoeren voor een onthouden account of ervoor kiezen om een ander account te gebruiken. toestemming: Gebruikerstoestemming is verleend, maar moet worden bijgewerkt. De gebruiker moet worden gevraagd toestemming te geven. admin_consent: Een beheerder moet worden gevraagd om toestemming te geven namens alle gebruikers in zijn organisatie |
| login_hint | optioneel | Kan worden gebruikt om het veld gebruikersnaam/e-mailadres van de aanmeldingspagina voor de gebruiker vooraf in te vullen, als u de gebruikersnaam vooraf weet. Apps gebruiken deze parameter vaak tijdens het opnieuw verifiëren, waarbij de gebruikersnaam al is geëxtraheerd uit een eerdere aanmelding met behulp van de preferred_username-claim. |
| domain_hint | optioneel | Geeft een hint over de tenant of het domein dat de gebruiker moet gebruiken om zich aan te melden. De waarde van de dommain_hint is een geregistreerd domein voor de tenant. Als de tenant is gefedereerd naar een on-premises map, wordt AAD omgeleid naar de opgegeven tenantfederatieserver. |
| code_challenge_method | aanbevolen | De methode die wordt gebruikt om de code_verifier voor de code_challenge-parameter te coderen. Kan plain of S256 zijn. Indien uitgesloten, wordt ervan uitgegaan dat code_challenge niet-versleutelde tekst is als code_challenge is opgenomen. Azure AAD v1.0 ondersteunt zowel plainals S256. Zie de PKCE RFC voor meer informatie. |
| code_challenge | aanbevolen | Wordt gebruikt om toekenning van autorisatiecode te beveiligen via Proof Key for Code Exchange (PKCE) van een systeemeigen of openbare client. Vereist indien code_challenge_method is inbegrepen. Zie de PKCE RFC voor meer informatie. |
Notitie
Als de gebruiker deel uitmaakt van een organisatie, kan een beheerder van de organisatie namens de gebruiker toestemming geven of weigeren, of de gebruiker toestaan om toestemming te geven. De gebruiker krijgt de mogelijkheid om alleen toestemming te geven wanneer de beheerder dit toestaat.
Op dit moment wordt de gebruiker gevraagd om zijn referentie in te voeren en toestemming te geven voor de machtigingen die door de app zijn aangevraagd in de Azure Portal. Zodra de gebruiker toestemming heeft geverifieerd en verleent, stuurt Azure AD een reactie naar uw app op het redirect_uri-adres in uw aanvraag met de code.
Geslaagde reactie
Een geslaagde reactie kan er als volgt uit zien:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Parameter | Beschrijving |
|---|---|
| admin_consent | De waarde is Waar als een beheerder toestemming heeft gegeven voor een toestemmingsaanvraagprompt. |
| code | De autorisatiecode die door de toepassing is aangevraagd. De toepassing kan de autorisatiecode gebruiken om een toegangstoken aan te vragen voor de doelresource. |
| session_state | Een unieke waarde die de huidige gebruikerssessie identificeert. Deze waarde is een GUID, maar moet worden behandeld als een ondoorzichtige waarde die zonder onderzoek wordt doorgegeven. |
| staat | Als een statusparameter is opgenomen in de aanvraag, wordt dezelfde waarde weergegeven in de reactie. Het is een goede gewoonte voor de toepassing om te controleren of de statuswaarden in de aanvraag en de reactie identiek zijn voordat de reactie wordt gebruikt. Dit helpt bij het detecteren van aanvallen van aanvraagvervalsing op meerdere sites (CSRF-aanvallen) gericht op de client. |
Foutreacties
Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de toepassing ze op de juiste manier kan verwerken.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Beschrijving |
|---|---|
| fout | Een foutcodewaarde die is gedefinieerd in sectie 5.2 van het OAuth 2.0-autorisatieframework. In de volgende tabel worden de foutcodes beschreven die Azure AD retourneert. |
| error_description | Een gedetailleerdere beschrijving van de fout. Dit bericht is niet bedoeld om gebruiksvriendelijk te zijn. |
| staat | De statuswaarde is een willekeurig gegenereerde niet-hergebruikte waarde die in de aanvraag wordt verzonden en die wordt geretourneerd in de reactie om aanvallen van aanvraagvervalsing op meerdere sites (CSRF-aanvallen) te voorkomen. |
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. | Herstel de aanvraag en dien ze opnieuw in. Dit is een ontwikkelingsfout en wordt meestal opgevangen tijdens de eerste test. |
| unauthorized_client | De clienttoepassing mag geen autorisatiecode aanvragen. | Dit gebeurt meestal 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 door resource-eigenaar geweigerd | De clienttoepassing kan de gebruiker waarschuwen dat het niet kan worden voortgezet, tenzij de gebruiker toestemming geeft. |
| unsupported_response_type | De autorisatieserver biedt geen ondersteuning voor het reactietype in de aanvraag. | Herstel de aanvraag en dien ze opnieuw in. Dit is een ontwikkelingsfout en wordt meestal opgevangen tijdens de eerste test. |
| 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 de reactie is vertraagd vanwege 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 voorwaarde. |
| invalid_resource | De doelresource is ongeldig omdat deze niet bestaat, Azure AD deze niet kan vinden of deze niet juist is geconfigureerd. | Dit 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. |
Gebruik de autorisatiecode om een toegangstoken aan te vragen
Nu u een autorisatiecode hebt verkregen en door de gebruiker bent gemachtigd, kunt u de code voor een toegangstoken voor de gewenste resource inwisselen door een POST-aanvraag naar het /token-eindpunt te verzenden:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
| 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 tenant-id's, bijvoorbeeld 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 of contoso.onmicrosoft.comcommon voor tenant-onafhankelijke tokens |
| client_id | vereist | De toepassings-id die aan uw toepassing is toegewezen toen u deze bij Azure AD hebt geregistreerd. U vindt dit in het Azure Portal. De toepassings-id wordt weergegeven in de instellingen van de app-registratie. |
| grant_type | vereist | Moet authorization_code zijn voor de autorisatiecodestroom. |
| code | vereist | De authorization_code die u in de vorige sectie hebt verkregen |
| redirect_uri | vereist | Een redirect_uri geregistreerd op de clienttoepassing. |
| client_secret | vereist voor web-apps, niet toegestaan voor openbare clients | Het toepassingsgeheim dat u hebt gemaakt in de Azure Portal voor uw app onder Sleutels. Het kan niet worden gebruikt in een systeemeigen app (openbare client), omdat client_secrets niet betrouwbaar kunnen worden opgeslagen op apparaten. Het is vereist voor web-apps en web-API's (alle vertrouwelijke clients), die de mogelijkheid hebben om de client_secret veilig op te slaan aan de serverzijde. De client_secret moet URL-gecodeerd zijn voordat deze wordt verzonden. |
| resource | aanbevolen | De app-id-URI van de doelweb-API (beveiligde resource). Als u de app-id-URI wilt vinden, klikt u in de Azure Portal op Azure Active Directory, klikt u op Toepassingsregistraties, opent u de pagina Instellingen van de toepassing en klikt u vervolgens op Eigenschappen. Het kan ook een externe resource zijn, zoals https://graph.microsoft.com. Dit is vereist in een van de autorisatie- of tokenaanvragen. Om ervoor te zorgen dat er minder verificatieprompts worden weergegeven in de autorisatieaanvraag om ervoor te zorgen dat toestemming van de gebruiker wordt ontvangen. In zowel de autorisatieaanvraag als de tokenaanvraag moeten de resourceparameters overeenkomen. |
| code_verifier | optioneel | Dezelfde code_verifier die is gebruikt om de autorisatiecode te verkrijgen. Vereist als PKCE is gebruikt in de toekenningsaanvraag van de autorisatiecode. Zie de PKCE RFC voor meer informatie |
Als u de app-id-URI wilt vinden, klikt u in de Azure Portal op Azure Active Directory, klikt u op Toepassingsregistraties, opent u de pagina Instellingen van de toepassing en klikt u vervolgens op Eigenschappen.
Geslaagde reactie
Azure AD retourneert een toegangstoken bij een geslaagde reactie. Om netwerkaanroepen van de clienttoepassing en de bijbehorende latentie te minimaliseren, moet de clienttoepassing toegangstokens in de cache opslaan voor de levensduur van het token dat is opgegeven in de OAuth 2.0-reactie. Als u de levensduur van het token wilt bepalen, gebruikt u de parameterwaarden expires_in of expires_on.
Als een web-API-resource een invalid_token-foutcode retourneert, kan dit erop wijzen dat de resource heeft vastgesteld dat het token is verlopen. Als de kloktijden van de client en de resource verschillen (ook wel een 'asymmetrische tijd' genoemd), kan de resource overwegen om het token te laten verlopen voordat het token uit de clientcache wordt gewist. Als dit gebeurt, wist u het token uit de cache, zelfs als het nog steeds binnen de berekende levensduur ligt.
Een geslaagde reactie kan er als volgt uit zien:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Parameter | Beschrijving |
|---|---|
| access_token | Het aangevraagde toegangstoken. Dit is een ondoorzichtige tekenreeks. Deze is afhankelijk van wat de resource verwacht te ontvangen en is niet bedoeld voor de client om naar te kijken. 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. Zie OAuth2.0 Authorization Framework: Bearer Tokens Usage (RFC 6750) (OAuth2.0 Authorization Framework: Bearer-tokengebruik (RFC 6750)) voor meer informatie over Bearer-tokens |
| expires_in | Hoe lang het toegangstoken geldig is, in seconden. |
| expires_on | De tijd waarop het token verloopt. De datum wordt weergegeven als het aantal seconden van 1970-01-01T0:0:0Z UTC tot de vervaltijd. Deze waarde wordt gebruikt om de levensduur van tokens in de cache te bepalen. |
| resource | De app-id-URI van de web-API (beveiligde resource). |
| scope | Imitatiemachtigingen die aan de cliënttoepassing zijn verleend. De standaardmachtiging is user_impersonation. De eigenaar van de beveiligde resource kan aanvullende waarden registreren in Azure AD. |
| refresh_token | Een OAuth 2.0-vernieuwingstoken. De app kan dit token gebruiken om extra toegangstokens te verkrijgen nadat het huidige toegangstoken is verlopen. Vernieuwingstokens zijn langdurig en kunnen worden gebruikt om de toegang tot resources gedurende langere tijd te behouden. |
| id_token | Een niet-ondertekende JSON Web Token (JWT) die een id-token vertegenwoordigt. De app kan de segmenten van dit token decoderen met base64Url 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 JWT IETF draft specification (conceptspecificatie van JWT IETF) voor meer informatie over JSON Web Tokens. Zie de v1.0 OpenID Connect flow (v1.0 OpenID Connect-stroom) voor meer informatie over id_tokens.
Foutreacties
De tokenuitgifte-eindpuntfouten zijn HTTP-foutcodes, omdat de client het tokenuitgifte-eindpunt rechtstreeks aanroept. Naast de HTTP-statuscode retourneert het Azure AD-tokenuitgifte-eindpunt ook een JSON-document met objecten die de fout beschrijven.
Een voorbeeld van een foutreactie kan er als volgt uitzien:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| Parameter | Beschrijving |
|---|---|
| fout | 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 waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren. |
| error_codes | Een lijst met STS-specifieke foutcodes die kunnen helpen bij diagnostische gegevens. |
| tijdstempel | 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. |
HTTP-statuscode
De volgende tabel bevat de HTTP-statuscodes die het tokenuitgifte-eindpunt retourneert. In sommige cases is de foutcode voldoende om de reactie te beschrijven, maar als er fouten zijn, moet u het bijbehorende JSON-document parseren en de bijbehorende foutcode onderzoeken.
| HTTP-code | Description |
|---|---|
| 400 | Standaard-HTTP-code. Wordt in de meeste cases gebruikt en wordt meestal veroorzaakt door een onjuiste aanvraag. Herstel de aanvraag en dien ze opnieuw in. |
| 401 | De verificatie is mislukt. De parameter client_secret ontbreekt bijvoorbeeld in de aanvraag. |
| 403 | Autorisatie is mislukt. De gebruiker heeft bijvoorbeeld geen machtiging voor toegang tot de resource. |
| 500 | Er is een interne fout opgetreden bij de service. Probeer de aanvraag opnieuw. |
Foutcodes voor tokeneindpuntfouten
| Foutcode | Description | Clientactie |
|---|---|---|
| invalid_request | Protocolfout, zoals een ontbrekende, vereiste parameter. | Herstel de aanvraag en dien ze opnieuw in |
| invalid_grant | De autorisatiecode is ongeldig of is verlopen. | Probeer een nieuwe aanvraag voor het /authorize-eindpunt |
| unauthorized_client | De geautoriseerde client is niet geautoriseerd om dit autorisatietoekenningstype te gebruiken. | Dit gebeurt meestal 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 | De clientauthenticatie is mislukt. | De clientreferenties zijn ongeldig. Laat de toepassingsbeheerder de referenties bijwerken. |
| unsupported_grant_type | De autorisatieserver biedt geen ondersteuning voor het autorisatietoekenningstype. | 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, Azure AD deze niet kan vinden of deze niet juist is geconfigureerd. | Dit 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. |
| interaction_required | Voor de aanvraag is gebruikersinteractie vereist. Er is bijvoorbeeld een extra verificatiestap vereist. | In plaats van een niet-interactieve aanvraag probeert u het opnieuw met een interactieve autorisatieaanvraag voor dezelfde resource. |
| 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 voorwaarde. |
Gebruik het toegangstoken voor toegang tot de resource
Nu u een access_token hebt verkregen, kunt u het token gebruiken in aanvragen voor web-API's door het op te geven in de Authorization-header. In de RFC 6750-specificatie wordt uitgelegd hoe u Bearer-tokens gebruikt in HTTP-aanvragen voor toegang tot beveiligde resources.
Voorbeeldaanvraag
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Foutreactie
Beveiligde resources die RFC 6750 implementeren, geven HTTP-statuscodes. Als de aanvraag geen verificatiereferenties bevat of als het token ontbreekt, bevat de reactie een WWW-Authenticate-header. Wanneer een aanvraag mislukt, reageert de resourceserver met de HTTP-statuscode en een foutcode.
Hier volgt een voorbeeld van een mislukte reactie wanneer de clientaanvraag geen Bearer-token bevat:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Foutparameters
| Parameter | Beschrijving |
|---|---|
| authorization_uri | De URI (fysiek eindpunt) van de autorisatieserver. Deze waarde wordt ook gebruikt als opzoeksleutel om meer informatie over de server op te halen uit een detectie-eindpunt. De client moet valideren of de autorisatieserver wordt vertrouwd. Wanneer de resource wordt beveiligd door Azure AD, is het voldoende om te controleren of de URL begint met |
| fout | Een foutcodewaarde die is gedefinieerd in sectie 5.2 van het OAuth 2.0-autorisatieframework. |
| error_description | Een gedetailleerdere beschrijving van de fout. Dit bericht is niet bedoeld om gebruiksvriendelijk te zijn. |
| resource_id | Retourneert de unieke id van de resource. De clienttoepassing kan deze id gebruiken als de waarde van de resource-parameter wanneer het een token voor de resource aangevraagd. Het is belangrijk dat de clienttoepassing deze waarde controleert, anders kan een kwaadwillende service mogelijk een aanval in de vorm van onrechtmatige uitbreiding van toegangsrechten veroorzaken De aanbevolen strategie voor het voorkomen van een aanval is om te controleren of de |
Foutcdes Bearer-schema
De RFC 6750-specificatie definieert de volgende fouten voor resources die gebruikmaken van de WWW-Authenticate-header en het Bearer-schema in de reactie.
| HTTP-statuscode | Foutcode | Description | Clientactie |
|---|---|---|---|
| 400 | invalid_request | De aanvraag is onjuist samengesteld. Het kan bijvoorbeeld zijn dat er een parameter ontbreekt of dat dezelfde parameter twee keer wordt gebruikt. | Herstel de fout op en probeer de aanvraag opnieuw. Dit type fout mag alleen optreden tijdens de ontwikkeling en moet tijdens de eerste test worden gedetecteerd. |
| 401 | invalid_token | Het toegangstoken ontbreekt, is ongeldig of is ingetrokken. De waarde van de parameter error_description biedt aanvullende details. | Vraag een nieuw token aan bij de autorisatieserver. Als het nieuwe token mislukt, is er een onverwachte fout opgetreden. Verzend een foutbericht naar de gebruiker en probeer het opnieuw na willekeurige vertragingen. |
| 403 | insufficient_scope | Het toegangstoken bevat niet de imitatiemachtigingen die zijn vereist voor toegang tot de resource. | Verzend een nieuwe autorisatieaanvraag naar het autorisatie-eindpunt. Als de reactie de bereikparameter bevat, gebruikt u de bereikwaarde in de aanvraag voor de resource. |
| 403 | insufficient_access | Het onderwerp van het token heeft niet de machtigingen die vereist zijn voor toegang tot de resource. | Vraag de gebruiker om een ander account te gebruiken of om machtigingen aan te vragen voor de opgegeven resource. |
De toegangstokens vernieuwen
Toegangstokens hebben een korte levensduur en moeten worden vernieuwd nadat ze zijn verlopen om toegang te houden tot resources. U kunt het access_token vernieuwen door een andere POST-aanvraag in te dienen bij het /token-eindpunt, maar deze keer geeft u de refresh_token in plaats van de code op. Vernieuwingstokens zijn geldig voor alle resources waarvoor uw client al toestemming heeft gegeven voor toegang. Er kan dus een vernieuwingstoken worden gebruikt dat is uitgegeven op een aanvraag voor resource=https://graph.microsoft.com om een nieuw toegangstoken voor resource=https://contoso.com/api aan te vragen.
Vernieuwingstokens hebben geen opgegeven levensduur. Normaal gesproken zijn de levensduur van vernieuwingstokens relatief lang. In sommige cases echter verlopen vernieuwingstokens, worden ze ingetrokken of ontbreken er voldoende bevoegdheden voor de gewenste actie. Uw toepassing moet fouten die door het tokenuitgifte-eindpunt worden geretourneerd, correct verwachten en verwerken.
Wanneer u een reactie ontvangt met een vernieuwingstokenfout, negeert u het huidige vernieuwingstoken en vraagt u een nieuwe autorisatiecode of toegangstoken aan. Met name bij het gebruik van een vernieuwingstoken in de toewijzingsstroom van de Autorisatiecode, als u een reactie met de foutcodes interaction_required of invalid_grant ontvangt, negeert u het vernieuwingstoken en vraagt u een nieuwe autorisatiecode aan.
Een voorbeeldaanvraag voor het tenantspecifieke eindpunt (u kunt ook het algemene eindpunt gebruiken) om een nieuw toegangstoken op te halen met behulp van een vernieuwingstoken ziet er als volgt uit:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Geslaagde reactie
Een geslaagde tokenreactie ziet er als volgt uit:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Parameter | Beschrijving |
|---|---|
| token_type | Het tokentype. De enige ondersteunde waarde is Bearer. |
| expires_in | De resterende levensduur van het token in seconden. Een typische waarde is 3600 (één uur). |
| expires_on | De datum en tijd waarop het token verloopt. De datum wordt weergegeven als het aantal seconden van 1970-01-01T0:0:0Z UTC tot de verlooptijd. |
| resource | Identificeert de beveiligde resource waartoe het toegangstoken kan worden gebruikt voor toegang. |
| scope | Imitatiemachtigingen die aan de systeemeigen cliënttoepassing zijn toegekend. De standaardmachtiging is user_impersonation. De eigenaar van de doelresource kan alternatieve waarden registreren in Azure AD. |
| access_token | Het nieuwe toegangstoken dat is aangevraagd. |
| refresh_token | Een nieuwe OAuth 2.0-refresh_token die kan worden gebruikt om nieuwe toegangstokens aan te vragen wanneer de toegangstokens in de reactie verloopt. |
Foutreacties
Een voorbeeld van een foutreactie kan er als volgt uitzien:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Parameter | Beschrijving |
|---|---|
| fout | 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 waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren. |
| error_codes | Een lijst met STS-specifieke foutcodes die kunnen helpen bij diagnostische gegevens. |
| tijdstempel | 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
Zie voorbeeldtoepassingen voor meer informatie over het Azure AD v1.0-eindpunt en het toevoegen van verificatie en autorisatie aan uw webtoepassingen en web-API's.