Impliciete toekenningsstroom voor Microsoft Identity Platform en OAuth 2.0

  • Artikel

Het Microsoft Identity Platform ondersteunt de impliciete toekenningsstroom OAuth 2.0, zoals beschreven in de OAuth 2.0-specificatie. Het definiërende kenmerk van de impliciete toekenning is dat tokens (id-tokens of toegangstokens) rechtstreeks worden geretourneerd vanaf het /authorize-eindpunt in plaats van het /token-eindpunt. Dit wordt vaak gebruikt als onderdeel van de autorisatiecodestroom, in wat de hybride stroom wordt genoemd: het ophalen van het id-token voor de aanvraag /authorize, samen met een autorisatiecode.

In dit artikel wordt beschreven hoe u rechtstreeks programma's kunt uitvoeren op basis van het protocol in uw toepassing om tokens aan te vragen bij Microsoft Entra ID. Indien mogelijk raden we u aan om in plaats daarvan de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken om tokens te verkrijgen en beveiligde web-API's aan te roepen. Bekijk ook de voorbeeld-apps die gebruikmaken van MSAL.

De voorkeur geven aan de verificatiecodestroom

Met de plannen voor het verwijderen van cookies van derden uit browsers is de impliciete toekenningsstroom geen geschikte verificatiemethode meer. De stille functies voor eenmalige aanmelding (SSO) van de impliciete stroom werken niet zonder cookies van derden, waardoor toepassingen worden onderbroken wanneer ze proberen een nieuw token te verkrijgen. We raden u ten zeerste aan dat alle nieuwe toepassingen gebruikmaken van de autorisatiecodestroom die nu ondersteuning biedt voor apps met één pagina in plaats van de impliciete stroom. Bestaande apps met één pagina moeten ook worden gemigreerd naar de autorisatiecodestroom.

Geschikte scenario's voor de impliciete OAuth2-toekenning

De impliciete toekenning is alleen betrouwbaar voor het eerste, interactieve deel van uw aanmeldingsstroom, waarbij het ontbreken van cookies van derden geen invloed heeft op uw toepassing. Deze beperking betekent dat u deze uitsluitend moet gebruiken als onderdeel van de hybride stroom, waarbij uw toepassing een code en een token van het autorisatie-eindpunt aanvraagt. In een hybride stroom ontvangt uw toepassing een code die kan worden ingewisseld voor een vernieuwingstoken, zodat de aanmeldingssessie van uw app na verloop van tijd geldig blijft.

Protocoldiagram

In het volgende diagram ziet u hoe de volledige impliciete aanmeldingsstroom eruitziet en in de volgende secties wordt elke stap in detail beschreven.

Diagram showing the implicit sign-in flow

De aanmeldingsaanvraag verzenden

Als u de gebruiker in eerste instantie wilt aanmelden bij uw app, kunt u een OpenID Connect-verificatieaanvraag verzenden en een id_token ophalen uit Microsoft Identity Platform.

Belangrijk

Als u een id-token en/of een toegangstoken wilt aanvragen, moet de app-registratie in het Microsoft Entra-beheercentrum - App-registraties pagina de bijbehorende impliciete toekenningsstroom hebben ingeschakeld door id-tokens en toegangstokens te selecteren in de sectie Impliciete toekenning en hybride stromen. Als deze niet is ingeschakeld, wordt er een unsupported_response fout geretourneerd:

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 Type Beschrijving
tenant vereist De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. De toegestane waarden zijn common, organizations, consumers en tenant-id's. Zie basisprincipes van protocollen voor meer informatie. Belangrijk: voor gastscenario's waarbij u een gebruiker van de ene tenant overzet in een andere tenant, moet u de tenant-id opgeven om ze correct aan te melden bij de resourcetenant.
client_id vereist De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties pagina toegewezen aan uw app.
response_type vereist Moet id_token bevatten voor aanmelding bij OpenID Connect. Het kan ook de response_type, token. Als u token hier gebruikt, kan uw app direct vanaf het autorisatie-eindpunt een toegangstoken ontvangen zonder dat u een tweede aanvraag hoeft te doen voor het autorisatie-eindpunt. Als u de token response_type gebruikt, moet de scope parameter een bereik bevatten dat aangeeft voor welke resource het token moet worden opgegeven (bijvoorbeeld user.read in Microsoft Graph). Het kan ook code bevatten in plaats van token om een autorisatiecode te bieden voor gebruik in de autorisatiecodestroom. Dit id_token+code antwoord wordt ook wel de hybride stroom genoemd.
redirect_uri aanbevolen De omleidings-URI van uw app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in de portal, behalve dat deze URL-gecodeerd moet zijn.
scope vereist Een door spaties gescheiden lijst met bereiken. Voor OpenID Verbinding maken (id_tokens) moet het bereik openidzijn opgenomen. Dit wordt omgezet in de machtiging 'Aanmelden' in de gebruikersinterface van toestemming. U kunt eventueel ook de bereiken email en profile voor het verkrijgen van toegang tot aanvullende gebruikersgegevens opnemen. U kunt ook andere bereiken opnemen in deze aanvraag voor het aanvragen van toestemming voor verschillende resources, als er een toegangstoken wordt aangevraagd.
response_mode optioneel Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. Standaard wordt alleen een toegangstoken opgevraagd, maar fragmenteer als de aanvraag een id_token bevat.
state aanbevolen Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het tokenantwoord. Het kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt voor om aanvallen van aanvraagvervalsing op meerdere sites te voorkomen. De status wordt ook gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag is opgetreden, zoals de pagina of weergave waarop ze zich bevonden.
nonce vereist Een waarde die is opgenomen in de aanvraag, gegenereerd door de app, die als claim wordt opgenomen in het resulterende id-token. De app kan deze waarde vervolgens verifiëren om aanvallen waarbij tokens worden herhaald te beperken. De waarde is doorgaans een gerandomiseerde, unieke tekenreeks die kan worden gebruikt om de oorsprong van de aanvraag te identificeren. Alleen vereist wanneer een id_token wordt aangevraagd.
prompt optioneel Geeft het type gebruikersinteractie aan dat vereist is. De enige geldige waarden op dit moment zijn login, none, select_account en consent. prompt=login dwingt de gebruiker om zijn referenties op die aanvraag in te voeren, waardoor eenmalige aanmelding wordt genegeerd. prompt=none is het tegenovergestelde - het zorgt ervoor dat de gebruiker geen interactieve prompt te zien krijgt. Als de aanvraag niet op de achtergrond kan worden voltooid via SSO, retourneert het Microsoft Identity Platform een fout. prompt=select_account stuurt de gebruiker naar een accountkiezer waar alle accounts die in de sessie worden onthouden, worden weergegeven. prompt=consent activeert het dialoogvenster OAuth-toestemming nadat de gebruiker zich heeft aangemeld en vraagt de gebruiker machtigingen te verlenen aan de app.
login_hint optioneel U kunt deze parameter gebruiken om de gebruikersnaam en het e-mailadresveld van de aanmeldingspagina voor de gebruiker vooraf in te vullen, als u de gebruikersnaam van tevoren kent. Apps gebruiken deze parameter vaak tijdens herauthenticatie, nadat ze de login_hintoptionele claim al hebben geëxtraheerd uit een eerdere aanmelding.
domain_hint optioneel Indien opgenomen, wordt het detectieproces op basis van e-mail overgeslagen dat de gebruiker doorloopt op de aanmeldingspagina, wat leidt tot een iets gestroomlijndere gebruikerservaring. Deze parameter wordt vaak gebruikt voor Line-Of-Business-apps die in één tenant werken, waarbij ze een domeinnaam binnen een bepaalde tenant opgeven, waarbij de gebruiker doorstuurt naar de federatieprovider voor die tenant. Deze hint voorkomt dat gasten zich aanmelden bij deze toepassing en beperkt het gebruik van cloudreferenties zoals FIDO.

Op dit moment wordt de gebruiker gevraagd om zijn referenties in te voeren en de verificatie te voltooien. Microsoft Identity Platform zorgt er ook voor dat de gebruiker toestemming heeft gegeven voor de machtigingen die zijn aangegeven in de queryparameter scope. Als de gebruiker voor geen van deze machtigingen toestemming heeft gegeven, wordt de gebruiker gevraagd toestemming te geven voor de vereiste machtigingen. Zie machtigingen, toestemming en apps met meerdere tenants voor meer informatie.

Zodra de gebruiker toestemming heeft geverifieerd en toestemming verleent, retourneert Microsoft Identity Platform een antwoord op uw app op de aangegeven redirect_uri, waarbij gebruik wordt gemaakt van de methode die is opgegeven in de parameter response_mode.

Succesvolle respons

Een geslaagde reactie met behulp van response_mode=fragment en response_type=id_token+code ziet er als volgt uit (met regeleinden voor leesbaarheid):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parameter Description
code Inclusief als response_typecode bevat. Het is een autorisatiecode die geschikt is voor gebruik in de autorisatiecodestroom.
access_token Inclusief als response_typetoken bevat. Het toegangstoken dat door de app is aangevraagd. Het toegangstoken mag niet worden gedecodeerd of anderszins geïnspecteerd. Het moet worden behandeld als een ondoorzichtige tekenreeks.
token_type Inclusief als response_typetoken bevat. Dit zal altijd zijn Bearer.
expires_in Inclusief als response_typetoken bevat. Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
scope Inclusief als response_typetoken bevat. Geeft de bereiken aan waarvoor de access_token geldig is. Mag niet alle aangevraagde bereiken bevatten als ze niet van toepassing waren op de gebruiker. Microsoft Entra-bereiken die bijvoorbeeld zijn aangevraagd bij het aanmelden met een persoonlijk account.
id_token Een ondertekend JSON-webtoken (JWT). De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. Zie voor meer informatie over id-tokens de id_token reference.
Opmerking: Alleen opgegeven als het bereik openid is aangevraagd en response_typeid_tokens bevatte.
state Als een statusparameter is opgenomen in de aanvraag, wordt dezelfde waarde weergegeven in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn.

Waarschuwing

Probeer geen tokens te valideren of te lezen voor een API waarvan u geen eigenaar bent, inclusief de tokens in dit voorbeeld, in uw code. Tokens voor Microsoft-services kunnen een speciale indeling gebruiken die niet wordt gevalideerd als een JWT, en kunnen ook worden versleuteld voor consumentengebruikers (Microsoft-account). Hoewel het lezen van tokens een handig hulpprogramma voor foutopsporing is en een leerfunctie heeft, hoeft u hier geen afhankelijkheden van te maken in uw code of uit te gaan van specifieke informatie over tokens die niet voor een API zijn die u beheert.

Foutrespons

Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de app ze op de juiste wijze kan verwerken:

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
Parameter Description
error Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren.

Toegangstokens op de achtergrond verkrijgen

Belangrijk

Dit deel van de impliciete stroom werkt waarschijnlijk niet voor uw toepassing omdat deze in verschillende browsers wordt gebruikt vanwege het standaard verwijderen van cookies van derden. Hoewel dit momenteel nog steeds werkt in op Chromium gebaseerde browsers die zich niet in Incognitomodus bevinden, moeten ontwikkelaars het gebruik van dit deel van de stroom heroverwegen. In browsers die geen cookies van derden ondersteunen, krijgt u een foutmelding die aangeeft dat er geen gebruikers zijn aangemeld, omdat de sessiecookies van de aanmeldingspagina zijn verwijderd door de browser.

Nu u de gebruiker hebt aangemeld bij uw app met één pagina, kunt u op de achtergrond toegangstokens verkrijgen voor het aanroepen van web-API's die zijn beveiligd door Microsoft Identity Platform, zoals Microsoft Graph. Zelfs als u al een token hebt ontvangen met behulp van de token response_type, kunt u deze methode gebruiken om tokens te verkrijgen naar aanvullende resources zonder de gebruiker om te leiden om zich opnieuw aan te melden.

In de normale OpenID Connect/OAuth-stroom doet u dit door een aanvraag in te dienen bij het Microsoft Identity Platform-eindpunt /token. U kunt de aanvraag indienen in een verborgen iframe om nieuwe tokens voor andere web-API's op te halen:

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

Zie de aanmeldingsaanvraag verzenden voor meer informatie over de queryparameters in de URL.

Tip

Kopieer en plak de onderstaande aanvraag in een browsertabblad. (Vergeet niet om de login_hint-waarden te vervangen door de juiste waarde voor uw gebruiker)

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}

Houd er rekening mee dat dit zelfs werkt in browsers zonder ondersteuning van cookies van derden, omdat u dit rechtstreeks in een browserbalk invoert in plaats van het te openen binnen een iframe.

Dankzij de prompt=none-parameter slaagt deze aanvraag onmiddellijk of mislukt hij en keert hij terug naar uw toepassing. Het antwoord wordt naar uw app verzonden in de aangegeven redirect_uri, met behulp van de methode die is opgegeven in de response_mode-parameter.

Succesvolle respons

Een geslaagd antwoord middels response_mode=fragment ziet er zo uit:

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 Inclusief als response_typetoken bevat. Het toegangstoken dat door de app is aangevraagd, in dit geval voor Microsoft Graph. Het toegangstoken mag niet worden gedecodeerd of anderszins geïnspecteerd. Het moet worden behandeld als een ondoorzichtige tekenreeks.
token_type Dit zal altijd zijn Bearer.
expires_in Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
scope Geeft de bereiken aan waarvoor het toegangstoken geldig is. Mag niet alle aangevraagde bereiken bevatten, als ze niet van toepassing zijn op de gebruiker (in het geval van alleen Microsoft Entra-bereiken die worden aangevraagd wanneer een persoonlijk account wordt gebruikt om zich aan te melden).
id_token Een ondertekend JSON-webtoken (JWT). Inclusief als response_typeid_token bevat. De app kan de segmenten van dit token decoderen om informatie op te vragen over de gebruiker die zich heeft aangemeld. De app kan de waarden in de cache opslaan en weergeven, maar deze mogen niet worden gebruikt voor autorisatie- of beveiligingsgrenzen. Zie de id_token naslaginformatie voor meer informatie over id_tokens.
Opmerking: Alleen opgegeven als het bereik openid is aangevraagd.
state Als een statusparameter is opgenomen in de aanvraag, wordt dezelfde waarde weergegeven in de reactie. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn.

Foutrespons

Foutreacties kunnen ook naar de redirect_uri worden verzonden, zodat de app ze op de juiste wijze kan verwerken. In het geval van prompt=none, is een verwachte fout:

GET https://localhost/myapp/#
error=user_authentication_required
&error_description=the+request+could+not+be+completed+silently
Parameter Description
error Een foutcodereeks die kan worden gebruikt voor het classificeren van typen fouten die optreden en die kan worden gebruikt om op fouten te reageren.
error_description Een specifiek foutbericht waarmee een ontwikkelaar de hoofdoorzaak van een verificatiefout kan identificeren.

Als u deze fout in de iframe-aanvraag ontvangt, moet de gebruiker zich interactief opnieuw aanmelden om een nieuw token op te halen. U kunt dit geval oplossen op de manier die het meest logisch is voor uw toepassing.

Tokens vernieuwen

De impliciete toekenning biedt geen vernieuwingstokens. Zowel id-tokens als toegangstokens verlopen na korte tijd, zodat uw app moet worden voorbereid om deze tokens periodiek te vernieuwen. Als u beide tokentypen wilt vernieuwen, kunt u dezelfde verborgen iframe-aanvraag van hierboven uitvoeren met behulp van de parameter prompt=none om het gedrag van het identiteitsplatform te beheren. Als u een nieuw id-token wilt ontvangen, moet u ervoor zorgen dat u id_token deze gebruikt in de response_type en scope=openid, evenals een nonce parameter.

In browsers die geen cookies van derden ondersteunen, resulteert dit in een fout die aangeeft dat er geen gebruiker is aangemeld.

Een afmeldingsaanvraag verzenden

Met de OpenID Connect end_session_endpoint kan uw app een aanvraag verzenden naar Microsoft Identity Platform om de sessie van een gebruiker te beëindigen en cookies te wissen die zijn ingesteld door Microsoft Identity Platform. Als u een gebruiker volledig wilt afmelden bij een webtoepassing, moet uw app een eigen sessie met de gebruiker beëindigen (meestal door een tokencache te wissen of cookies te verwijderen) en de browser vervolgens omleiden naar:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parameter Type Beschrijving
tenant vereist De {tenant}-waarde in het pad van de aanvraag kan worden gebruikt om te bepalen wie zich kan aanmelden bij de toepassing. De toegestane waarden zijn common, organizations, consumers en tenant-id's. Zie basisprincipes van protocollen voor meer informatie.
post_logout_redirect_uri aanbevolen De URL waarnaar de gebruiker moet worden teruggestuurd nadat de afmelding is voltooid. Deze waarde moet overeenkomen met een van de omleidings-URI's die zijn geregistreerd voor de toepassing. Als deze niet is opgenomen, krijgt de gebruiker een algemeen bericht te zien van Microsoft Identity Platform.

Volgende stappen