implicit beviljandeflöde för Microsofts identitetsplattform och OAuth 2.0

  • Artikel

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 /authorize-slutpunkten i stället för /token-slutpunkten. 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.

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:t!

Föredra 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 hämta 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 beviljande av OAuth2

Det implicita beviljandet ä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 tar ditt program emot 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 det implicita inloggningsflödet ser ut och avsnitten som följer beskriver varje steg i detalj.

Diagram som visar det implicita inloggningsflödet

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.

Viktigt

Om du vill begära en ID-token och/eller en åtkomsttoken måste appregistreringen i Microsoft Entra administrationscenter – Appregistreringar sidan ha motsvarande implicit beviljandeflöde aktiverat genom att välja ID-token och åtkomsttoken i avsnittet Implicit beviljande och hybridflöden. Om det inte är aktiverat 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=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
&nonce=678910
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. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i protokollgrunderna. 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 korrekt i resursklientorganisationen.
client_id krävs Program-ID:t (klient) som Microsoft Entra administrationscenter – Appregistreringar sidan som tilldelats till din app.
response_type krävs Måste inkluderas id_token för inloggning med OpenID Connect. Det 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 auktoriseringsslutpunkten utan att behöva göra en andra begäran till auktoriseringsslutpunkten. Om du använder token response_type måste parametern scope innehålla ett omfång som anger vilken resurs som token ska utfärdas för (till exempel user.read på Microsoft Graph). Den kan också innehålla code i stället token för för att tillhandahålla en auktoriseringskod 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 krävs En blankstegsavgränsad lista över 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 valfri Anger den metod som ska användas för att skicka tillbaka den resulterande token till din app. Standardinställningen ä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 som användaren var på.
nonce krävs 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 för tillfället är login, none, select_accountoch consent. 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 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 för OAuth-medgivande efter att 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 i förväg 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åketlogin_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 strömlinjeformad användarupplevelse. Den här parametern används ofta för branschspecifika appar som körs 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 förhindrar 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. 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. 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 metoden som anges i parametern response_mode .

Lyckat svar

Ett lyckat svar med response_mode=fragment och response_type=id_token+code ser ut så här (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 passar 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 täckande 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 i cachelagringssyfte.
scope Inkluderad om response_type innehåller token. Anger de omfång 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. Till exempel Microsoft Entra omfång som begärs när du loggar in med ett personligt konto.
id_token En signerad JSON-webbtoken (JWT). 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-token finns i id_token reference.
Observera: 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 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 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 felkodsträ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 ensidesappen kan du tyst hämta å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 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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.

Tips

Försök att 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 din användare)

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=6731de76-14a6-49ae-97bc-6eba6914391e&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 cookiesupport 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å angivet redirect_uri, med hjälp av den metod som anges i parametern response_mode .

Lyckat svar

Ett lyckat svar med ser response_mode=fragment 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 täckande sträng.
token_type Detta kommer alltid att vara Bearer.
expires_in Anger hur många sekunder token är giltig i cachelagringssyfte.
scope Anger omfången 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 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_tokens finns i referensenid_token.
Observera: 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 Beskrivning
error En felkodsträ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å det sätt som passar ditt program.

Uppdaterar 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 med jämna mellanrum. Om du vill uppdatera någon av tokentyperna kan du utföra samma dolda iframe-begäran ovan med hjälp av parametern prompt=none för att styra identitetsplattformens beteende. Om du vill ta emot en ny ID-token måste du använda id_token i response_type och scope=openidsamt 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 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 från ett webbprogram helt 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 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. De tillåtna värdena är common, organizations, consumersoch klientidentifierare. Mer information finns i protokollgrunderna.
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 omdirigerings-URI:erna som registrerats för programmet. Om det inte ingår visas ett allmänt meddelande av Microsofts identitetsplattform.

Nästa steg