Microsofts identitetsplattform och OAuth 2.0-auktoriseringskodflöde

  • Artikel
  • 23 minuter för att läsa

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 Microsofts identitetsplattform av OAuth 2.0 och Open ID Anslut (OIDC) kan du lägga till inloggning och API-åtkomst till dina mobilappar och skrivbordsappar.

Den här artikeln beskriver hur du programmerar direkt mot protokollet i ditt program med val annat språk. När det är möjligt rekommenderar vi att du använder de Microsoft Authentication Libraries (MSAL) som stöds i stället för att hämta token och anropa säkra webb-API:er. Ta även en titt på exempelapparna som använder MSAL.

OAuth 2.0-auktoriseringskodflödet beskrivs i avsnitt 4.1 i OAuth 2.0-specifikationen. Med OIDC används det för att utföra autentisering och auktorisering i de flesta apptyper, inklusive ensidesappar, webbappar och inbyggda appar. Flödet gör att appar på ett säkert sätt kan hämta access_tokens som kan användas för att komma åt resurser som skyddas av Microsofts identitetsplattform, samt uppdateringstoken för att hämta ytterligare access_tokens och ID-token för den inloggade användaren.

Tips

Prova att köra den här begäran i Postman
Prova att köra den här begäran och mycket mer i Postman – glöm inte att ersätta token och-ID:er!

Protokolldiagram

På en hög nivå ser hela autentiseringsflödet för ett program ut lite så här:

OAuth Auth Code Flow

Omdirigerings-URI-konfiguration krävs för ensidesappar

Auktoriseringskodflödet för ensidesprogram kräver viss ytterligare konfiguration. Följ anvisningarna för att skapa ensidesapplikationen för att korrekt markera din omdirigerings-URI som aktiverad för CORS. Om du vill uppdatera en befintlig omdirigerings-URI för att aktivera CORS öppnar du manifestredigeraren och anger fältet för din type omdirigerings-URI spa till i avsnittet replyUrlsWithType . Du kan också klicka på omdirigerings-URI i avsnittet "Webb" på fliken Autentisering och välja de URI:er som du vill migrera till med hjälp av auktoriseringskodflödet.

spaOmdirigeringstypen ä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 gå över till spa omdirigerings-URI-typen utan problem och fortsätta att använda det implicita flödet.

Om du försöker använda auktoriseringskodflödet och ser det här felet:

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.

Gå sedan till din appregistrering och uppdatera omdirigerings-URI:en för din app för att skriva spa .

Program kan inte använda en spa omdirigerings-URI med icke-SPA-flöden, till exempel interna program eller flöden för klientidentifiering. För att säkerställa säkerhet och bästa praxis returnerar Microsoft Identity-plattformen ett fel om du försöker använda en spa omdirigerings-URI utan Origin rubrik. På samma sätt förhindrar Microsoft Identity-plattformen även användning av klientautentiseringsuppgifter (i OBO-flödet, flödet för klientautentiseringsuppgifter och auth-kodflöde) i närvaro av ett huvud för att säkerställa att hemligheter inte används inifrån Origin 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 openid offline_access behörigheterna , https://graph.microsoft.com/mail.read och från användaren. Vissa behörigheter är administratörsbegränsade, till exempel att skriva data till en organisations katalog med hjälp av Directory.ReadWrite.All . Om ditt program begär åtkomst till någon av dessa behörigheter från en organisationsanvändare får användaren ett felmeddelande som säger 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.

// 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

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

Parameter Obligatoriskt/valfritt Description
tenant krävs Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in i programmet. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder. För gästscenarier där du loggar in en användare från en klientorganisation till en annan klientorganisation måste du ange klient-ID:t för att logga in dem på rätt sätt i resursklientorganisationen.
client_id krävs Det program-ID (klient) som Azure Portal – Appregistreringar till din app.
response_type krävs Måste inkludera code för auktoriseringskodflödet. Kan även inkludera id_token eller om du använder token hybridflödet.
redirect_uri krävs Den redirect_uri av din app, där autentiseringssvar kan skickas och tas emot av din app. Den måste exakt matcha en av de redirect_uris som du registrerade i portalen, förutom att den måste vara URL-kodad. För inbyggda &-appar bör du använda något av de rekommenderade värdena – (för appar som använder inbäddade webbläsare) eller (för appar https://login.microsoftonline.com/common/oauth2/nativeclient http://localhost 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 av begäran kan detta omfatta flera resurser, så att din app kan få medgivande för flera /authorize webb-API:er som du vill anropa.
response_mode Rekommenderas Anger den metod som ska användas för att skicka den resulterande token tillbaka till din app. Kan vara något av följande:

- query
- fragment
- form_post

query innehåller koden som en frågesträngsparameter på din omdirigerings-URI. Om du begär en ID-token med hjälp av det implicita flödet kan du inte använda query som anges i OpenID-specifikationen. Om du bara begär koden kan du använda query , fragment eller form_post . form_post kör en POST som innehåller koden till din omdirigerings-URI.
state Rekommenderas Ett värde som ingår i begäran som också returneras i tokensvaret. Det kan vara en sträng med val annat innehåll. Ett slumpmässigt genererat unikt värde används vanligtvis för att förhindra förfalskning av begäran mellan webbplatser. Värdet kan också koda information om användarens tillstånd i appen innan autentiseringsbegäran gjordes, till exempel den sida eller vy som användaren var på.
prompt valfri Anger vilken typ av användarinteraktion som krävs. De enda giltiga värdena just nu är login , none , och consent select_account .

- prompt=login tvingar användaren att ange sina autentiseringsuppgifter på begäran, vilket negerar enkel inloggning.
- prompt=none är det motsatta – det säkerställer att användaren inte får någon interaktiv uppmaning alls. Om begäran inte kan slutföras tyst via enkel inloggning returnerar Microsofts identitetsplattform returnerar ett interaction_required fel.
- prompt=consent utlöser dialogrutan för OAuth-medgivande efter att användaren har loggar in, där användaren uppmanas att bevilja behörigheter till appen.
- prompt=select_account avbryter enkel inloggning och visar en lista över alla konton i sessionen eller ett ihågkommet konto eller ett alternativ för att välja att använda ett annat konto helt och hållet.
login_hint Valfritt 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 i förväg, om du känner till användarnamnet i förväg. Appar använder ofta den här parametern vid omauthenticering, efter att redan ha extraherat det valfria login_hint anspråket från en tidigare inloggning.
domain_hint valfri Om den inkluderas hoppar den över den e-postbaserade identifieringsprocessen som användaren går igenom på inloggningssidan, vilket leder till en något effektivare användarupplevelse – till exempel att skicka dem till sin federerade identitetsprovider. Appar använder ofta den här parametern vid omautentisering genom att tid extrahera från en tidigare inloggning.
code_challenge rekommenderas/krävs Används för att skydda auktoriseringskodsstipendier via proof key for Code Exchange (PKCE). Krävs om code_challenge_method ingår. Mer information finns i PKCE RFC. Detta 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 rekommenderas/krävs Metoden som används för att koda code_verifier för code_challenge parametern . Detta bör vara S256 , men specifikationen tillåter användning av om plain klienten av någon anledning inte kan stödja SHA256.

Om undantagna code_challenge antas vara klartext om code_challenge ingår. Den Microsofts identitetsplattform stöder både plain och S256 . Mer information finns i PKCE RFC. Detta krävs för ensidesappar som använder auktoriseringskodflödet.

Nu uppmanas användaren att ange sina autentiseringsuppgifter och slutföra autentiseringen. Den 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 godkänna de behörigheter som krävs. Information om behörigheter, medgivande och appar för flera innehavare finns här.

När användaren autentiserar och ger sitt medgivande Microsofts identitetsplattform returnerar ett svar till din app på angiven , med hjälp av den metod som redirect_uri anges i response_mode parametern .

Lyckat svar

Ett lyckat svar med hjälp response_mode=query av ser ut så här:

GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
Parameter Beskrivning
code Den authorization_code som appen begärde. Appen kan använda auktoriseringskoden för att begära en åtkomsttoken för målresursen. Authorization_codes kortlivade, vanligtvis upphör de efter cirka 10 minuter.
state Om en tillståndsparameter 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. Detta kallas ibland för "hybridflöde"och används av ramverk som ASP.NET.

Felsvar

Felsvar kan också skickas till redirect_uri så att 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 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.
error_description Ett specifikt felmeddelande som kan hjälpa en utvecklare att identifiera rotorsaken till ett autentiseringsfel.

Felkoder för auktoriseringsslutpunktsfel

I följande tabell beskrivs de olika felkoder som kan returneras i error parametern för felsvaret.

Felkod Description Klientåtgärd
invalid_request Protokollfel, till exempel en obligatorisk parameter saknas. Åtgärda och skicka begäran igen. Det här ä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 har lagts till i användarens Azure AD-klientorganisation. Programmet kan uppmana användaren att ange anvisningar för att installera programmet och lägga till det i Azure AD.
access_denied Resursägare nekat medgivande Klientprogrammet kan meddela användaren att det inte kan fortsätta om inte användaren godkänner det.
unsupported_response_type Auktoriseringsservern stöder inte svarstypen i begäran. Åtgärda och skicka begäran igen. Det här är ett utvecklingsfel som vanligtvis uppstår under den inledande testningen. När det visas i hybridflödetsignalerar det 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 att skicka begäran igen. De här felen kan uppstå på grund av tillfälliga förhållanden. Klientprogrammet kan förklara för användaren att svaret har fördröjts till ett tillfälligt fel.
temporarily_unavailable Servern är tillfälligt för upptagen för att hantera begäran. Försök att skicka begäran igen. Klientprogrammet kan förklara för användaren att svaret är försenat på grund av ett tillfälligt tillstånd.
invalid_resource Målresursen är ogiltig eftersom den inte finns, Azure AD 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 att ange anvisningar för 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 kan innebära att det finns flera användare som är aktiva i sessionen eller inga användare. Detta tar hänsyn till den klientorganisation som valts (om det till exempel finns två aktiva Azure AD-konton och en Microsoft-konto, och consumers väljs, kommer tyst autentisering att fungera).
interaction_required Begäran kräver användarinteraktion. Ytterligare ett autentiseringssteg eller godkännande krävs. Försök igen med begäran utan prompt=none .

Begär även en ID-token (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. Detta kallas hybridflöde eftersom det blandar implicit beviljande med auktoriseringskodflödet. Hybridflödet används ofta i webbappar som vill rendera en sida för en användare utan att blockera kodinlösning, särskilt ASP.NET. Både ensidesappar och traditionella webbappar drar nytta av kortare svarstider i den här modellen.

Hybridflödet är samma som auktoriseringskodflödet som beskrevs tidigare, men med tre tillägg som alla 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 till servern att programmet vill ha en ID-token i svaret från /authorize slutpunkten.
scope Obligatorisk För ID-token måste uppdateras för att inkludera ID-token-omfången openid , och eventuellt profile och email .
nonce Obligatorisk Ett värde som ingår i begäran, som genereras av appen, som tas med i den resulterande id_token som ett anspråk. Appen kan sedan verifiera det här värdet för att minimera tokenuppspelningsattacker. 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 den metod som ska användas för att skicka den resulterande token tillbaka till din app. Standardvärdet är query för bara en auktoriseringskod, fragment men om begäran innehåller en id_token response_type . Appar rekommenderas dock att använda , särskilt form_post när du använder som en http://localhost omdirigerings-URI.

Användning av som svarsläge orsakar problem för webbappar som läser koden från omdirigeringen, eftersom webbläsare inte skickar fragment fragmentet till webbservern. I sådana situationer bör appar använda form_post svarsläget för att säkerställa att alla data skickas till servern.

Lyckat svar

Ett lyckat svar med hjälp response_mode=fragment av ser ut så här:

GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
Parameter Beskrivning
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 som utfärdas via implicit beviljande. Innehåller ett c_hash särskilt anspråk som är hashen för i samma code begäran.
state Om en tillståndsparameter 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 mot en åtkomsttoken

Alla konfidentiella klienter kan välja att använda klienthemligheter (symmetriska delade hemligheter som genereras av Microsofts identitetsplattform) och certifikatautentiseringsuppgifter (asymmetriska nycklar som laddats upp av utvecklaren). För bästa säkerhet rekommenderar vi att du använder certifikatautentiseringsuppgifter. Offentliga klienter (interna 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 korrekt anger programtypen och är unika.

Begära en åtkomsttoken med en client_secret

Nu när du har skaffat authorization_code och har beviljats behörighet av användaren kan du lösa in mot code en access_token till önskad resurs. Gör detta genom att skicka POST en 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 Description
tenant krävs Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in i programmet. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder.
client_id krävs Det program-ID (klient) som Azure Portal – Appregistreringar till din app.
scope valfri En blankstegsavgränsad lista över omfång. Alla omfång måste komma från en enda resurs, tillsammans med OIDC-omfång ( profile , openid , email ). En mer detaljerad förklaring av omfång finns i behörigheter, medgivande och omfång. Det här ä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ösning.
code krävs Den authorization_code som du skaffade i flödets första ben.
redirect_uri krävs Samma redirect_uri 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 Den programhemlighet som du skapade i appregistreringsportalen för din app. Du bör inte använda programhemligheten i en inbyggd app eller en ensidesapp eftersom client_secrets inte kan lagras på ett tillförlitligt sätt på enheter eller webbsidor. Det krävs för webbappar och webb-API:er, som har möjlighet att lagra client_secret på ett säkert sätt på serversidan. Precis som alla parametrar som beskrivs här måste klienthemligheten vara URL-kodad innan den skickas, ett steg som vanligtvis utförs av SDK: n. Mer information om URI-kodning finns i URI Generic Syntax specification (URI:s specifikation för allmän syntax). Grundläggande autentiseringsmönster i stället för att ange autentiseringsuppgifter i auktoriseringsrubriken, per RFC 6749 stöds också.

Begära en åtkomsttoken med ett certifikats autentiseringsuppgifter

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 Description
tenant krävs Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in i programmet. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder.
client_id krävs Program-ID (klient) som Azure Portal – Appregistreringar till din app.
scope valfri En blankstegsavgränsad lista över omfång. Alla omfång måste komma från en enda resurs, tillsammans med OIDC-omfång ( profile , openid , email ). En mer detaljerad förklaring av omfång finns i behörigheter, medgivande och omfång. Det här ä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ösning.
code krävs Den authorization_code som du skaffade i flödets första ben.
redirect_uri krävs Samma redirect_uri 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 urn:ietf:params:oauth:client-assertion-type:jwt-bearer för att du ska kunna använda autentiseringsuppgifter för certifikat.
client_assertion krävs för konfidentiella webbappar En försäkran (en JSON-webbtoken) som du behöver för att skapa och signera med certifikatet som du registrerade som autentiseringsuppgifter för ditt program. Läs om autentiseringsuppgifter för certifikat för att lära dig hur du registrerar certifikatet och formatet för försäkran.

Observera att parametrarna är samma som i fallet med en delad hemlighet, förutom att parametern ersätts client_secret med två parametrar: a client_assertion_type och client_assertion .

Lyckat svar

Ett lyckat tokensvar ser ut så här:

{
    "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 denna 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 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 – detta är inte standard, och om det utelämnas används token för de omfång som begärdes i flödets första ben.
refresh_token En OAuth 2.0-uppdateringstoken. Appen kan använda denna token för att hämta ytterligare åtkomsttoken när den aktuella åtkomsttoken upphör att gälla. Refresh_tokens långlivade och kan användas för att behålla åtkomsten till resurser under längre tidsperioder. Mer information om hur du uppdaterar en åtkomsttoken finns i avsnittet nedan.
Obs! Anges endast om offline_access omfång har begärts.
id_token En JSON Web Token (JWT). Appen kan avkoda segmenten för denna token för att begära information om den användare som loggade in. Appen kan cachelagra värdena och visa dem, och konfidentiella klienter kan använda dem för auktorisering. Mer information om id_tokens finns i id_token reference .
Obs! Anges endast om openid omfång har begärts.

Felsvar

Felsvar ser ut så här:

{
  "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 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.
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 vid diagnostik.
timestamp Den tid då felet inträffade.
trace_id En unik identifierare för begäran som kan vara till hjälp vid diagnostik.
correlation_id En unik identifierare för begäran som kan hjälpa till med diagnostik över komponenter.

Felkoder för tokenslutpunktsfel

Felkod Description Klientåtgärd
invalid_request Protokollfel, till exempel en obligatorisk parameter 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 med en ny begäran till /authorize slutpunkten och kontrollera att code_verifier-parametern var korrekt.
unauthorized_client Den autentiserade klienten har inte behörighet att använda den här typen av auktoriseringsbegäran. 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 be användaren att ange anvisningar för att installera programmet och lägga till det i Azure AD.
invalid_client Klientautentisering misslyckades. Klientautentiseringsuppgifterna är inte giltiga. För att åtgärda det uppdaterar programadministratören autentiseringsuppgifterna.
unsupported_grant_type Auktoriseringsservern stöder inte beviljandetypen för auktorisering. Ändra typ av beviljande i begäran. Den här typen av fel bör endast inträffa under utvecklingen och identifieras under den inledande testningen.
invalid_resource Målresursen är ogiltig eftersom den inte finns, Azure AD kan inte hitta den eller så är den inte korrekt konfigurerad. Detta anger att resursen, om den finns, inte har konfigurerats i klientorganisationen. Programmet kan be användaren att ange anvisningar för att installera programmet och lägga till det i Azure AD.
interaction_required Icke-standard, eftersom OIDC-specifikationen endast kräver detta på /authorize slutpunkten. Begäran kräver användarinteraktion. Till exempel krävs ytterligare ett autentiseringssteg. 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 med begäran 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ändarens medgivande. Det här felet är inte standard eftersom det vanligtvis bara returneras på /authorize slutpunkten enligt OIDC-specifikationerna. Returneras när scope en parameter användes i kodinlösningsflödet som klientappen inte har behörighet att begära. Klienten bör skicka tillbaka användaren till slutpunkten /authorize 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 scope-parametern i autentiseringsbegäran till ett giltigt värde.

Anteckning

Ensidesappar kan få ett fel som anger att inlösning av token för korsande ursprung endast tillåts för klienttypen invalid_request "Ensidesapplikation". Detta anger att den omdirigerings-URI som används för att begära token inte har markerats som en spa omdirigerings-URI. Granska programregistreringsstegen om hur du aktiverar det här flödet.

Använda åtkomsttoken

Nu när du har skaffat en kan du använda token i begäranden till access_token webb-API:er genom att inkludera den i Authorization -huvudet:

GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Uppdatera åtkomsttoken

Access_tokens kortlivade och du måste uppdatera dem när de upphör att gälla för att fortsätta att komma åt resurser. Du kan göra det genom att skicka POST en annan begäran till /token slutpunkten, och den här gången ange refresh_token i stället för code . Uppdateringstoken är giltiga för alla behörigheter som klienten redan har fått medgivande för . Därför kan en uppdateringstoken som utfärdats för en begäran för användas för att begära en ny scope=mail.read åtkomsttoken för scope=api://contoso.com/api/UseResource .

Uppdateringstoken för webbappar och interna appar har inte någon angiven livslängd. 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ärdande på rätt sätt. Ensidesappar får dock en token med en livslängd på 24 timmar, vilket kräver en ny autentisering varje dag. Detta kan göras tyst i en iframe när cookies från tredje part är aktiverade, men måste göras i en bildruta på den översta nivån (antingen hel sidnavigering 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, men 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 när en ny uppdateringstoken har utfärdats till klienten."

Viktigt

För uppdateringstoken som skickas till en omdirigerings-URI registrerad som spa upphör uppdateringstoken att gälla efter 24 timmar. Ytterligare uppdateringstoken som förvärvas med den första uppdateringstoken förs över den förfallotiden, så appar måste vara förberedda på 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ågot UX, bara en ny inläsning av programmet, men webbläsaren måste besöka inloggningssidan i en övre bildruta för att kunna se inloggningssessionen. Detta beror på sekretessfunktioner i webbläsare som blockerarcookies 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 Description
tenant krävs Värdet {tenant} i sökvägen för begäran kan användas för att styra vem som kan logga in i programmet. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder.
client_id krävs Det program-ID (klient) som Azure Portal – Appregistreringar till 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 det här ben 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 token för resursen som anges i det första omfånget. En mer detaljerad förklaring av omfång finns i behörigheter, medgivande och omfång.
refresh_token krävs Den refresh_token som du skaffade i flödets andra ben.
client_secret krävs för webbappar Den programhemlighet som du skapade i appregistreringsportalen för din app. Det bör inte användas i en inbyggd app, eftersom client_secrets inte kan lagras på ett tillförlitligt sätt på enheter. Det krävs för webbappar och webb-API:er, som har möjlighet att lagra client_secret på ett säkert sätt på serversidan. Den här hemligheten måste vara URL-kodad. Mer information finns i URI Generic Syntax specification (URI:s specifikation för allmän syntax).

Lyckat svar

Ett lyckat tokensvar ser ut så här:

{
    "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 denna 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 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.
refresh_token En ny OAuth 2.0-uppdateringstoken. Du bör ersätta den gamla uppdateringstoken med denna nyligen köpta uppdateringstoken för att säkerställa att dina uppdateringstoken är giltiga så länge som möjligt.
Obs! Anges endast om offline_access omfång har begärts.
id_token En osignerad JSON Web Token (JWT). Appen kan avkoda segmenten för denna token för att begära information om den användare som loggade in. Appen kan cachelagra 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_tokens finns i id_token reference .
Obs! Anges endast om openid omfång har begärts.

Varning

Försök inte att validera eller läsa token för något API som du inte äger, inklusive token i det här exemplet, i din kod. Token för Microsoft-tjänster kan använda ett särskilt format som inte valideras som en JWT och kan också krypteras för konsumentanvändare (Microsoft-konto). Även om läsningstoken är ett användbart felsöknings- och inlärningsverktyg ska du inte ta beroenden av detta i koden eller förutsätta information 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 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.
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 vid diagnostik.
timestamp Den tid då felet inträffade.
trace_id En unik identifierare för begäran som kan vara till hjälp vid diagnostik.
correlation_id En unik identifierare för begäran som kan hjälpa till med diagnostik över komponenter.

En beskrivning av felkoderna och den rekommenderade klientåtgärden finns i Felkoder för tokenslutpunktsfel.