Microsofts identitetsplattform- och OAuth 2.0-auktoriseringskodflöde

Beviljande av OAuth 2.0-auktoriseringskod kan användas i appar som är installerade på en enhet för att få åtkomst till skyddade resurser, till exempel webb-API:er. Med hjälp av Microsofts identitetsplattform implementering av OAuth 2.0 och Open ID Anslut (OIDC) kan du lägga till inloggnings- och API-åtkomst till dina mobilappar och skrivbordsappar.

I den här artikeln beskrivs hur du kan programmera direkt mot protokollet i ditt program med hjälp av valfritt språk. När det är möjligt rekommenderar vi att du använder de Microsoft Authentication Libraries (MSAL) som stöds för att hämta token och anropa skyddade webb-API:er. Mer information finns i exempelappar som använder MSAL.

OAuth 2.0-auktoriseringskodflödet beskrivs i avsnitt 4.1 i OAuth 2.0-specifikationen. Med OIDC utför det här flödet autentisering och auktorisering för de flesta apptyper. Dessa typer omfattar ensidesappar, webbappar och internt installerade appar. Flödet gör det möjligt för appar att på ett säkert sätt hämta en access_token som kan användas för att komma åt resurser som skyddas av Microsofts identitetsplattform. Appar kan uppdatera token för att hämta andra åtkomsttoken och ID-token för den inloggade användaren.

Tips

Try running this request in Postman
Prova att köra den här begäran och mycket mer i Postman – glöm inte att ersätta token och ID:t!

Protokolldiagram

Det här diagrammet ger en översikt på hög nivå över autentiseringsflödet för ett program:

Diagram shows OAuth authorization code flow. Native app and Web A P I interact by using tokens as described in this article.

Omdirigerings-URI krävs för ensidesappar

Auktoriseringskodflödet för ensidesprogram kräver ytterligare konfiguration. Följ anvisningarna för att skapa ett ensidesprogram för att korrekt markera omdirigerings-URI:n som aktiverad för resursdelning för korsande ursprung (CORS). Om du vill uppdatera en befintlig omdirigerings-URI för att aktivera CORS öppnar du manifestredigeraren och anger type fältet för din omdirigerings-URI till spa i replyUrlsWithType avsnittet. Eller så kan du välja omdirigerings-URI:n i AuthenticationWeb> och välja URI:er att migrera till med hjälp av auktoriseringskodflödet.

Omdirigeringstypen spa är bakåtkompatibel med det implicita flödet. Appar som för närvarande 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 går du till din appregistrering och uppdaterar omdirigerings-URI:n för din app så att den spa använder typen .

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 ett Origin huvud. 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 inloggade användare.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read%20api%3A%2F%2F
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Tips

Välj länken nedan för att köra den här begäran! När du har loggat in ska webbläsaren omdirigeras till http://localhost/myapp/ med en code i adressfältet. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parameter Obligatoriskt/valfritt Beskrivning
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. 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 klient-ID:t för att logga in dem i resursklientorganisationen. Mer information finns i Slutpunkter.
client_id krävs Det program-ID (klient)-ID som Azure Portal – Appregistreringar upplevelse som tilldelats din app.
response_type krävs Måste inkluderas code för auktoriseringskodflödet. Kan även inkludera id_token eller token om du använder hybridflödet.
redirect_uri krävs 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 portalen, 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 krävs En blankstegsavgränsad lista över omfång som du vill att användaren ska godkänna. För delen /authorize av begäran kan den här parametern täcka 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. Anger 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 även om endast en kod begärs.
- 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, consent och select_account.

- prompt=login tvingar användaren att ange sina autentiseringsuppgifter för begäran och negera enkel inloggning.
- prompt=none är motsatsen. Det säkerställer att användaren inte får någon interaktiv uppmaning. Om begäran inte kan slutföras tyst med hjälp av enkel inloggning returnerar Microsofts identitetsplattform ett interaction_required fel.
- prompt=consent utlöser dialogrutan för OAuth-medgivande efter att användaren har loggat in och ber användaren att bevilja behörigheter till appen.
- prompt=select_account avbryter enkel inloggning vilket ger en upplevelse för val av konto som visar alla konton, antingen i session eller ett sparat 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 i förväg på inloggningssidan för användaren. Appar kan använda den här parametern under omautentiseringen, efter att redan ha extraherat det valfria anspråketlogin_hint från en tidigare inloggning.
domain_hint valfri Om den ingår hoppar appen över den e-postbaserade identifieringsprocessen som användaren går igenom på inloggningssidan, vilket leder till en något mer strömlinjeformad 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 beviljande av auktoriseringskod med hjälp av proof key för 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 som använder 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 har stöd för SHA256.

Om den undantas antas vara klartext om code_challenge den inkluderascode_challenge. 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 säkerställer också 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 godkänna 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 metoden som anges i parametern response_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 Beskrivning
code Den authorization_code app som begärdes. Appen kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. Auktoriseringskoder är kortvariga. 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 implicit beviljande aktiverat i din programregistrering. Det här beteendet kallas ibland för hybridflödet. Den 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 Beskrivning
error En felkodsträ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 användbar information 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 obligatorisk parameter som saknas. Åtgärda och skicka begäran igen. Det här felet är ett utvecklingsfel som vanligtvis uppstår under den inledande 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 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 nekades medgivande Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren ger sitt medgivande.
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 inledande 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 svaret 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 dess svar fördröjs 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. Det här felet 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.
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å Aktiva Azure AD-konton 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 begäran 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 för hybridflödet eftersom det blandar implicit beviljande med 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=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
Parametern har uppdaterats Obligatoriskt/valfritt Beskrivning
response_type krävs Tillägget av id_token anger för servern att programmet vill ha en ID-token i svaret från /authorize slutpunkten.
scope krävs För ID-token måste den här parametern uppdateras för att inkludera ID-tokenomfången: openid och eventuellt profile och email.
nonce krävs Ett värde som ingår i begäran, som genereras av appen, som ingår i resultatet id_token som ett anspråk. Appen kan sedan verifiera det här värdet för att minimera tokenreprisattacker. Värdet är vanligtvis en slumpmässig, unik sträng som kan användas för att identifiera begärans ursprung.
response_mode Rekommenderas Anger vilken metod som ska användas för att skicka tillbaka den resulterande token till din app. Standardvärdet är query bara för en auktoriseringskod, men fragment om begäran innehåller en id_tokenresponse_type som anges i OpenID-specifikationen. Vi rekommenderar att appar använder form_post, särskilt när de används http://localhost som omdirigerings-URI.

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 Beskrivning
code Den auktoriseringskod 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 som utfärdas med hjälp av det implicita beviljandet. 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong 
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
Parameter Obligatoriskt/valfritt Beskrivning
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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter.
client_id krävs Program-ID:t (klient) som Azure Portal – Appregistreringar sida som tilldelats till din app.
scope valfri En blankstegsavgränsad lista över omfång. Omfången måste vara från en enda 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 krävs Det authorization_code som du fick i den första delen av flödet.
redirect_uri krävs Samma redirect_uri värde som användes för att hämta authorization_code.
grant_type krävs 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 ensidesapp 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 säkert client_secret på serversidan. Precis som alla parametrar här måste klienthemligheten vara URL-kodad innan den skickas. Det här steget utförs vanligtvis av SDK: et. Mer information om URI-kodning finns i URI:ns allmänna syntaxspecifikation. Mönstret Grundläggande autentisering för att i stället ange autentiseringsuppgifter i auktoriseringshuvudet, per RFC 6749 stöds också.

Begära en åtkomsttoken med en certifikatautentiseringsuppgift

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
Parameter Obligatoriskt/valfritt Beskrivning
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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter.
client_id krävs Program-ID:t (klient) som Azure Portal – Appregistreringar sida som tilldelats till din app.
scope valfri En blankstegsavgränsad lista över omfång. Omfången måste vara från en enda 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 krävs Det authorization_code som du fick i den första delen av flödet.
redirect_uri krävs Samma redirect_uri värde som användes för att hämta authorization_code.
grant_type krävs 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_assertion_type krävs för konfidentiella webbappar Värdet måste anges till för att urn:ietf:params:oauth:client-assertion-type:jwt-bearer använda en certifikatautentiseringsuppgift.
client_assertion krävs för konfidentiella webbappar En försäkran, som är en JSON-webbtoken (JWT), som du måste 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 certifikatet och intygets format.

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 Beskrivning
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 typen som Azure AD 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 gäller token för de omfång som begärdes i det inledande 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 har upphört 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.
Observera: 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.
Observera: 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parameter Beskrivning
error En felkodsträng som kan användas för att klassificera typer av fel och för att 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 till med diagnostik.
timestamp Tidpunkt då felet inträffade.
trace_id En unik identifierare för begäran som kan hjälpa till 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 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. Klientautentiseringsuppgifterna är inte giltiga. Programadministratören uppdaterar autentiseringsuppgifterna för att åtgärda problemet.
unsupported_grant_type Auktoriseringsservern stöder inte auktoriserings bevilja typ. Ändra bidragstypen 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, Azure AD inte kan 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 att installera programmet och lägga till det i Azure AD.
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 igen /authorize 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 per OIDC-specifikationer. Returneras 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.

Anteckning

Ensidesappar kan få ett invalid_request fel som anger att tokeninlösen mellan ursprung endast tillåts för klienttypen "Enkelsidigt program". Detta anger att den omdirigerings-URI som används för att begära token inte har markerats som en spa omdirigerings-URI. Läs 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 kortvariga. 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 för en begäran 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 är aktiverade. 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 ignorera den gamla uppdateringstoken. OAuth 2.0-specifikationen säger: "Auktoriseringsservern kan utfärda en ny uppdateringstoken, i så fall måste klienten ta bort den gamla uppdateringstoken och ersätta den med den nya uppdateringstoken. Auktoriseringsservern kan återkalla den gamla uppdateringstoken när en ny uppdateringstoken har utfärdats till klienten."

Viktigt

För uppdateringstoken som skickas till en omdirigerings-URI som är registrerad 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å ö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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s    // NOTE: Only required for web apps. This secret needs to be URL-Encoded
Parameter Typ Beskrivning
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. Giltiga värden är common, organizations, consumersoch klientidentifierare. Mer information finns i Slutpunkter.
client_id krävs Det program-ID (klient)-ID som Azure Portal – Appregistreringar upplevelse som tilldelats din app.
grant_type krävs Måste vara refresh_token för den här delen av auktoriseringskodflödet.
scope valfri En blankstegsavgränsad lista över 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 krävs Det refresh_token som du fick i andra delen av flödet.
client_secret krävs för webbappar Programhemligheten som du skapade i appregistreringsportalen för din app. Den 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 säkert client_secret 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 Beskrivning
access_token Begärd åtkomsttoken. 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 Ägarna.
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.
Observera: Tillhandahålls endast om offline_access omfång begärdes.
id_token En osignerad JSON-webbtoken. Appen kan 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 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.
Observera: 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 valideras som en JWT och som även kan krypteras för konsumentanvändare (Microsoft-konto). Även om läsning av token är ett användbart felsöknings- och inlärningsverktyg bör du inte använda beroenden för detta i din kod 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
Parameter Beskrivning
error En felkodsträ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 vara till hjälp i diagnostiken.
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