Microsofts identitetsplattform och implicit beviljandeflöde

Den Microsofts identitetsplattform stöder flödet för implicit OAuth 2.0-beviljande enligt beskrivningen i OAuth 2.0-specifikationen. Den definierande egenskapen för det implicita beviljandet ä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 idet som kallas "hybridflöde" – hämtning av ID-token på /authorize-begäran tillsammans med en auktoriseringskod.

Den här artikeln beskriver hur du programmerar direkt mot protokollet i programmet för att begära token från Azure AD. När det är möjligt rekommenderar vi att du använder MSAL (Microsoft Authentication Libraries) i stället för att Hämta tokens och anropa säkra webb-API: er. Ta också en titt på de exempel appar 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:er!

Prioritera auth-kodflödet

Med planer på att cookies från tredje part ska tas bort från webbläsareär det implicita beviljandeflödet inte längre en lämplig autentiseringsmetod. Funktionerna för tyst enkel inloggning 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 auktoriseringskodflödet som nu stöder ensidesappar i stället för det implicita flödet och att befintliga ensidesappar även börjar migrera till auktoriseringskodflödet.

Lämpliga scenarier för implicit OAuth2-beviljande

Det implicita beviljandet är endast tillförlitligt för den första, interaktiva delen av inloggningsflödet, där bristen på cookies från tredje part inte kan påverka 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. Detta säkerställer att ditt program tar 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 de avsnitt som följer beskriver varje steg i detalj.

Diagram som visar det implicita inloggningsflödet

Skicka inloggningsbegäran

För att först logga in användaren i din app kan du skicka en OpenID Anslut-autentiseringsbegäran och id_token få en från Microsofts identitetsplattform.

Viktigt

För att kunna begära en ID-token och/eller en åtkomsttoken måste appregistreringen på sidan Azure Portal – Appregistreringar ha motsvarande implicit beviljandeflöde aktiverat genom att välja ID-token och åtkomsttoken i avsnittet Implicit beviljande och hybridflöden. Om den inte är aktiverad unsupported_response returneras ett 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

Tips

Om du vill testa att logga in med det implicita flödet klickar du på https://login.microsoftonline.com/common/oauth2/v2.0/authorize.. . När du har loggat in ska webbläsaren omdirigeras https://localhost/myapp/ till med en i id_token adressfältet.

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. 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 id_token inkluderas för Anslut openID-inloggning. Den kan även innehålla response_type token . Med hjälp av här kan din app ta emot en åtkomsttoken direkt från auktorisera slutpunkten utan att behöva token göra en andra begäran till auktorisera slutpunkten. Om du använder response_type måste parametern innehålla ett omfång som anger vilken resurs som token ska token scope utfärdas för (till exempel user.read på Microsoft Graph). Den kan också innehålla code i stället för för att tillhandahålla en token auktoriseringskod, för användning i auktoriseringskodflödet. Det id_token och kodsvar kallas ibland för hybridflödet.
redirect_uri Rekommenderas 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.
scope krävs En blankstegsavgränsad lista med omfång. För OpenID Anslut (id_tokens) måste det innehålla omfånget , som översätts till behörigheten "Logga in" i gränssnittet openid för medgivande. Om du vill kan du även inkludera email profile omfången och 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 den resulterande token tillbaka 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 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. Tillståndet används också för att koda information om användarens tillstånd i appen innan autentiseringsbegäran gjordes, 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 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. 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_account" och "consent". 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 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 för OAuth-medgivande efter att användaren har loggar in, där användaren uppmanas 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. Appar använder ofta den här parametern vid omauthenticering efter att det valfria anspråket redan har extraherats login_hint 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 mer effektiv användarupplevelse. Den här parametern används ofta för affärsappar som fungerar i en enda klientorganisation, där de tillhandahåller ett domännamn inom en viss klientorganisation och vidarebefordrar användaren till federationsprovidern för den klientorganisationen. Observera att 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 innehavare.

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 response_mode=fragment och ser ut som följande response_type=id_token+code (med radbrytningar för att göra det lätt att göra det):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parameter Beskrivning
code Inkluderas om response_type innehåller code . Det här är en auktoriseringskod som lämpar sig för användning i auktoriseringskodflödet.
access_token Inkluderas om response_type innehåller token . Den åtkomsttoken som appen begärde. Åtkomsttoken ska inte avkodas eller inspekteras på annat sätt, den ska behandlas som en täckande sträng.
token_type Inkluderas om response_type innehåller token . Kommer alltid att vara Bearer .
expires_in Inkluderas om response_type innehåller token . Anger antalet sekunder som token är giltig i cachelagringssyfte.
scope Inkluderas om response_type innehåller token . Anger de omfång för vilka access_token ska vara giltiga. Omfattar kanske inte alla begärda omfång, om de inte är tillämpliga för användaren (om endast Azure AD-omfång begärs när ett personligt konto används för att logga in).
id_token En signerad 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 och response_type id_tokens inkluderats.
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 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

Felsvar kan också skickas till redirect_uri så att 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 i bakgrunden

Viktigt

Den här delen av det implicita flödet fungerar troligen inte för ditt program eftersom det används i olika webbläsare på grund av borttagning av cookies från tredje part som standard. Detta fungerar fortfarande i Chromium webbläsare som inte är i Incognito, men utvecklare bör inte ö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 om 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 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 response_type kan du använda den här metoden för att hämta token till ytterligare resurser utan att behöva omdirigera användaren för att token logga in igen.

I det normala OpenID Anslut-/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

Prova att & klistra in begäran nedan på en webbläsarflik! (Glöm inte att ersätta värdena login_hint med rätt värde för användaren)

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 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 prompt=none parametern lyckas eller misslyckas den här begäran omedelbart och återgår till ditt program. Svaret skickas till din app på den angivna , med redirect_uri hjälp av den metod som anges i response_mode parametern .

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 Inkluderas 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 granskas på annat sätt, den ska behandlas som en täckande sträng.
token_type Kommer alltid att vara Bearer .
expires_in Anger antalet sekunder som token är giltig i cachelagringssyfte.
scope Anger de omfång som access_token ska vara giltiga. Kanske inte innehåller alla begärda omfång, om de inte var tillämpliga för användaren (om endast Azure AD-omfång begärs när ett personligt konto används för att logga in).
id_token En signerad JSON Web Token (JWT). Inkluderas om response_type innehåller id_token . 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 referensen.
Obs! Anges endast om openid omfång har begärts.
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 redirect_uri så att appen kan hantera dem på rätt sätt. När det gäller prompt=none kommer ett förväntat fel att vara:

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 logga in interaktivt igen för att hämta en ny token. Du kan välja att hantera det här fallet på det sätt som är logiskt för ditt program.

Uppdatera token

Det implicita beviljandet tillhandahåller inte uppdateringstoken. Både id_token s och s upphör att gälla efter en kort tidsperiod, så din app måste vara beredd på att uppdatera dessa token access_token regelbundet. Om du vill uppdatera någon av dessa typer av token kan du utföra samma dolda iframe-begäran ovan med hjälp av parametern för prompt=none att styra identitetsplattformens beteende. Om du vill ta emot en id_token ny måste du använda i och , samt en id_token response_type scope=openid 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 ut logga ut-begäran

OpenID-Anslut tillåter att din app skickar en begäran till Microsofts identitetsplattform för att avsluta en användares session och rensa cookies som anges end_session_endpoint av Microsofts identitetsplattform . För att helt logga ut en användare från en webbapp bör din app avsluta sin egen session med användaren (vanligtvis genom att rensa en tokencache eller ta bort 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. Tillåtna värden är common , organizations , och consumers klientorganisationsidentifierare. Mer information finns i protokoll grunder.
post_logout_redirect_uri Rekommenderas Den URL som användaren ska returneras till när utloggningen är klar. Det här värdet måste matcha ett av de omdirigerings-URI:er som registrerats för programmet. Om användaren inte ingår visas ett allmänt meddelande av användaren Microsofts identitetsplattform.

Nästa steg