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 microsofts autentiseringsbibliotek (MSAL) som stöds i stället för att hämta token och anropa skyddade webb-API:er. En lista över kodexempel som använder MSAL finns i Microsofts identitetsplattform kodexempel.
Varning
Microsoft rekommenderar att du inte använder det implicita beviljandeflödet. I de flesta scenarier är säkrare alternativ tillgängliga och rekommenderas. Vissa konfigurationer av det här flödet kräver en mycket hög grad av förtroende för programmet och medför risker som inte finns i andra flöden. Du bör bara använda det här flödet när andra säkrare flöden inte är livskraftiga. Mer information finns i säkerhetsproblemen med implicit beviljandeflöde.
Protokolldiagram
Följande diagram visar hur hela implicita inloggningsflödet ser ut och de avsnitt som följer beskriver varje steg i detalj.
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 och 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.
Föredrar autentiseringskodflödet
När vissa webbläsare tar bort stöd för cookies från tredje part ä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.
Säkerhetsproblem med implicit beviljandeflöde
Det implicita beviljandeflödet är avsett för traditionella webbprogram där servern har kontroll över bearbetningen av POST-data på ett säkert sätt. Det finns två huvudsakliga sätt att leverera token med implicit beviljandeflöde: där response_mode returneras som ett URL-fragment eller som en frågeparameter (med och GET form POST ). I det implicita flödet där response_mode=form_postlevereras token säkert via ett HTML-formulär POST till klientens omdirigerings-URI. Den här metoden säkerställer att token inte exponeras i URL-fragmentet, vilket i sin tur undviker risken för tokenläckage via webbläsarhistorik eller referenshuvuden.
Säkerhetsproblemen med det implicita flödet uppstår när token levereras med hjälp av response_mode=fragment. URL-fragmentet är den del av URL:en som kommer efter symbolen # och skickas inte till servern när webbläsaren begär en ny sida, men är tillgänglig för JavaScript som körs i webbläsaren. Det innebär att token exponeras för javascript som körs på sidan, vilket kan vara en säkerhetsrisk om sidan innehåller skript från tredje part. Dessa säkerhetsproblem för token i SPA:er gäller inte heller för det implicita flödet med form POST.
När ska du tillåta att en åtkomsttoken eller ID-token utfärdas när du begär det med implicit beviljande eller hybridflöde?
Implicit beviljande och hybridflöde är inte lika säkert som andra OAuth-flöden. Om det inte är absolut nödvändigt bör du inte tillåta att en åtkomst- eller ID-token utfärdas när den begärs med implicit beviljande eller hybridflöde i din appregistrering. Om du (eller dina utvecklare) använder MSAL i ditt program för att implementera autentisering och auktorisering behöver inget av fälten aktiveras.
Men om du (eller dina utvecklare) inte använder MSAL i ditt program beskriver följande tabell när åtkomsttoken eller ID-token ska aktiveras.
| Typ av program som du skapar | Token som du bör aktivera i Appregistrering |
|---|---|
| Ett SPA (ensidesprogram) som inte använder auktoriseringskodflödet med PKCE | Åtkomsttoken och ID-token |
| Ett webb- eller SPA-program som anropar ett webb-API via JavaScript med implicit flöde | Åtkomsttoken och ID-token |
| En ASP.NET Core-webbapp och andra webbappar som använder hybridautentisering | ID-token |
Skicka inloggningsbegäran
Om du först vill logga in användaren i din app kan du skicka en OpenID Connect-autentiseringsbegäran och hämta en id_token från Microsofts identitetsplattform.
Viktig
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 |
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. 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 |
krävs | Det program-ID (klient)-ID som administrationscentret för Microsoft Entra – Appregistreringar sida som tilldelats din app. |
response_type |
krävs | Måste inkluderas id_token för OpenID Connect-inloggning. Den kan också innehålla response_type, token. Om du använder token det här kan din app ta emot en åtkomsttoken direkt från slutpunkten /authorize utan att behöva göra en andra begäran till slutpunkten /authorize. 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 |
rekommenderad | Omdirigerings-URI:n för din app, där autentiseringssvar skickas och tas emot i din app. Den måste exakt matcha en av de omdirigerings-URI:er som du registrerade i administrationscentret för Microsoft Entra, förutom att den måste vara URL-kodad. |
scope |
krävs | En blankstegsavgränsad lista med omfång. För OpenID Connect (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 |
rekommenderad | 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 åtkomsttoken, men fragment om begäran innehåller en id_token. Av säkerhetsskäl rekommenderar vi att du använder form_post det implicita flödet för att säkerställa att token inte exponeras i URL-fragmentet. |
state |
rekommenderad | Ett värde som ingår i begäran returneras också 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 |
krävs | Ett värde som ingår i begäran, som genereras av appen, som ingår 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 för den begäran och negera enkel inloggning. prompt=none är motsatsen – det säkerställer att användaren inte visas med någon interaktiv fråga 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 sparats 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, vilket 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 till att användaren har samtyckt till de behörigheter som anges i frågeparameternscope. 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 | Beskrivning |
|---|---|
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. Det här är alltid en 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 ett eller flera omfång som access_token är 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 | 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. |
Hämta åtkomsttoken tyst
Nu när användaren är inloggad i ensidesappen 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.
Viktig
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.
I det normala OpenID Connect/OAuth-flödet skulle du göra 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 följande begäran på en webbläsarflik med hjälp av en riktig client_id och username från din appregistrering. Detta gör att du kan se den tysta tokenbegäran i praktiken.
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={your-client-id}&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={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 | Beskrivning |
|---|---|
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 |
Det här är alltid en Bearer. |
expires_in |
Anger hur många sekunder token är giltig för cachelagring. |
scope |
Anger ett eller flera omfång som åtkomsttoken är 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. Om 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 | 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. |
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 ger 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 som tidigare beskrivits 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 parametern response_type och scope=openidoch .nonce
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 Connect 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 |
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. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i grunderna för protokoll. |
post_logout_redirect_uri |
rekommenderad | 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 användaren inte ingår visas ett allmänt meddelande av Microsofts identitetsplattform. |