Auktorisera åtkomst till Azure Active Directory-webbprogram med beviljandeflödet för OAuth 2.0-kod
Varning
Det här innehållet gäller för den äldre Azure AD v1.0-slutpunkten. Använd Microsofts identitetsplattform för nya projekt.
Anteckning
Om du inte berättar för servern vilken resurs du planerar att anropa utlöser inte servern principerna för villkorsstyrd åtkomst för den resursen. För att kunna ha en MFA-utlösare måste du därför inkludera en resurs i url:en.
I Azure Active Directory (Azure AD) används OAuth 2.0 för att du ska kunna bevilja åtkomst till webbprogram och webb-API:er i din klientorganisation. Den här guiden är språkoberoende och beskriver hur du skickar och tar emot HTTP-meddelanden utan att använda något av våra bibliotek med öppen källkod.
OAuth 2.0-auktoriseringskodflödet beskrivs i avsnitt 4.1 i OAuth 2.0-specifikationen. Den används för att utföra autentisering och auktorisering i de flesta programtyper, inklusive webbappar och internt installerade appar.
Registrera ditt program med din AD-klient
Registrera först ditt program med din Azure Active Directory-klientorganisation (Azure AD). Det ger dig en program-ID för ditt program och låter det ta emot tokens.
Logga in på Azure-portalen.
Välj din Azure AD klientorganisation genom att välja ditt konto i det övre högra hörnet på sidan, följt av navigeringen Växla katalog och sedan välja lämplig klientorganisation.
- Hoppa över det här steget om du bara har en Azure AD klient under ditt konto, eller om du redan har valt rätt Azure AD klientorganisation.
I Azure Portal söker du efter och väljer Azure Active Directory.
I menyn till vänster i Azure Active Directory väljer du Appregistreringar och sedan Ny registrering.
Följ anvisningarna och skapa ett nytt program. Det spelar ingen roll om det är ett webbprogram eller en offentlig klient (mobilt & skrivbordsprogram) för den här självstudien, men om du vill ha specifika exempel för webbprogram eller offentliga klientprogram kan du läsa våra snabbstarter.
- Namn är appens namn och beskriver appen för användarna.
- Under Kontotyper som stöds väljer du Accounts in any organizational directory and personal Microsoft accounts (Konton i alla organisationskataloger och personliga Microsoft-konton).
- Ange omdirigerings-URI. För webbprogram är detta bas-URL:en för din app där användarna kan logga in. Till exempel
http://localhost:12345. För offentliga klienter (mobila & desktop) använder Azure AD den för att returnera tokensvar. Ange ett specifikt värde för ditt program. Till exempelhttp://MyFirstAADApp.
När du har slutfört registreringen tilldelar Azure AD programmet en unik klientidentifierare (program-ID). Du behöver det här värdet i nästa avsnitt, så kopiera det från programsidan.
Om du vill hitta ditt program i Azure Portal väljer du Appregistreringar och sedan Visa alla program.
OAuth 2.0-auktoriseringsflöde
På hög nivå ser hela auktoriseringsflödet för ett program ut ungefär så här:
Begära en auktoriseringskod
Auktoriseringskodflödet börjar med att klienten dirigerar användaren till /authorize slutpunkten. I den här begäran anger klienten de behörigheter som krävs för att hämta från användaren. Du kan hämta OAuth 2.0-auktoriseringsslutpunkten för din klientorganisation genom att välja Appregistreringar > slutpunkter i 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 | Typ | Description |
|---|---|---|
| tenant | krävs | Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in i programmet. De tillåtna värdena är klientidentifierare, till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller commoncontoso.onmicrosoft.com för klientoberoende token |
| client_id | krävs | Det program-ID som tilldelades din app när du registrerade det med Azure AD. Du hittar detta i Azure Portal. Klicka på Azure Active Directory i sidofältet för tjänster, klicka på Appregistreringar och välj programmet. |
| response_type | krävs | Måste inkluderas code för auktoriseringskodflödet. |
| redirect_uri | Rekommenderas | Appens redirect_uri, där autentiseringssvar kan skickas och tas emot av din app. Den måste exakt matcha en av de redirect_uris som du registrerade i portalen, förutom att den måste vara URL-kodad. För interna & mobilappar bör du använda standardvärdet https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | valfri | Anger den metod som ska användas för att skicka tillbaka den resulterande token till din app. Kan vara query, fragmenteller form_post. query tillhandahåller koden som en frågesträngsparameter på din omdirigerings-URI. Om du begär en ID-token med hjälp av det implicita flödet kan du inte använda query det som anges i OpenID-specifikationen. Om du bara begär koden kan du använda query, fragmenteller form_post. form_post kör ett POST som innehåller koden till din omdirigerings-URI. Standardvärdet är query för ett kodflöde. |
| state | Rekommenderas | Ett värde som ingår i begäran som också returneras i tokensvaret. Ett slumpmässigt genererat unikt värde används vanligtvis för att förhindra förfalskningsattacker mellan webbplatser. Tillståndet används också för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn som användaren var på. |
| resource | Rekommenderas | App-ID-URI för målwebb-API:et (skyddad resurs). Om du vill hitta app-ID:n klickar du på Azure Active Directory i Azure Portal, klickar på Programregistreringar, öppnar programmets inställningssida och klickar sedan på Egenskaper. Det kan också vara en extern resurs som https://graph.microsoft.com. Detta krävs i någon av auktoriserings- eller tokenbegäranden. För att säkerställa att färre autentiseringsprompter placerar den i auktoriseringsbegäran för att säkerställa att medgivande tas emot från användaren. |
| omfång | Ignoreras | För v1 Azure AD-appar måste omfång konfigureras statiskt i Azure Portal under programinställningar, nödvändiga behörigheter. |
| Snabb | valfri | Ange vilken typ av användarinteraktion som krävs. Giltiga värden är: inloggning: Användaren bör uppmanas att autentisera igen. select_account: Användaren uppmanas att välja ett konto, vilket avbryter enkel inloggning. Användaren kan välja ett befintligt inloggningskonto, ange sina autentiseringsuppgifter för ett sparat konto eller välja att använda ett annat konto helt och hållet. medgivande: Användarmedgivande har beviljats, men måste uppdateras. Användaren bör uppmanas att samtycka. admin_consent: En administratör bör uppmanas att godkänna för alla användare i organisationen |
| login_hint | valfri | Kan användas för att fylla i fältet användarnamn/e-postadress på inloggningssidan i förväg för användaren, om du känner till användarens användarnamn i förväg. Ofta använder appar den här parametern under omautentisering, eftersom de redan har extraherat användarnamnet från en tidigare inloggning med anspråket preferred_username . |
| domain_hint | valfri | Ger en ledtråd om klientorganisationen eller domänen som användaren ska använda för att logga in. Värdet för domain_hint är en registrerad domän för klientorganisationen. Om klientorganisationen är federerad till en lokal katalog omdirigeras AAD till den angivna klientfederationsservern. |
| code_challenge_method | Rekommenderas | Den metod som används för att koda code_verifier för parametern code_challenge . Kan vara en av plain eller S256. Om detta utelämnas code_challenge antas det vara klartext om code_challenge det ingår. Azure AAD v1.0 stöder både plain och S256. Mer information finns i PKCE RFC. |
| code_challenge | Rekommenderas | Används för att skydda auktoriseringskodsbidrag via proof key for Code Exchange (PKCE) från en intern eller offentlig klient. Krävs om code_challenge_method ingår. Mer information finns i PKCE RFC. |
Anteckning
Om användaren är en del av en organisation kan en administratör i organisationen samtycka eller avböja för användarens räkning, eller tillåta användaren att samtycka. Användaren ges möjlighet att godkänna endast när administratören tillåter det.
Nu uppmanas användaren att ange sina autentiseringsuppgifter och godkänna de behörigheter som begärs av appen i Azure Portal. När användaren autentiserar och ger sitt medgivande skickar Azure AD ett svar till din app på redirect_uri adressen i din begäran med koden.
Lyckat svar
Ett lyckat svar kan se ut så här:
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 | Beskrivning |
|---|---|
| admin_consent | Värdet är Sant om en administratör samtyckt till en begäran om medgivande. |
| kod | Den auktoriseringskod som programmet begärde. Programmet kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. |
| session_state | Ett unikt värde som identifierar den aktuella användarsessionen. Det här värdet är ett GUID, men bör behandlas som ett täckande värde som skickas utan undersökning. |
| state | Om en tillståndsparameter ingår i begäran bör samma värde visas i svaret. Det är en bra idé för programmet att kontrollera att tillståndsvärdena i begäran och svaret är identiska innan svaret används. Detta hjälper till att identifiera CSRF-attacker (Cross-Site Request Forgery) mot klienten. |
Felsvar
Felsvar kan också skickas till redirect_uri så att programmet kan hantera dem på rätt sätt.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Beskrivning |
|---|---|
| fel | Ett felkodvärde som definierats i avsnitt 5.2 i OAuth 2.0 Authorization Framework. I nästa tabell beskrivs felkoderna som Azure AD returnerar. |
| error_description | En mer detaljerad beskrivning av felet. Det här meddelandet är inte avsett att vara användarvänligt. |
| state | Tillståndsvärdet är ett slumpmässigt genererat värde som inte återanvänds och som skickas i begäran och returneras i svaret för att förhindra csrf-attacker (cross-site request forgery). |
Felkoder för auktoriseringsslutpunktsfel
I följande tabell beskrivs de olika felkoder som kan returneras i parametern error för felsvaret.
| Felkod | Description | Klientåtgärd |
|---|---|---|
| invalid_request | Protokollfel, till exempel en parameter som saknas. | Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis upp under den första testningen. |
| unauthorized_client | Klientprogrammet får inte begära en auktoriseringskod. | Detta inträffar vanligtvis när klientprogrammet inte är registrerat i Azure AD eller inte läggs till i användarens Azure AD klientorganisation. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD. |
| access_denied | Resursägaren nekade medgivande | Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren samtycker. |
| unsupported_response_type | Auktoriseringsservern stöder inte svarstypen i begäran. | Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis upp under den första testningen. |
| server_error | Servern påträffade ett oväntat fel. | Försök igen med begäran. Dessa fel kan bero på tillfälliga villkor. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt fel. |
| temporarily_unavailable | Servern är tillfälligt för upptagen för att hantera begäran. | Försök igen med begäran. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt villkor. |
| invalid_resource | Målresursen är ogiltig eftersom den inte finns, Azure AD inte kan hitta den eller så är den inte korrekt konfigurerad. | Detta anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD. |
Använd auktoriseringskoden för att begära en åtkomsttoken
Nu när du har skaffat en auktoriseringskod och har beviljats behörighet av användaren kan du lösa in koden för en åtkomsttoken till önskad resurs genom att skicka en POST-begäran till /token slutpunkten:
// 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 | Typ | Description |
|---|---|---|
| tenant | krävs | Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in på programmet. De tillåtna värdena är till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 klientidentifierare eller contoso.onmicrosoft.comcommon för klientoberoende token |
| client_id | krävs | Det program-ID som tilldelats din app när du registrerade det med Azure AD. Du hittar detta i Azure Portal. Program-ID:t visas i inställningarna för appregistreringen. |
| grant_type | krävs | Måste vara authorization_code för auktoriseringskodflödet. |
| kod | krävs | Det authorization_code som du förvärvade i föregående avsnitt |
| redirect_uri | krävs | En redirect_uriregistrerad i klientprogrammet. |
| client_secret | krävs för webbappar, tillåts inte för offentliga klienter | Programhemligheten som du skapade i Azure Portal för din app under Nycklar. Den kan inte användas i en intern app (offentlig klient), eftersom client_secrets inte kan lagras på ett tillförlitligt sätt på enheter. Det krävs för webbappar och webb-API:er (alla konfidentiella klienter), som har möjlighet att lagra client_secret säkert på serversidan. Den client_secret ska vara URL-kodad innan den skickas. |
| resource | Rekommenderas | App-ID-URI för målwebb-API:et (skyddad resurs). Om du vill hitta app-ID:n klickar du på Azure Active Directory i Azure Portal, klickar på Programregistreringar, öppnar programmets inställningssida och klickar sedan på Egenskaper. Det kan också vara en extern resurs som https://graph.microsoft.com. Detta krävs i någon av auktoriserings- eller tokenbegäranden. För att säkerställa att färre autentiseringsprompter placerar den i auktoriseringsbegäran för att säkerställa att medgivande tas emot från användaren. Om både auktoriseringsbegäran och tokenbegäran finns i måste resursens parametrar matcha. |
| code_verifier | valfri | Samma code_verifier som användes för att få authorization_code. Krävs om PKCE användes i begäran om beviljande av auktoriseringskod. Mer information finns i PKCE RFC |
Om du vill hitta app-ID:n klickar du på Azure Active Directory i Azure Portal, klickar på Programregistreringar, öppnar programmets inställningssida och klickar sedan på Egenskaper.
Lyckat svar
Azure AD returnerar en åtkomsttoken vid ett lyckat svar. För att minimera nätverksanrop från klientprogrammet och deras associerade svarstid ska klientprogrammet cachelagrar åtkomsttoken för tokenlivslängden som anges i OAuth 2.0-svaret. Om du vill fastställa tokenlivslängden använder du antingen parametervärdena expires_in eller expires_on .
Om en webb-API-resurs returnerar en invalid_token felkod kan detta tyda på att resursen har fastställt att token har upphört att gälla. Om klientens och resursens klocktider är olika (kallas för "tidssnedställning" kan resursen överväga att token har upphört att gälla innan token rensas från klientcachen. Om detta inträffar rensar du token från cachen, även om den fortfarande ligger inom den beräknade livslängden.
Ett lyckat svar kan se ut så här:
{
"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 | Beskrivning |
|---|---|
| access_token | Begärd åtkomsttoken. Det här är en täckande sträng – den beror på vad resursen förväntar sig att ta emot och är inte avsedd för klienten att titta på. Appen kan använda denna token för att autentisera till den skyddade resursen, till exempel ett webb-API. |
| token_type | Anger tokentypvärdet. Den enda typ som Azure AD stöder är Bearer. Mer information om ägartoken finns i OAuth2.0 Authorization Framework: Bearer Token Usage (RFC 6750) |
| expires_in | Hur länge åtkomsttoken är giltig (i sekunder). |
| expires_on | Den tid då åtkomsttoken upphör att gälla. Datumet representeras som antalet sekunder från 1970-01-01T0:0:0Z UTC fram till förfallotiden. Det här värdet används för att fastställa livslängden för cachelagrade token. |
| resource | App-ID-URI för webb-API:et (skyddad resurs). |
| omfång | Personifieringsbehörigheter som beviljats klientprogrammet. Standardbehörigheten är user_impersonation. Ägaren till den skyddade resursen kan registrera ytterligare värden i Azure AD. |
| refresh_token | En OAuth 2.0-uppdateringstoken. Appen kan använda denna token för att hämta ytterligare åtkomsttoken när den aktuella åtkomsttoken upphör att gälla. Uppdateringstoken är långlivade och kan användas för att behålla åtkomsten till resurser under längre tidsperioder. |
| id_token | En osignerad JSON-webbtoken (JWT) som representerar en ID-token. Appen kan base64Url avkoda segmenten för denna token för att begära information om användaren som loggade in. Appen kan cachelagrat värdena och visa dem, men den bör inte förlita sig på dem för auktorisering eller säkerhetsgränser. |
Mer information om JSON-webbtoken finns i JWT IETF-utkastspecifikationen. Mer information om id_tokensfinns i flödet v1.0 OpenID Connect.
Felsvar
Slutpunktsfel för tokenutfärdning är HTTP-felkoder, eftersom klienten anropar slutpunkten för tokenutfärdning direkt. Förutom HTTP-statuskoden returnerar Azure AD slutpunkt för tokenutfärdning också ett JSON-dokument med objekt som beskriver felet.
Ett exempel på ett felsvar kan se ut så här:
{
"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 | Beskrivning |
|---|---|
| fel | En felkodsträng som kan användas för att klassificera typer av fel som inträffar och som kan användas för att reagera på fel. |
| error_description | Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel. |
| error_codes | En lista över STS-specifika felkoder som kan hjälpa dig med diagnostik. |
| timestamp | Tidpunkten då felet inträffade. |
| trace_id | En unik identifierare för begäran som kan hjälpa dig med diagnostik. |
| correlation_id | En unik identifierare för begäran som kan hjälpa till med diagnostik mellan komponenter. |
HTTP-statuskoder
I följande tabell visas de HTTP-statuskoder som slutpunkten för tokenutfärdning returnerar. I vissa fall räcker felkoden för att beskriva svaret, men om det finns fel måste du parsa det tillhörande JSON-dokumentet och undersöka dess felkod.
| HTTP-kod | Beskrivning |
|---|---|
| 400 | Http-standardkod. Används i de flesta fall och beror vanligtvis på en felaktig begäran. Åtgärda och skicka begäran igen. |
| 401 | Autentiseringen misslyckades. Begäran saknar till exempel parametern client_secret. |
| 403 | Auktoriseringen misslyckades. Användaren har till exempel inte behörighet att komma åt resursen. |
| 500 | Ett internt fel har uppstått i tjänsten. Försök igen med begäran. |
Felkoder för tokenslutpunktsfel
| Felkod | Description | Klientåtgärd |
|---|---|---|
| invalid_request | Protokollfel, till exempel en obligatorisk parameter som saknas. | Åtgärda och skicka begäran igen |
| invalid_grant | Auktoriseringskoden är ogiltig eller har upphört att gälla. | Prova en ny begäran till /authorize slutpunkten |
| unauthorized_client | Den autentiserade klienten har inte behörighet att använda den här typen av auktoriseringsbeviljande. | Detta inträffar vanligtvis när klientprogrammet inte är registrerat i Azure AD eller inte läggs till i användarens Azure AD klientorganisation. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD. |
| invalid_client | Klientautentiseringen misslyckades. | Klientens autentiseringsuppgifter är inte giltiga. För att åtgärda detta uppdaterar programadministratören autentiseringsuppgifterna. |
| unsupported_grant_type | Auktoriseringsservern stöder inte beviljandetypen för auktorisering. | Ändra beviljandetyp i begäran. Den här typen av fel ska endast inträffa under utvecklingen och identifieras under den första testningen. |
| invalid_resource | Målresursen är ogiltig eftersom den inte finns, Azure AD inte kan hitta den eller så är den inte korrekt konfigurerad. | Detta anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren att installera programmet och lägga till det i Azure AD. |
| interaction_required | Begäran kräver användarinteraktion. Ett ytterligare autentiseringssteg krävs till exempel. | Försök igen med en interaktiv auktoriseringsbegäran för samma resurs i stället för en icke-interaktiv begäran. |
| temporarily_unavailable | Servern är tillfälligt för upptagen för att hantera begäran. | Försök igen med begäran. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt villkor. |
Använda åtkomsttoken för att komma åt resursen
Nu när du har hämtat en access_tokenkan du använda token i begäranden till webb-API:er genom att inkludera den i Authorization rubriken. RFC 6750-specifikationen förklarar hur du använder ägartoken i HTTP-begäranden för att få åtkomst till skyddade resurser.
Exempelbegäran
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Felsvar
Skyddade resurser som implementerar RFC 6750 utfärdar HTTP-statuskoder. Om begäran inte innehåller autentiseringsuppgifter eller om token saknas innehåller svaret ett WWW-Authenticate huvud. När en begäran misslyckas svarar resursservern med HTTP-statuskoden och en felkod.
Följande är ett exempel på ett misslyckat svar när klientbegäran inte innehåller ägartoken:
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.",
Felparametrar
| Parameter | Beskrivning |
|---|---|
| authorization_uri | URI :n (fysisk slutpunkt) för auktoriseringsservern. Det här värdet används också som en uppslagsnyckel för att få mer information om servern från en identifieringsslutpunkt. Klienten måste verifiera att auktoriseringsservern är betrodd. När resursen skyddas av Azure AD räcker det att kontrollera att URL:en börjar med |
| fel | Ett felkodvärde som definierats i avsnitt 5.2 i OAuth 2.0 Authorization Framework. |
| error_description | En mer detaljerad beskrivning av felet. Det här meddelandet är inte avsett att vara användarvänligt för slutanvändare. |
| resource_id | Returnerar resursens unika identifierare. Klientprogrammet kan använda den här identifieraren som värdet för parametern resource när den begär en token för resursen. Det är viktigt att klientprogrammet verifierar det här värdet, annars kan en skadlig tjänst orsaka en attack med utökade privilegier Den rekommenderade strategin för att förhindra ett angrepp är att verifiera att |
Felkoder för ägarschema
RFC 6750-specifikationen definierar följande fel för resurser som använder WWW-Authenticate-huvudet och ägarschemat i svaret.
| HTTP-statuskod | Felkod | Description | Klientåtgärd |
|---|---|---|---|
| 400 | invalid_request | Begäran är inte korrekt utformad. Den kanske till exempel saknar en parameter eller använder samma parameter två gånger. | Åtgärda felet och försök igen. Den här typen av fel bör endast inträffa under utvecklingen och identifieras i den inledande testningen. |
| 401 | invalid_token | Åtkomsttoken saknas, är ogiltig eller har återkallats. Värdet för parametern error_description innehåller ytterligare information. | Begär en ny token från auktoriseringsservern. Om den nya token misslyckas har ett oväntat fel inträffat. Skicka ett felmeddelande till användaren och försök igen efter slumpmässiga fördröjningar. |
| 403 | insufficient_scope | Åtkomsttoken innehåller inte de personifieringsbehörigheter som krävs för att få åtkomst till resursen. | Skicka en ny auktoriseringsbegäran till auktoriseringsslutpunkten. Om svaret innehåller omfångsparametern använder du omfångsvärdet i begäran till resursen. |
| 403 | insufficient_access | Ämnet för token har inte de behörigheter som krävs för att komma åt resursen. | Uppmana användaren att använda ett annat konto eller att begära behörigheter till den angivna resursen. |
Uppdatera åtkomsttoken
Åtkomsttoken är kortvariga och måste uppdateras när de upphör att gälla för att fortsätta komma åt resurser. Du kan uppdatera access_token genom att skicka en annan POST begäran till slutpunkten, men den /token här gången anger du refresh_token i stället för code. Uppdateringstoken är giltiga för alla resurser som klienten redan har getts medgivande till åtkomst. Därför kan en uppdateringstoken som utfärdats för en begäran för användas för resource=https://graph.microsoft.com att begära en ny åtkomsttoken för resource=https://contoso.com/api.
Uppdateringstoken har inte angivna livslängder. Normalt är livslängden för uppdateringstoken relativt lång. I vissa fall upphör dock uppdateringstoken att gälla, återkallas eller saknar tillräckliga privilegier för den önskade åtgärden. Programmet måste förvänta sig och hantera fel som returneras av slutpunkten för tokenutfärdning korrekt.
När du får ett svar med ett uppdateringstokenfel tar du bort den aktuella uppdateringstoken och begär en ny auktoriseringskod eller åtkomsttoken. När du använder en uppdateringstoken i beviljandeflödet för auktoriseringskod tar du bort uppdateringstoken och begär en ny auktoriseringskod om du får ett svar med felkoderna interaction_required eller invalid_grant .
En exempelbegäran till den klientspecifika slutpunkten (du kan också använda den gemensamma slutpunkten) för att hämta en ny åtkomsttoken med en uppdateringstoken ser ut så här:
// 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
Lyckat svar
Ett lyckat tokensvar ser ut så här:
{
"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 | Beskrivning |
|---|---|
| token_type | Tokentypen. Det enda värde som stöds är bearer. |
| expires_in | Den återstående livslängden för token i sekunder. Ett typiskt värde är 3600 (en timme). |
| expires_on | Datum och tid då token upphör att gälla. Datumet representeras som antalet sekunder från 1970-01-01T0:0:0Z UTC fram till förfallotiden. |
| resource | Identifierar den skyddade resurs som åtkomsttoken kan användas för åtkomst. |
| omfång | Personifieringsbehörigheter som beviljats det inbyggda klientprogrammet. Standardbehörigheten är user_impersonation. Målresursens ägare kan registrera alternativa värden i Azure AD. |
| access_token | Den nya åtkomsttoken som begärdes. |
| refresh_token | En ny OAuth 2.0-refresh_token som kan användas för att begära nya åtkomsttoken när den i det här svaret upphör att gälla. |
Felsvar
Ett exempel på ett felsvar kan se ut så här:
{
"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 | Beskrivning |
|---|---|
| fel | En felkodsträng som kan användas för att klassificera typer av fel som inträffar och som kan användas för att reagera på fel. |
| error_description | Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel. |
| error_codes | En lista över STS-specifika felkoder som kan hjälpa dig med diagnostik. |
| timestamp | Tidpunkten då felet inträffade. |
| trace_id | En unik identifierare för begäran som kan hjälpa dig med diagnostik. |
| correlation_id | En unik identifierare för begäran som kan hjälpa till med diagnostik mellan komponenter. |
En beskrivning av felkoderna och den rekommenderade klientåtgärden finns i Felkoder för tokenslutpunktsfel.
Nästa steg
Mer information om Azure AD v1.0-slutpunkten och hur du lägger till autentisering och auktorisering i dina webbprogram och webb-API:er finns i exempelprogram.