implicit beviljandeflöde för Microsofts identitetsplattform och OAuth 2.0
Microsofts identitetsplattform stöder implicit beviljandeflöde för OAuth 2.0 enligt beskrivningen i OAuth 2.0-specifikationen. Den definierande egenskapen för implicit beviljande är att token (ID-token eller åtkomsttoken) returneras direkt från slutpunkten /authorize i stället för slutpunkten /token. Detta används ofta som en del av auktoriseringskodflödet, i det som kallas "hybridflöde" – hämtar ID-token på /authorize-begäran tillsammans med en auktoriseringskod.
Den här artikeln beskriver hur du programmerar direkt mot protokollet i ditt program för att begära token från Microsoft Entra-ID. 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 skyddade webb-API:er. Ta också en titt på exempelapparna som använder MSAL.
Föredrar autentiseringskodflödet
Med planerna för att ta bort cookies från tredje part från webbläsare är det implicita beviljandeflödet inte längre en lämplig autentiseringsmetod. Funktionerna för tyst enkel inloggning (SSO) i det implicita flödet fungerar inte utan cookies från tredje part, vilket gör att program bryts när de försöker få en ny token. Vi rekommenderar starkt att alla nya program använder det auktoriseringskodflöde som nu stöder ensidesappar i stället för det implicita flödet. Befintliga ensidesappar bör också migreras till auktoriseringskodflödet.
Lämpliga scenarier för implicit OAuth2-beviljande
Det implicita bidraget är bara tillförlitligt för den första interaktiva delen av ditt inloggningsflöde, där bristen på cookies från tredje part inte påverkar ditt program. Den här begränsningen innebär att du bör använda den exklusivt som en del av hybridflödet, där ditt program begär en kod samt en token från auktoriseringsslutpunkten. I ett hybridflöde får ditt program en kod som kan lösas in mot en uppdateringstoken, vilket säkerställer att appens inloggningssession förblir giltig över tid.
Protokolldiagram
Följande diagram visar hur hela implicita inloggningsflödet ser ut och de avsnitt som följer beskriver varje steg i detalj.
Skicka inloggningsbegäran
Om du först vill logga in användaren i din app kan du skicka en OpenID-Anslut autentiseringsbegäran och hämta en id_token från Microsofts identitetsplattform.
Viktigt!
Om du vill begära en ID-token och/eller en åtkomsttoken måste appregistreringen i administrationscentret för Microsoft Entra – Appregistreringar sidan ha motsvarande implicita beviljandeflöde aktiverat genom att välja ID-token och åtkomsttoken i avsnittet Implicit beviljande och hybridflöden. Om den inte är aktiverad returneras ett unsupported_response fel:
The provided value for the input parameter 'response_type' is not allowed for this client. Expected value is 'code'
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
| 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. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i grunderna för protokoll. För gästscenarier där du signerar en användare från en klientorganisation till en annan klientorganisation måste du ange klientidentifieraren för att logga in dem korrekt i resursklientorganisationen. |
client_id |
required | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar sida som tilldelats din app. |
response_type |
required | Måste inkluderas id_token för OpenID Anslut inloggning. Den kan också innehålla response_type, token. Om du använder token det här kan din app ta emot en åtkomsttoken omedelbart från auktorisera slutpunkten utan att behöva göra en andra begäran till auktorisera slutpunkten. Om du använder token response_type måste parametern scope innehålla ett omfång som anger vilken resurs som ska utfärda token för (till exempel user.read i Microsoft Graph). Den kan också innehålla code i stället för att ange en auktoriseringskod token för användning i auktoriseringskodflödet. Det här id_token+code svaret kallas ibland för hybridflödet. |
redirect_uri |
rekommenderas | Omdirigerings-URI:n för din app, 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. |
scope |
required | En blankstegsavgränsad lista med omfång. För OpenID-Anslut (id_tokens) måste den innehålla omfånget openid, som översätts till behörigheten "Logga in dig" i användargränssnittet för medgivande. Du kan också inkludera omfången email och profile för att få åtkomst till ytterligare användardata. Du kan också inkludera andra omfång i den här begäran för att begära medgivande till olika resurser, om en åtkomsttoken begärs. |
response_mode |
valfri | Anger vilken metod som ska användas för att skicka tillbaka den resulterande token till din app. Standardvärdet är att fråga efter bara en åtkomsttoken, men fragment om begäran innehåller en id_token. |
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. Tillståndet används också för att koda information om användarens tillstånd i appen innan autentiseringsbegäran inträffade, till exempel sidan eller vyn de var på. |
nonce |
required | Ett värde som ingår i begäran, som genereras av appen, som inkluderas i den resulterande 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. Krävs endast när en id_token begärs. |
prompt |
valfri | Anger vilken typ av användarinteraktion som krävs. De enda giltiga värdena just nu är login, none, select_accountoch consent. prompt=login tvingar användaren att ange sina autentiseringsuppgifter på begäran och negera enkel inloggning. prompt=none är motsatsen – det ser till att användaren inte visas med någon interaktiv fråga alls. Om begäran inte kan slutföras tyst via enkel inloggning returnerar Microsofts identitetsplattform ett fel. prompt=select_account skickar användaren till en kontoväljare där alla konton som sparas i sessionen visas. prompt=consent utlöser dialogrutan OAuth-medgivande när användaren har loggat in och ber användaren att bevilja behörigheter till appen. |
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, om du känner till användarnamnet i förväg. Ofta använder appar 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 den över den e-postbaserade identifieringsprocessen som användaren går igenom på inloggningssidan, vilket leder till en något mer effektiviserad användarupplevelse. Den här parametern används ofta för branschspecifika appar som fungerar i en enda klientorganisation, där de anger ett domännamn inom en viss klientorganisation och vidarebefordrar användaren till federationsprovidern för den klientorganisationen. Det här tipset hindrar gäster från att logga in i det här programmet och begränsar användningen av molnautentiseringsuppgifter som FIDO. |
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, medgivande och appar för flera klientorganisationer.
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
Ett lyckat svar som använder response_mode=fragment och response_type=id_token+code ser ut som följande (med radbrytningar för läsbarhet):
GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
| Parameter | Description |
|---|---|
code |
Inkluderad om response_type innehåller code. Det är en auktoriseringskod som är lämplig för användning i auktoriseringskodflödet. |
access_token |
Inkluderad om response_type innehåller token. Den åtkomsttoken som appen begärde. Åtkomsttoken ska inte avkodas eller inspekteras på annat sätt. Den bör behandlas som en ogenomskinlig sträng. |
token_type |
Inkluderad om response_type innehåller token. Detta kommer alltid att vara Bearer. |
expires_in |
Inkluderad om response_type innehåller token. Anger hur många sekunder token är giltig för cachelagring. |
scope |
Inkluderad om response_type innehåller token. Anger omfången som access_token ska vara giltiga för. Får inte innehålla alla begärda omfång om de inte är tillämpliga för användaren. Microsoft Entra-omfång som till exempel begärs när du loggar in med ett personligt konto. |
id_token |
En signerad JSON-webbtoken (JWT). 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-token finns i id_token reference. Obs! Tillhandahålls endast om openid omfånget begärdes och response_type inkluderades id_tokens. |
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. |
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
Felsvar kan också skickas till så att redirect_uri appen kan hantera dem på rätt sätt:
GET https://localhost/myapp/#
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 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. |
Hämta åtkomsttoken tyst
Viktigt!
Den här delen av det implicita flödet kommer sannolikt inte att fungera för ditt program eftersom det används i olika webbläsare på grund av att cookies från tredje part tas bort som standard. Även om detta fortfarande fungerar i Chromium-baserade webbläsare som inte finns i Incognito, bör utvecklare överväga att använda den här delen av flödet. I webbläsare som inte stöder cookies från tredje part får du ett felmeddelande som anger att inga användare är inloggade, eftersom inloggningssidans sessionscookies har tagits bort av webbläsaren.
Nu när du har loggat in användaren i din ensidesapp kan du tyst få åtkomsttoken för att anropa webb-API:er som skyddas av Microsofts identitetsplattform, till exempel Microsoft Graph. Även om du redan har fått en token med hjälp av token response_type kan du använda den här metoden för att hämta token till ytterligare resurser utan att omdirigera användaren att logga in igen.
I det normala OpenID-Anslut/OAuth-flödet gör du detta genom att göra en begäran till Microsofts identitetsplattform /token slutpunkten. Du kan göra begäran i en dold iframe för att hämta nya token för andra webb-API:er:
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&response_mode=fragment
&state=12345
&nonce=678910
&prompt=none
&login_hint=myuser@mycompany.com
Mer information om frågeparametrarna i URL:en finns i skicka inloggningsbegäran.
Dricks
Prova att kopiera och klistra in begäran nedan på en webbläsarflik! (Glöm inte att ersätta login_hint värdena med rätt värde för användaren)
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&response_type=token&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&scope=https%3A%2F%2Fgraph.microsoft.com%2Fuser.read&response_mode=fragment&state=12345&nonce=678910&prompt=none&login_hint={your-username}
Observera att detta fungerar även i webbläsare utan stöd för cookies från tredje part, eftersom du anger detta direkt i ett webbläsarfält i stället för att öppna det i en iframe.
Tack vare parametern prompt=none lyckas eller misslyckas den här begäran omedelbart och återgår till ditt program. Svaret skickas till din app på angiven redirect_uri, med hjälp av den metod som anges i parametern response_mode .
Lyckat svar
Ett lyckat svar med hjälp av response_mode=fragment ser ut så här:
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fdirectory.read
| Parameter | Description |
|---|---|
access_token |
Inkluderad om response_type innehåller token. Den åtkomsttoken som appen begärde, i det här fallet för Microsoft Graph. Åtkomsttoken ska inte avkodas eller inspekteras på annat sätt. Den bör behandlas som en ogenomskinlig sträng. |
token_type |
Detta kommer alltid att vara Bearer. |
expires_in |
Anger hur många sekunder token är giltig för cachelagring. |
scope |
Anger vilka omfång som åtkomsttoken ska vara giltig för. Får inte innehålla alla begärda omfång, om de inte är tillämpliga för användaren (om Microsoft Entra-omfång begärs när ett personligt konto används för att logga in). |
id_token |
En signerad JSON-webbtoken (JWT). Inkluderad om response_type innehåller id_token. 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_tokens finns i referensenid_token. Obs! Tillhandahålls endast om openid omfång begärdes. |
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. |
Felsvar
Felsvar kan också skickas till så att redirect_uri appen kan hantera dem på rätt sätt. När det gäller prompt=noneär ett förväntat fel:
GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
| Parameter | Description |
|---|---|
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. |
Om du får det här felet i iframe-begäran måste användaren interaktivt logga in igen för att hämta en ny token. Du kan välja att hantera det här fallet på vilket sätt som helst för ditt program.
Uppdatera token
Det implicita beviljandet tillhandahåller inte uppdateringstoken. Både ID-token och åtkomsttoken upphör att gälla efter en kort tidsperiod, så din app måste vara beredd att uppdatera dessa token regelbundet. Om du vill uppdatera någon av tokentyperna kan du utföra samma dolda iframe-begäran ovanifrån med hjälp av parametern prompt=none för att styra identitetsplattformens beteende. Om du vill ta emot en ny ID-token ska du använda id_token i response_type och scope=openid, samt en nonce parameter.
I webbläsare som inte stöder cookies från tredje part resulterar detta i ett fel som anger att ingen användare är inloggad.
Skicka en utloggningsbegäran
Med OpenID-Anslut end_session_endpoint kan din app skicka en begäran till Microsofts identitetsplattform för att avsluta en användares session och rensa cookies som angetts av Microsofts identitetsplattform. Om du vill logga ut en användare helt från ett webbprogram bör din app avsluta sin egen session med användaren (vanligtvis genom att rensa en tokencache eller släppa cookies) och sedan omdirigera webbläsaren till:
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
| 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. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i grunderna för protokoll. |
post_logout_redirect_uri |
rekommenderas | Den URL som användaren ska returneras till när utloggningen har slutförts. Det här värdet måste matcha en av de omdirigerings-URI:er som registrerats för programmet. Om den inte ingår visas ett allmänt meddelande av Microsofts identitetsplattform. |