Microsofts identitetsplattform och kodflöde för OAuth 2.0-auktorisering
OAuth 2.0-auktoriseringskodens beviljandetyp, eller autentiseringskodflödet, gör det möjligt för ett klientprogram att få auktoriserad åtkomst till skyddade resurser som webb-API:er. Autentiseringskodflödet kräver en användaragent som stöder omdirigering från auktoriseringsservern (Microsofts identitetsplattform) tillbaka till ditt program. Till exempel en webbläsare, ett skrivbord eller ett mobilprogram som drivs av en användare för att logga in på din app och komma åt deras data.
Den här artikeln beskriver protokollinformation på låg nivå som endast krävs när du skapar och utfärdar råa HTTP-begäranden för att köra flödet, vilket vi inte rekommenderar. Använd i stället ett Microsoft-byggt och stödt autentiseringsbibliotek för att hämta säkerhetstoken och anropa skyddade webb-API:er i dina appar.
Program som stöder autentiseringskodflödet
Använd autentiseringskodflödet i kombination med Proof Key for Code Exchange (PKCE) och OpenID Anslut (OIDC) för att hämta åtkomsttoken och ID-token i dessa typer av appar:
Protokollinformation
OAuth 2.0-auktoriseringskodflödet beskrivs i avsnitt 4.1 i OAuth 2.0-specifikationen. Appar som använder OAuth 2.0-auktoriseringskodflödet hämtar en access_token som ska inkluderas i begäranden till resurser som skyddas av Microsofts identitetsplattform (vanligtvis API:er). Appar kan också begära nytt ID och åtkomsttoken för tidigare autentiserade entiteter med hjälp av en uppdateringsmekanism.
Det här diagrammet visar en översikt över autentiseringsflödet:
Omdirigerings-URI:er för ensidesappar (SPA)
Omdirigerings-URI:er för SPA:er som använder autentiseringskodflödet kräver särskild konfiguration.
- Lägg till en omdirigerings-URI som stöder autentiseringskodflöde med PKCE och resursdelning mellan ursprung (CORS): Följ stegen i Omdirigerings-URI: MSAL.js 2.0 med autentiseringskodflöde.
- Uppdatera en omdirigerings-URI: Ange omdirigerings-URI:n
typetillspamed hjälp av programmanifestredigeraren i administrationscentret för Microsoft Entra.
Omdirigeringstypen spa är bakåtkompatibel med det implicita flödet. Appar som använder det implicita flödet för att hämta token kan flyttas till spa omdirigerings-URI-typen utan problem och fortsätta använda det implicita flödet.
Om du försöker använda auktoriseringskodflödet utan att konfigurera CORS för din omdirigerings-URI visas det här felet i konsolen:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
I så fall besöker du din appregistrering och uppdaterar omdirigerings-URI:n för din app för att använda typen spa .
Program kan inte använda en spa omdirigerings-URI med icke-SPA-flöden, till exempel interna program eller klientautentiseringsflöden. För att säkerställa säkerhet och bästa praxis returnerar Microsofts identitetsplattform ett fel om du försöker använda en spa omdirigerings-URI utan en Origin rubrik. På samma sätt förhindrar Microsofts identitetsplattform även användning av klientautentiseringsuppgifter i alla flöden i närvaro av en Origin rubrik, för att säkerställa att hemligheter inte används inifrån webbläsaren.
Begära en auktoriseringskod
Auktoriseringskodflödet börjar med att klienten dirigerar användaren till /authorize slutpunkten. I den här begäran begär klienten behörigheterna openid, offline_accessoch https://graph.microsoft.com/mail.read från användaren.
Vissa behörigheter är administratörsbegränsade, till exempel att skriva data till en organisations katalog med hjälp Directory.ReadWrite.Allav . Om ditt program begär åtkomst till någon av dessa behörigheter från en organisationsanvändare får användaren ett felmeddelande om att de inte har behörighet att godkänna appens behörigheter. Om du vill begära åtkomst till administratörsbegränsade omfång bör du begära dem direkt från en global administratör. Mer information finns i Administratörsbegränsade behörigheter.
Om inget annat anges finns det inga standardvärden för valfria parametrar. Det finns dock standardbeteende för en begäran som utelämnar valfria parametrar. Standardbeteendet är att antingen logga in den enda aktuella användaren, visa kontoväljaren om det finns flera användare eller visa inloggningssidan om det inte finns några användare som är inloggade.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parameter | Obligatoriskt/valfritt | beskrivning |
|---|---|---|
tenant |
required | 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. Giltiga värden är common, organizations, consumersoch klientidentifierare. För gästscenarier där du loggar in en användare från en klientorganisation i en annan klientorganisation måste du ange klientidentifieraren för att logga in dem i resursklientorganisationen. Mer information finns i Slutpunkter. |
client_id |
required | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app. |
response_type |
required | Måste inkluderas code för auktoriseringskodflödet. Kan även inkludera id_token eller token om du använder hybridflödet. |
redirect_uri |
required | Appens redirect_uri , där autentiseringssvar kan skickas och tas emot av din app. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i administrationscentret för Microsoft Entra, förutom att den måste vara URL-kodad. För interna appar och mobilappar använder du något av de rekommenderade värdena: https://login.microsoftonline.com/common/oauth2/nativeclient för appar som använder inbäddade webbläsare eller http://localhost för appar som använder systemwebbläsare. |
scope |
required | En utrymmesavgränsad lista över omfång som du vill att användaren ska samtycka till. För delen /authorize av begäran kan den här parametern omfatta flera resurser. Med det här värdet kan din app få medgivande för flera webb-API:er som du vill anropa. |
response_mode |
rekommenderas | Anger hur identitetsplattformen ska returnera den begärda token till din app. Värden som stöds: - query: Standard när du begär en åtkomsttoken. Innehåller koden som en frågesträngsparameter på din omdirigerings-URI. Parametern query stöds inte när du begär en ID-token med hjälp av det implicita flödet. - fragment: Standard när du begär en ID-token med hjälp av det implicita flödet. Stöds också om du bara begär en kod.- form_post: Kör en POST som innehåller koden till din omdirigerings-URI. Stöds när du begär en kod. |
state |
rekommenderas | Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med valfritt innehåll som du vill. Ett slumpmässigt genererat unikt värde används vanligtvis för att förhindra förfalskningsattacker mellan webbplatser. Värdet kan också koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade. Den kan till exempel koda sidan eller vyn som de var på. |
prompt |
valfri | Anger vilken typ av användarinteraktion som krävs. Giltiga värden är login, none, consentoch select_account.- prompt=login tvingar användaren att ange sina autentiseringsuppgifter för den begäran och negera enkel inloggning.- prompt=none är motsatsen. Det säkerställer att användaren inte visas med någon interaktiv fråga. Om begäran inte kan slutföras tyst med enkel inloggning returnerar Microsofts identitetsplattform ett interaction_required fel.- prompt=consent utlöser dialogrutan OAuth-medgivande när användaren har loggat in och ber användaren att bevilja behörigheter till appen.- prompt=select_account avbryter enkel inloggning för att ge kontovalsupplevelsen en lista över alla konton, antingen i sessionen eller ett ihågkomet konto eller ett alternativ för att välja att använda ett annat konto helt och hållet. |
login_hint |
valfri | Du kan använda den här parametern för att fylla i fältet användarnamn och e-postadress på inloggningssidan för användaren. Appar kan använda den här parametern under omautentiseringen, efter att redan ha extraherat det valfria anspråket login_hint från en tidigare inloggning. |
domain_hint |
valfri | Om den ingår hoppar appen över den e-postbaserade identifieringsprocess som användaren går igenom på inloggningssidan, vilket leder till en något mer effektiviserad användarupplevelse. Du kan till exempel skicka dem till deras federerade identitetsprovider. Appar kan använda den här parametern under omautentiseringen genom att tid extrahera från en tidigare inloggning. |
code_challenge |
rekommenderat/obligatoriskt | Används för att skydda auktoriseringskodsbidrag med hjälp av Proof Key for Code Exchange (PKCE). Krävs om code_challenge_method ingår. Mer information finns i PKCE RFC. Den här parametern rekommenderas nu för alla programtyper, både offentliga och konfidentiella klienter, och krävs av Microsofts identitetsplattform för ensidesappar med hjälp av auktoriseringskodflödet. |
code_challenge_method |
rekommenderat/obligatoriskt | Den metod som används för att koda code_verifier för parametern code_challenge . Detta bör vara S256, men specifikationen tillåter användning av plain om klienten inte kan stödja SHA256. Om detta utesluts code_challenge antas det vara klartext om code_challenge det ingår. Microsofts identitetsplattform stöder både plain och S256. Mer information finns i PKCE RFC. Den här parametern krävs för ensidesappar med hjälp av auktoriseringskodflödet. |
Nu uppmanas användaren att ange sina autentiseringsuppgifter och slutföra autentiseringen. Microsofts identitetsplattform ser också till att användaren har samtyckt till de behörigheter som anges i scope frågeparametern. Om användaren inte har samtyckt till någon av dessa behörigheter uppmanas användaren att samtycka till de behörigheter som krävs. Mer information finns i Behörigheter och medgivande i Microsofts identitetsplattform.
När användaren autentiserar och beviljar medgivande returnerar Microsofts identitetsplattform ett svar till din app på angiven redirect_uri, med hjälp av den metod som anges i parameternresponse_mode.
Lyckat svar
Det här exemplet visar ett lyckat svar med hjälp av response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parameter | Description |
|---|---|
code |
Det authorization_code som appen begärde. Appen kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. Auktoriseringskoder är kortlivade. Vanligtvis upphör de att gälla efter cirka 10 minuter. |
state |
Om en state parameter ingår i begäran bör samma värde visas i svaret. Appen bör kontrollera att tillståndsvärdena i begäran och svaret är identiska. |
Du kan också få en ID-token om du begär en och har det implicita beviljandet aktiverat i din programregistrering. Det här beteendet kallas ibland för hybridflödet. Det används av ramverk som ASP.NET.
Felsvar
Felsvar kan också skickas till så att redirect_uri appen kan hantera dem på rätt sätt:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Description |
|---|---|
error |
En felkodssträng som kan användas för att klassificera typer av fel och reagera på fel. Den här delen av felet tillhandahålls så att appen kan reagera korrekt på felet, men förklarar inte på djupet varför ett fel uppstod. |
error_description |
Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera orsaken till ett autentiseringsfel. Den här delen av felet innehåller det mesta av den användbara informationen om varför felet inträffade. |
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 |
|---|---|---|
invalid_request |
Protokollfel, till exempel en parameter som saknas. | Åtgärda och skicka begäran igen. Det här felet är ett utvecklingsfel som vanligtvis uppstår under den första testningen. |
unauthorized_client |
Klientprogrammet har inte behörighet att begära en auktoriseringskod. | Det här felet uppstår vanligtvis när klientprogrammet inte är registrerat i Microsoft Entra-ID eller inte läggs till i användarens Microsoft Entra-klientorganisation. Programmet kan uppmana användaren med instruktioner för att installera programmet och lägga till det i Microsoft Entra-ID. |
access_denied |
Resursägaren nekades 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 felet är ett utvecklingsfel som vanligtvis uppstår under den första testningen. I hybridflödet signalerar det här felet att du måste aktivera inställningen implicit beviljande av ID-token för klientappregistreringen. |
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 dess svar fördröjs till 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, Microsoft Entra-ID kan inte hitta den eller så är den inte korrekt konfigurerad. | Det här felet anger 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 Microsoft Entra-ID. |
login_required |
För många eller inga användare hittades. | Klienten begärde tyst autentisering (prompt=none), men det gick inte att hitta en enskild användare. Det här felet kan innebära att det finns flera användare som är aktiva i sessionen eller inga användare. Det här felet tar hänsyn till den klientorganisation som valts. Om det till exempel finns två Microsoft Entra-konton aktiva och ett Microsoft-konto, och consumers väljs, fungerar tyst autentisering. |
interaction_required |
Begäran kräver användarinteraktion. | Ett annat autentiseringssteg eller medgivande krävs. Försök igen utan prompt=none. |
Begära en ID-token eller hybridflöde
Om du vill veta vem användaren är innan du löser in en auktoriseringskod är det vanligt att program även begär en ID-token när de begär auktoriseringskoden. Den här metoden kallas hybridflödet eftersom det blandar OIDC med OAuth2-auktoriseringskodflödet.
Hybridflödet används ofta i webbappar för att återge en sida för en användare utan att blockera kodinlösen, särskilt i ASP.NET. Både ensidesappar och traditionella webbappar drar nytta av kortare svarstider i den här modellen.
Hybridflödet är detsamma som det auktoriseringskodflöde som beskrevs tidigare men med tre tillägg. Alla dessa tillägg krävs för att begära en ID-token: nya omfång, en ny response_type och en ny nonce frågeparameter.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
Användningen av fragment som svarsläge orsakar problem för webbappar som läser koden från omdirigeringen. Webbläsare skickar inte fragmentet till webbservern. I dessa situationer bör appar använda svarsläget form_post för att säkerställa att alla data skickas till servern.
Lyckat svar
Det här exemplet visar ett lyckat svar med hjälp av response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Parameter | Description |
|---|---|
code |
Auktoriseringskoden som appen begärde. Appen kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. Auktoriseringskoder är kortvariga och upphör vanligtvis att gälla efter cirka 10 minuter. |
id_token |
En ID-token för användaren, utfärdad med hjälp av implicit beviljande. Innehåller ett särskilt c_hash anspråk som är hashen för code i samma begäran. |
state |
Om en state parameter ingår i begäran bör samma värde visas i svaret. Appen bör kontrollera att tillståndsvärdena i begäran och svaret är identiska. |
Lösa in en kod för en åtkomsttoken
Alla konfidentiella klienter kan välja att använda klienthemligheter eller certifikatautentiseringsuppgifter. Symmetriska delade hemligheter genereras av Microsofts identitetsplattform. Certifikatautentiseringsuppgifter är asymmetriska nycklar som laddas upp av utvecklaren. Mer information finns i Microsofts identitetsplattform certifikatautentiseringsuppgifter för program.
För bästa säkerhet rekommenderar vi att du använder certifikatautentiseringsuppgifter. Offentliga klienter, som innehåller inbyggda program och ensidesappar, får inte använda hemligheter eller certifikat när de löser in en auktoriseringskod. Se alltid till att dina omdirigerings-URI:er innehåller typen av program och är unika.
Begära en åtkomsttoken med en client_secret
Nu när du har skaffat en authorization_code och har beviljats behörighet av användaren kan du lösa in code för en access_token till resursen. code Lös in genom att skicka en POST begäran till /token slutpunkten:
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Parameter | Obligatoriskt/valfritt | beskrivning |
|---|---|---|
tenant |
required | 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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter. |
client_id |
required | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar sida som tilldelats din app. |
scope |
valfri | En blankstegsavgränsad lista med omfång. Omfången måste alla komma från en enskild resurs, tillsammans med OIDC-omfång (profile, openid, email). Mer information finns i Behörigheter och medgivande i Microsofts identitetsplattform. Den här parametern är ett Microsoft-tillägg till auktoriseringskodflödet, som är avsett att tillåta appar att deklarera den resurs som de vill ha token för under tokeninlösen. |
code |
required | Det authorization_code som du fick i den första delen av flödet. |
redirect_uri |
required | Samma redirect_uri värde som användes för att hämta authorization_code. |
grant_type |
required | Måste vara authorization_code för auktoriseringskodflödet. |
code_verifier |
rekommenderas | Samma code_verifier som användes för att hämta authorization_code. Krävs om PKCE användes i begäran om beviljande av auktoriseringskod. Mer information finns i PKCE RFC. |
client_secret |
krävs för konfidentiella webbappar | Programhemligheten som du skapade i appregistreringsportalen för din app. Använd inte programhemligheten i en intern app eller en enskild sidapp eftersom en client_secret inte kan lagras på ett tillförlitligt sätt på enheter eller webbsidor. Det krävs för webbappar och webb-API:er, som kan lagra på client_secret ett säkert sätt på serversidan. Precis som alla parametrar här måste klienthemligheten vara URL-kodad innan den skickas. Det här steget utförs av SDK:et. Mer information om URI-kodning finns i URI: ns allmänna syntaxspecifikation. Mönstret Grundläggande autentisering i stället för att ange autentiseringsuppgifter i auktoriseringshuvudet, per RFC 6749 stöds också. |
Begära en åtkomsttoken med en certifikatautentiseringsuppgift
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Parameter | Obligatoriskt/valfritt | beskrivning |
|---|---|---|
tenant |
required | 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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter. |
client_id |
required | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar sida som tilldelats din app. |
scope |
valfri | En blankstegsavgränsad lista med omfång. Omfången måste alla komma från en enskild resurs, tillsammans med OIDC-omfång (profile, openid, email). Mer information finns i behörigheter, medgivande och omfång. Den här parametern är ett Microsoft-tillägg till auktoriseringskodflödet. Med det här tillägget kan appar deklarera den resurs som de vill ha token för under tokeninlösen. |
code |
required | Det authorization_code som du fick i den första delen av flödet. |
redirect_uri |
required | Samma redirect_uri värde som användes för att hämta authorization_code. |
grant_type |
required | Måste vara authorization_code för auktoriseringskodflödet. |
code_verifier |
rekommenderas | code_verifier Samma som användes för att hämta authorization_code. Krävs om PKCE användes i begäran om beviljande av auktoriseringskod. Mer information finns i PKCE RFC. |
client_assertion_type |
krävs för konfidentiella webbappar | Värdet måste anges till att urn:ietf:params:oauth:client-assertion-type:jwt-bearer använda en certifikatautentiseringsuppgift. |
client_assertion |
krävs för konfidentiella webbappar | Ett intyg, som är en JSON-webbtoken (JWT), som du behöver för att skapa och signera med certifikatet som du registrerade som autentiseringsuppgifter för ditt program. Läs mer om certifikatautentiseringsuppgifter för att lära dig hur du registrerar ditt certifikat och formatet på försäkran. |
Parametrarna är samma som begäran av delad hemlighet förutom att parametern client_secret ersätts av två parametrar: a client_assertion_type och client_assertion.
Lyckat svar
Det här exemplet visar ett lyckat tokensvar:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | Description |
|---|---|
access_token |
Den begärda åtkomsttoken. Appen kan använda den här token för att autentisera till den skyddade resursen, till exempel ett webb-API. |
token_type |
Anger värdet för tokentyp. Den enda typ som Microsoft Entra ID stöder är Bearer. |
expires_in |
Hur länge åtkomsttoken är giltig i sekunder. |
scope |
De omfång som access_token är giltiga för. Valfritt. Den här parametern är inte standard och om den utelämnas är token för de omfång som begärdes i den första delen av flödet. |
refresh_token |
En OAuth 2.0-uppdateringstoken. Appen kan använda den här token för att hämta andra åtkomsttoken när den aktuella åtkomsttoken upphör att gälla. Uppdateringstoken är långlivade. De kan upprätthålla åtkomsten till resurser under längre perioder. Mer information om hur du uppdaterar en åtkomsttoken finns i Uppdatera åtkomsttoken senare i den här artikeln. Obs! Tillhandahålls endast om offline_access omfång begärdes. |
id_token |
En JSON-webbtoken. Appen kan avkoda segmenten för den här token för att begära information om användaren som loggade in. Appen kan cachelagras värdena och visa dem, och konfidentiella klienter kan använda den här token för auktorisering. Mer information om id_tokens finns i id_token reference. Obs! Tillhandahålls endast om openid omfång begärdes. |
Felsvar
Det här exemplet är ett felsvar:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parameter | Description |
|---|---|
error |
En felkodssträng som kan användas för att klassificera typer av fel och reagera på fel. |
error_description |
Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera orsaken 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. |
Felkoder för tokenslutpunktsfel
| Felkod | beskrivning | Klientåtgärd |
|---|---|---|
invalid_request |
Protokollfel, till exempel en parameter som saknas. | Åtgärda begäran eller appregistreringen och skicka begäran igen. |
invalid_grant |
Auktoriseringskoden eller PKCE-kodverifieraren är ogiltig eller har upphört att gälla. | Prova en ny begäran till /authorize slutpunkten och kontrollera att parametern code_verifier var korrekt. |
unauthorized_client |
Den autentiserade klienten har inte behörighet att använda den här typen av auktoriseringsbeviljande. | Det här felet uppstår vanligtvis när klientprogrammet inte är registrerat i Microsoft Entra-ID eller inte läggs till i användarens Microsoft Entra-klientorganisation. Programmet kan uppmana användaren med instruktioner för att installera programmet och lägga till det i Microsoft Entra-ID. |
invalid_client |
Klientautentiseringen misslyckades. | Klientautentiseringsuppgifterna är inte giltiga. Programadministratören uppdaterar autentiseringsuppgifterna för att åtgärda problemet. |
unsupported_grant_type |
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. |
invalid_resource |
Målresursen är ogiltig eftersom den inte finns, Microsoft Entra-ID kan inte hitta den eller så är den inte korrekt konfigurerad. | Den här koden anger 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 Microsoft Entra-ID. |
interaction_required |
Icke-standard, eftersom OIDC-specifikationen endast anropar den här koden på /authorize slutpunkten. Begäran kräver användarinteraktion. Ett annat autentiseringssteg krävs till exempel. |
Försök /authorize igen med samma omfång. |
temporarily_unavailable |
Servern är tillfälligt för upptagen för att hantera begäran. | Försök igen efter en liten fördröjning. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt villkor. |
consent_required |
Begäran kräver användarmedgivande. Det här felet är inte standard. Det returneras vanligtvis bara på /authorize slutpunkten enligt OIDC-specifikationerna. Returnerades när en scope parameter användes i kodinlösenflödet som klientappen inte har behörighet att begära. |
Klienten bör skicka tillbaka användaren till /authorize slutpunkten med rätt omfång för att utlösa medgivande. |
invalid_scope |
Det omfång som begärs av appen är ogiltigt. | Uppdatera värdet för parametern scope i autentiseringsbegäran till ett giltigt värde. |
Kommentar
Ensidesappar kan få ett invalid_request fel som anger att inlösen av token för korsande ursprung endast tillåts för klienttypen "Enkelsidigt program". Detta anger att omdirigerings-URI:n som används för att begära token inte har markerats som en spa omdirigerings-URI. Granska stegen för programregistrering om hur du aktiverar det här flödet.
Använda åtkomsttoken
Nu när du har skaffat en access_tokenkan du använda token i begäranden till webb-API:er genom att inkludera den i Authorization rubriken:
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Uppdatera åtkomsttoken
Åtkomsttoken är kortlivade. Uppdatera dem när de har upphört att gälla för att fortsätta komma åt resurser. Du kan göra det genom att skicka en annan POST begäran till /token slutpunkten. refresh_token Ange i stället för code. Uppdateringstoken är giltiga för alla behörigheter som klienten redan har fått medgivande för. Till exempel kan en uppdateringstoken som utfärdats på en begäran för användas för scope=mail.read att begära en ny åtkomsttoken för scope=api://contoso.com/api/UseResource.
Uppdateringstoken för webbappar och interna appar 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 åtgärden. Ditt program måste förvänta sig och hantera fel som returneras av slutpunkten för tokenutfärdning. Ensidesappar får en token med en livslängd på 24 timmar, vilket kräver en ny autentisering varje dag. Den här åtgärden kan utföras tyst i en iframe när cookies från tredje part aktiveras. Det måste göras i en ram på den översta nivån, antingen helsidesnavigering eller ett popup-fönster, i webbläsare utan cookies från tredje part, till exempel Safari.
Uppdateringstoken återkallas inte när de används för att hämta nya åtkomsttoken. Du förväntas ta bort den gamla uppdateringstoken. OAuth 2.0-specifikationen säger: "Auktoriseringsservern kan utfärda en ny uppdateringstoken, i vilket fall klienten MÅSTE ta bort den gamla uppdateringstoken och ersätta den med den nya uppdateringstoken. Auktoriseringsservern kan återkalla den gamla uppdateringstoken efter att ha utfärdat en ny uppdateringstoken till klienten."
Viktigt!
För uppdateringstoken som skickas till en omdirigerings-URI som registrerats som spaupphör uppdateringstoken att gälla efter 24 timmar. Ytterligare uppdateringstoken som hämtas med den första uppdateringstoken överförs under den förfallotiden, så appar måste vara beredda att köra auktoriseringskodflödet igen med hjälp av en interaktiv autentisering för att få en ny uppdateringstoken var 24:e timme. Användarna behöver inte ange sina autentiseringsuppgifter och ser vanligtvis inte ens någon användarupplevelse, bara en ny inläsning av programmet. Webbläsaren måste gå till inloggningssidan i en ram på den översta nivån för att kunna se inloggningssessionen. Detta beror på sekretessfunktioner i webbläsare som blockerar cookies från tredje part.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Parameter | Typ | Beskrivning |
|---|---|---|
tenant |
required | 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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter. |
client_id |
required | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar upplevelse som tilldelats din app. |
grant_type |
required | Måste vara refresh_token för den här delen av auktoriseringskodflödet. |
scope |
valfri | En blankstegsavgränsad lista med omfång. De omfång som begärs i den här delen måste vara likvärdiga med eller en delmängd av de omfång som begärdes i den ursprungliga authorization_code begärandeben. Om de omfång som anges i den här begäran sträcker sig över flera resursservrar returnerar Microsofts identitetsplattform en token för resursen som anges i det första omfånget. Mer information finns i Behörigheter och medgivande i Microsofts identitetsplattform. |
refresh_token |
required | Det refresh_token som du fick i den andra delen av flödet. |
client_secret |
krävs för webbappar | Programhemligheten som du skapade i appregistreringsportalen för din app. Det bör inte användas i en intern app, eftersom en client_secret inte kan lagras på ett tillförlitligt sätt på enheter. Det krävs för webbappar och webb-API:er, som kan lagra på client_secret ett säkert sätt på serversidan. Den här hemligheten måste vara URL-kodad. Mer information finns i URI:ns allmänna syntaxspecifikation. |
Lyckat svar
Det här exemplet visar ett lyckat tokensvar:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | Description |
|---|---|
access_token |
Den begärda åtkomsttoken. Appen kan använda den här token för att autentisera till den skyddade resursen, till exempel ett webb-API. |
token_type |
Anger värdet för tokentyp. Den enda typ som Microsoft Entra ID stöder är Bearer. |
expires_in |
Hur länge åtkomsttoken är giltig i sekunder. |
scope |
De omfång som access_token är giltiga för. |
refresh_token |
En ny OAuth 2.0-uppdateringstoken. Ersätt den gamla uppdateringstoken med den här nyligen förvärvade uppdateringstoken för att säkerställa att dina uppdateringstoken förblir giltiga så länge som möjligt. Obs! Tillhandahålls endast om offline_access omfång begärdes. |
id_token |
En osignerad JSON-webbtoken. Appen kan 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 id_tokenfinns i Microsofts identitetsplattform ID-token. Obs! Tillhandahålls endast om openid omfång begärdes. |
Varning
Försök inte verifiera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i koden. Token för Microsoft-tjänster kan använda ett särskilt format som inte verifieras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Läs token är ett användbart felsöknings- och inlärningsverktyg, men använd inte beroenden för detta i koden eller anta detaljer om token som inte är för ett API som du kontrollerar.
Felsvar
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parameter | Description |
|---|---|
error |
En felkodssträng som kan användas för att klassificera typer av fel och 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
- Gå över MSAL JS-exemplen för att komma igång med kodningen.
- Läs mer om scenarier för tokenutbyte.