Not
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
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.
Anmärkning
Om du inte talar om för servern vilken resurs du planerar att anropa utlöser servern inte principerna för villkorsstyrd åtkomst för den resursen. För att kunna ha en MFA-utlösare måste du inkludera en resurs i url:en.
Azure Active Directory (Azure AD) använder OAuth 2.0 för att tillåta åtkomst till webbprogram och webb-API:er i din Azure AD-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 din applikation med din AD-klient
Registrera först ditt program hos din klientorganisation i Azure Active Directory (Azure AD). Detta ger dig ett program-ID för ditt program och gör det möjligt för det att ta emot token.
Logga in på Azure-portalen.
Välj din Azure AD-klient genom att välja ditt konto i det övre högra hörnet på sidan, följt av att välja Växla katalog och sedan välja lämplig klient.
- Hoppa över det här steget om du bara har en Azure AD-klient under ditt konto eller om du redan har valt lämplig Azure AD-klientorganisation.
I Azure-portalen söker du efter och väljer Azure Active Directory-.
Välj Appregistreringari Azure Active Directory vänstra menyn och välj sedan Ny registrering.
Följ anvisningarna och skapa ett nytt program. Det spelar ingen roll om det är ett webbprogram eller ett klientprogram för allmänheten (mobilt & skrivbord) för den här handledningen, men om du vill ha specifika exempel för webbprogram eller klientprogram för allmänheten kan du läsa våra snabbstartsguider.
- Namn är programnamnet och beskriver ditt program för slutanvä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:n. För webbprogram är det här bas-URL:en för din app där användarna kan logga in. Till exempel
http://localhost:12345. För offentlig klient (mobil & desktop) använder Azure AD den för att returnera tokensvar. Ange ett värde som är specifikt för ditt program. Till exempelhttp://MyFirstAADApp.
När du har slutfört registreringen tilldelar Azure AD ditt program 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-portalen väljer du Appregistreringaroch väljer 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 klient genom att välja Appregistreringar > slutpunkter i Azure-portalen.
// 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 | Beskrivning |
|---|---|---|
| hyresgäst | obligatorisk | 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 klientidentifierare, till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller contoso.onmicrosoft.com eller common för klientoberoende token |
| klient-id | obligatorisk | Program-ID:t som tilldelades din app när du registrerade det med Azure AD. Du hittar detta i Azure-portalen. Klicka på Azure Active Directory- i sidofältet för tjänster, klicka på Appregistreringaroch välj programmet. |
| response_type | obligatorisk | Måste inkluderas code för auktoriseringskodflödet. |
| omdirigerings_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 du registrerade i portalen, förutom att den måste vara URL-kodad. För interna & mobilappar bör du använda standardvärdet för https://login.microsoftonline.com/common/oauth2/nativeclient. |
| svarsläge | valfri | Anger vilken 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 det implicita flödet kan du inte använda query enligt OpenID-specifikationen. Om du bara begär koden kan du använda query, fragmenteller form_post.
form_post kör en POST som innehåller koden till din omdirigerings-URI. Standardvärdet är query för ett kodflöde. |
| tillstånd | 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 de var på. |
| resurs | rekommenderas | App-ID-URI:n för målwebb-API:et (skyddad resurs). Klicka på Azure Active Directoryi Azure-portalen, klicka på Programregistreringar, öppna den sidan Inställningar för applikationen och välj sedan 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 minska antalet autentiseringsförfrågningar, inkludera dem i auktoriseringsbegäran för att ta emot användarens medgivande. |
| omfattning | ignorerade | För v1 Azure AD-appar måste omfång konfigureras statiskt i Azure-portalen under program Inställningar, Nödvändiga behörigheter. |
| skyndsam | 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 och avbryta enkel inloggning. Användaren kan välja ett befintligt loggat konto, ange sina autentiseringsuppgifter för ett ihågkomet 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 |
| inloggningsförslag | valfri | Kan användas för att i förväg fylla i fältet användarnamn/e-postadress på inloggningssidan för användaren, om du känner till användarnamnet i förväg. Oftast använder appar den här parametern under återautentisering, efter att ha extraherat användarnamnet från en tidigare inloggning med hjälp av preferred_username-klämmen. |
| domäninformation | valfri | Ger en ledtråd om klientorganisationen eller domänen som användaren ska använda sig av för att logga in. Värdet för domain_hint är en registrerad domän för klientorganisationen. Om klientorganisationen är federerad med en specifik lokal katalog, omdirigeras AAD till den specificerade federationsservern för klientorganisationen. |
| metod för kodutmaning | 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 code_challenge utesluts, så antas det vara klartext om code_challenge ingår. Azure AAD v1.0 stöder både plain och S256. Mer information finns i PKCE RFC. |
| kodutmaning | rekommenderas | Används för att säkerställa auktoriseringskoder via Proof Key for Code Exchange (PKCE) från en inbyggd eller offentlig klient. Krävs om code_challenge_method ingår. Mer information finns i PKCE RFC. |
Anmärkning
Om användaren är en del av en organisation kan en administratör i organisationen samtycka till eller avböja för användarens räkning, eller tillåta användaren att samtycka. Användaren får endast möjlighet att ge sitt medgivande när administratören tillåter det.
I det här läget uppmanas användaren att ange sina autentiseringsuppgifter och samtycka till de behörigheter som begärs av appen i Azure-portalen. När användaren autentiserar och beviljar medgivande skickar Azure AD ett svar till din app på den 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 |
|---|---|
| administratörens samtycke | Värdet är sant om en administratör har samtyckt till en begäran om samtycke. |
| kod | Auktoriseringskoden 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 ogenomskinligt värde som skickas utan att undersökas. |
| tillstånd | 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 felkodsvärde som definierats i avsnitt 5.2 i OAuth 2.0 Authorization Framework. I nästa tabell beskrivs felkoderna som Azure AD returnerar. |
| felbeskrivning | En mer detaljerad beskrivning av felet. Det här meddelandet är inte avsett att vara användarvänligt. |
| tillstånd | Tillståndsvärdet är ett slumpmässigt genererat och ej återanvänt värde som skickas med begäran och returneras med svaret för att förhindra cross-site request forgery (CSRF)-angrepp. |
Felkoder för auktoriseringsslutpunktsfel
I följande tabell beskrivs de olika felkoder som kan returneras i parametern error för felsvaret.
| Felkod | Beskrivning | Klientåtgärd |
|---|---|---|
| ogiltig_förfrågan | Protokollfel, till exempel en parameter som saknas. | Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel och fångas vanligtvis under den första testningen. |
| obehörig_klient | 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 med instruktioner för att installera programmet och lägga till det i Azure AD. |
| åtkomst nekad | Resursägaren nekades medgivande | Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren samtycker. |
| otillåten_svarstyp | 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 under den första testningen. |
| serverfel | 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. |
| tillfälligt otillgänglig | 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. |
| ogiltig resurs | Målresursen är ogiltig eftersom den inte finns, Azure AD kan inte hitta den eller så är den inte korrekt konfigurerad. | Detta indikerar att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren med instruktioner för 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 den önskade resursen 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 | Beskrivning |
|---|---|---|
| hyresgäst | obligatorisk | 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 klientidentifierare, till exempel 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 eller contoso.onmicrosoft.com eller common för klientoberoende token |
| klient-id | obligatorisk | Program-ID:t som tilldelades din app när du registrerade det med Azure AD. Du hittar detta i Azure-portalen. Program-ID visas i inställningarna för appregistreringen. |
| beviljandetyp | obligatorisk | Måste vara authorization_code för auktoriseringskodflödet. |
| kod | obligatorisk | Den authorization_code som du anskaffade i det föregående avsnittet |
| redirect_uri (omdirigerings-URI) | obligatorisk | Något redirect_uriregistrerades i klientprogrammet. |
| klienthemlighet | krävs för webbappar, inte tillåtna för offentliga klienter | Programhemligheten som du skapade i Azure-portalen 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. Client_secret ska vara URL-kodad innan den skickas. |
| resurs | rekommenderas | App-ID-URI:n för målwebb-API:et (skyddad resurs). Klicka på Azure Active Directoryi Azure-portalen, klicka på Programregistreringar, öppna den sidan Inställningar för applikationen och välj sedan 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 minska antalet autentiseringsförfrågningar, inkludera dem i auktoriseringsbegäran för att ta emot användarens medgivande. Om i både auktoriseringsbegäran och tokenbegäran måste resursparametrarna matcha. |
| kodverifiering | valfri | Det är samma code_verifier som användes för att erhålla authorization_code. Krävs om PKCE användes i begäran om beviljande av auktoriseringskod. Mer information finns i PKCE RFC- |
Klicka på Azure Active Directoryi Azure-portalen, klicka på Programregistreringar, öppna den sidan Inställningar för applikationen och välj sedan 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 bör klientprogrammet cachelagrar åtkomsttoken för den tokenlivslängd som anges i OAuth 2.0-svaret. Om du vill fastställa tokens livslängd 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 "tidsförskjutning" 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 cacheminnet, ä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 |
|---|---|
| åtkomsttoken | Den begärda åtkomsttoken. Det här är en ogenomskinlig 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 den här token för att autentisera till den skyddade resursen, till exempel ett webb-API. |
| typ_av_token | Anger värdet för tokentyp. 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) |
| går ut om | Hur länge åtkomsttoken är giltig (i sekunder). |
| utgår den | Tiden då åtkomsttoken upphör att gälla. Datumet representeras som antalet sekunder från 1970-01-01T0:0:0Z UTC till förfallotiden. Det här värdet används för att fastställa livslängden för cachelagrade token. |
| resurs | App-ID-URI:n för webb-API:et (skyddad resurs). |
| omfattning | Imitationsbehörigheter som beviljats klientapplikationen. Standardbehörigheten är user_impersonation. Ägaren till den skyddade resursen kan registrera ytterligare värden i Azure AD. |
| uppdaterings-token | En OAuth 2.0-uppfräschningskod. Appen kan använda den här token för att hämta ytterligare åtkomsttoken när den aktuella åtkomsttoken har upphört 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 Web Token (JWT) som representerar en ID-token. Appen kan base64Url avkoda segmenten för den här 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 v1.0 OpenID Connect-flödet.
Felsvar
Slutpunktsfel för tokenutfärding är HTTP-felkoder, eftersom klienten anropar slutpunkten för tokenutfärdning direkt. Förutom HTTP-statuskoden returnerar slutpunkten för Utfärdande av Azure AD-token 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 felkodssträ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. |
| felbeskrivning | Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel. |
| felkoder | En lista över STS-specifika felkoder som kan hjälpa dig med diagnostik. |
| tidsstämpel | 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ärding returnerar. I vissa fall räcker det med 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 | Beskrivning | Klientåtgärd |
|---|---|---|
| ogiltig_förfrågan | Protokollfel, till exempel en parameter som saknas. | Åtgärda och skicka begäran igen |
| ogiltigt_bidrag | Auktoriseringskoden är ogiltig eller har upphört att gälla. | Prova en ny begäran till slutpunkten /authorize |
| obehörig_klient | 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 med instruktioner för att installera programmet och lägga till det i Azure AD. |
| ogiltig_klient | Klientautentiseringen misslyckades. | Klientautentiseringsuppgifterna är inte giltiga. Programadministratören uppdaterar autentiseringsuppgifterna för att åtgärda problemet. |
| otillåten_bidrags_typ | Auktoriseringsservern stöder inte typen av auktoriseringsbidrag. | Ändra beviljandetyp i begäran. Den här typen av fel bör endast inträffa under utvecklingen och identifieras under den första testningen. |
| ogiltig resurs | Målresursen är ogiltig eftersom den inte finns, Azure AD kan inte hitta den eller så är den inte korrekt konfigurerad. | Detta indikerar att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan uppmana användaren med instruktioner för att installera programmet och lägga till det i Azure AD. |
| Interaktion krävs | 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. |
| tillfälligt otillgänglig | 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 skaffat en access_tokenkan du använda denna token i begäranden till webb-API:er genom att inkludera den i Authorization-headern. Specifikationen RFC 6750 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 misslyckad svar när klientens begäran inte innehåller bearertoken:
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 |
|---|---|
| auktoriserings_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 felkodsvärde som definierats i avsnitt 5.2 i OAuth 2.0 Authorization Framework. |
| felbeskrivning | En mer detaljerad beskrivning av felet. Det här meddelandet är inte avsett att vara användarvänligt. |
| 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 utökade privilegier angrepp Den rekommenderade strategin för att förhindra ett angrepp är att kontrollera att |
Felkoder för bärarskeema
RFC 6750-specifikationen definierar följande fel för resurser som använder WWW-Authenticate-huvudet och bearer-schemat i svaret.
| HTTP-statuskod | Felkod | Beskrivning | Klientåtgärd |
|---|---|---|---|
| 400 | ogiltig_förfrågan | 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 första testningen. |
| 401 | ogiltig_token | Åtkomsttoken saknas, är ogiltig eller har återkallats. Värdet för parametern error_description ger 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 | otillräcklig behörighet | Åtkomsttoken innehåller inte de personifieringsbehörigheter som krävs för å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 | otillräcklig åtkomst | Ämnet för token har inte de behörigheter som krävs för att komma åt resursen. | Be användaren att använda ett annat konto eller begära behörigheter till den angivna resursen. |
Uppdatera åtkomsttoken
Åtkomsttoken är kortvariga och måste uppdateras när de har upphört 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 /token slutpunkten, men den här gången anger du refresh_token i stället för code. Uppfriskningstoken är giltiga för alla resurser som din klient redan har fått medgivande att komma åt. Därför kan en uppfriskningstoken som utfärdats vid en begäran om resource=https://graph.microsoft.com användas för att begära en ny åtkomsttoken för resource=https://contoso.com/api.
Uppdaterings-token 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äcklig behörighet 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 auktoriseringskodens beviljandeflöde 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 vanliga 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 |
|---|---|
| typ_av_token | Tokentypen. Det enda värde som stöds är bärare. |
| går ut om | Den återstående livslängden för token i sekunder. Ett typiskt värde är 3600 (en timme). |
| utgår den | Datum och tid då token upphör att gälla. Datumet representeras som antalet sekunder från 1970-01-01T0:0:0Z UTC till förfallotiden. |
| resurs | Identifierar den skyddade resurs som åtkomsttoken kan användas för åtkomst. |
| omfattning | Personifieringsbehörigheter som beviljats det interna klientprogrammet. Standardbehörigheten är user_impersonation. Målresursens ägare kan registrera alternativa värden i Azure AD. |
| åtkomsttoken | 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 felkodssträ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. |
| felbeskrivning | Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel. |
| felkoder | En lista över STS-specifika felkoder som kan hjälpa dig med diagnostik. |
| tidsstämpel | 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.