Share via

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 vanuit 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 op 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 de ondersteunde Microsoft Authentication Libraries (MSAL) te gebruiken om tokens te verkrijgen en beveiligde web-API's aan te roepen. Raadpleeg de codevoorbeelden van het Microsoft Identity Platform voor een lijst met codevoorbeelden die gebruikmaken van MSAL.

Waarschuwing

Microsoft raadt u aan de impliciete toekenningsstroom niet te gebruiken. In de meeste scenario's zijn veiligere alternatieven beschikbaar en aanbevolen. Bepaalde configuraties van deze stroom vereisen een zeer hoge mate van vertrouwen in de toepassing en dragen risico's die niet aanwezig zijn in andere stromen. U moet deze stroom alleen gebruiken wanneer andere veiligere stromen niet haalbaar zijn. Zie de beveiligingsproblemen met impliciete toekenningsstroom voor meer informatie.

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 met de impliciete aanmeldingsstroom.

Geschikte scenario's voor 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 aanvraagt vanaf het autorisatie-eindpunt. 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.

De voorkeur geven aan de verificatiecodestroom

Met sommige browsers die ondersteuning voor cookies van derden verwijderen, 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.

Beveiligingsproblemen met impliciete toekenningsstroom

De impliciete toekenningsstroom is bedoeld voor traditionele webtoepassingen waar de server controle heeft over het veilig verwerken van POST-gegevens. Er zijn twee belangrijkste manieren om tokens te leveren met de impliciete toekenningsstroom: waar response_mode wordt geretourneerd als een URL-fragment of als queryparameter (met behulp form POST van en GET ). In de impliciete stroom waar response_mode=form_posthet token veilig wordt geleverd via een HTML-formulierPOST naar de omleidings-URI van de client. Deze methode zorgt ervoor dat het token niet wordt weergegeven in het URL-fragment, waardoor op zijn beurt de risico's van tokenlekken worden voorkomen via browsergeschiedenis of verwijzingsheaders.

De beveiligingsproblemen met de impliciete stroom ontstaan wanneer tokens worden geleverd met behulp van response_mode=fragment. Het URL-fragment is het deel van de URL dat na het # symbool wordt geleverd en niet naar de server wordt verzonden wanneer de browser een nieuwe pagina aanvraagt, maar beschikbaar is voor JavaScript dat in de browser wordt uitgevoerd. Dit betekent dat het token wordt blootgesteld aan JavaScript dat wordt uitgevoerd op de pagina, wat een beveiligingsrisico kan zijn als de pagina scripts van derden bevat. Deze beveiligingsproblemen voor tokens in SPA's zijn ook niet van toepassing op de impliciete stroom met form POST.

Wanneer moet u toestaan dat een toegangstoken of id-token wordt uitgegeven wanneer dit wordt aangevraagd met behulp van impliciete toekenning of hybride stroom?

De impliciete toekenning en hybride stroom zijn niet zo veilig als andere OAuth-stromen. Tenzij dit absoluut vereist is, moet u niet toestaan dat een toegangs- of id-token wordt uitgegeven wanneer dit wordt aangevraagd met behulp van impliciete toekenning of hybride stroom in uw app-registratie. Als u (of uw ontwikkelaars) de MSAL in uw toepassing gebruikt om verificatie en autorisatie te implementeren, moet geen van beide velden worden ingeschakeld.

Als u (of uw ontwikkelaars) echter geen MSAL in uw toepassing gebruikt, wordt in de volgende tabel beschreven wanneer toegangstokens of id-token moeten worden ingeschakeld.

Type toepassing dat u bouwt Tokens die u moet inschakelen in app-registratie
Een BEVEILIGD-WACHTWOORDVERIFICATIE (toepassing met één pagina) die niet gebruikmaakt van de autorisatiecodestroom met PKCE Toegangstokens en id-tokens
Een web- of BEVEILIGD-WACHTWOORDVERIFICATIE-toepassing die een web-API aanroept via JavaScript met behulp van impliciete stroom Toegangstokens en id-tokens
Een ASP.NET Core-web-app en andere web-apps die gebruikmaken van hybride verificatie Id-tokens

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 aanvraag ophalen via het 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, organizationsen consumerstenant-id's. Zie de basisprincipes van protocollen voor meer informatie. Kritiek: voor gastscenario's waarbij u een gebruiker van de ene tenant ondertekent 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 zijn opgenomen id_token voor aanmelding bij OpenID Connect. Het kan ook de response_type, token. Als token u hier gebruikt, kan uw app direct vanaf het eindpunt /autoriseren een toegangstoken ontvangen zonder dat u een tweede aanvraag hoeft te indienen bij het eindpunt /authorize. 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 een autorisatiecode bevatten code voor gebruik in de autorisatiecodestroom.token Dit id_token+code antwoord wordt ook wel de hybride stroom genoemd.
redirect_uri aanbevolen De omleidings-URI van uw app, waar verificatiereacties worden verzonden en ontvangen in uw app. Deze moet exact overeenkomen met een van de omleidings-URI's die u hebt geregistreerd in het Microsoft Entra-beheercentrum, behalve dat deze URL-gecodeerd moet zijn.
scope Vereist Een door spaties gescheiden lijst met bereiken. Voor OpenID Connect (id_tokens) moet het bereik openidzijn opgenomen. Dit wordt omgezet in de machtiging Aanmelden in de gebruikersinterface van toestemming. U kunt eventueel ook de email en profile bereiken 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 aanbevolen Hiermee geeft u de methode op die moet worden gebruikt om het resulterende token terug te sturen naar uw app. Standaard ingesteld query voor alleen een toegangstoken, maar fragment als de aanvraag een id_token bevat. Om veiligheidsredenen is het raadzaam om voor de impliciete stroom te gebruiken form_post om ervoor te zorgen dat het token niet wordt weergegeven in het URL-fragment.
state aanbevolen Een waarde die is opgenomen in de aanvraag, wordt ook geretourneerd in het tokenantwoord. Dit kan een tekenreeks zijn van alle gewenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om vervalsingsaanvallen op meerdere sites te voorkomen. De status wordt ook gebruikt om informatie over de status van de gebruiker in de app te coderen 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 is opgenomen in het resulterende id-token. De app kan deze waarde vervolgens verifiëren om het opnieuw afspelen van tokens 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 facultatief Geeft het type gebruikersinteractie aan dat vereist is. De enige geldige waarden op dit moment zijn login, none, select_accounten consent. prompt=login dwingt de gebruiker hun referenties op die aanvraag in te voeren, waarbij eenmalige aanmelding wordt genegeerd. prompt=none is het tegenovergestelde- het zorgt ervoor dat de gebruiker geen interactieve prompt wordt weergegeven. Als de aanvraag niet op de achtergrond kan worden voltooid via eenmalige aanmelding, retourneert het Microsoft Identity Platform een fout. prompt=select_account verzendt de gebruiker naar een accountkiezer waar alle accounts die in de sessie zijn 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 facultatief U kunt deze parameter gebruiken om het veld gebruikersnaam en e-mailadres van de aanmeldingspagina voor de gebruiker vooraf in te vullen als u de gebruikersnaam van tevoren kent. Apps gebruiken deze parameter vaak tijdens opnieuw verificatie, nadat ze de login_hint optionele claim al hebben geëxtraheerd uit een eerdere aanmelding.
domain_hint facultatief 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 wordt doorgestuurd 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 hun referenties in te voeren en de verificatie te voltooien. Het Microsoft Identity Platform zorgt ervoor dat de gebruiker toestemming heeft gegeven voor de machtigingen die zijn aangegeven in de scope queryparameter. Als de gebruiker toestemming heeft gegeven voor geen van deze machtigingen, wordt de gebruiker gevraagd om toestemming te geven voor de vereiste machtigingen. Zie machtigingen, toestemming en apps met meerdere tenants voor meer informatie.

Zodra de gebruiker zich verifieert en toestemming verleent, retourneert het Microsoft Identity Platform een antwoord op uw app op de aangegeven redirect_uri, met behulp van de methode die is opgegeven in de response_mode parameter.

Geslaagde reactie

Een geslaagd antwoord 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 Beschrijving
code Inbegrepen indien response_type opgenomen code. Het is een autorisatiecode die geschikt is voor gebruik in de autorisatiecodestroom.
access_token Inbegrepen indien response_type opgenomen token. Het toegangstoken dat de app heeft aangevraagd. Het toegangstoken mag niet worden gedecodeerd of anderszins geïnspecteerd. Het moet worden behandeld als een ondoorzichtige tekenreeks.
token_type Inbegrepen indien response_type opgenomen token. Dit is altijd een Bearer.
expires_in Inbegrepen indien response_type opgenomen token. Geeft het aantal seconden aan dat het token geldig is voor cachedoeleinden.
scope Inbegrepen indien response_type opgenomen token. Hiermee wordt een of meer bereiken aangegeven waarvoor de access_token waarde 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 afhankelijk zijn van autorisatie- of beveiligingsgrenzen. Zie voor meer informatie over id-tokens de id_token reference.
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd en response_type opgenomen id_tokens.
state Als een statusparameter is opgenomen in de aanvraag, moet dezelfde waarde worden weergegeven in het antwoord. 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 gebruikmaken van een speciale indeling die niet wordt gevalideerd als JWT, en kan ook worden versleuteld voor gebruikers van het Microsoft-account (Consumentenaccount). Hoewel het lezen van tokens een nuttig hulpprogramma voor foutopsporing en leerproces is, neemt u hier geen afhankelijkheden van in uw code of gaat u ervan uit dat er specifieke informatie is over tokens die niet voor een API die u beheert.

Foutreactie

Er kunnen ook foutberichten naar de redirect_uri app worden verzonden, zodat de app deze op de juiste manier kan verwerken:

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

Toegangstokens op de achtergrond verkrijgen

Nu uw gebruiker is aangemeld bij uw app met één pagina, kunt u op de achtergrond toegangstokens krijgen voor het aanroepen van web-API's die zijn beveiligd door het 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.

Belangrijk

Dit deel van de impliciete stroom werkt waarschijnlijk niet voor uw toepassing omdat deze in verschillende browsers wordt gebruikt vanwege het verwijderen van cookies van derden. Hoewel dit momenteel nog steeds werkt in browsers op basis van Chromium die zich niet in Incognito bevinden, moeten ontwikkelaars het gebruik van dit deel van de stroom opnieuw overwegen. 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.

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 in een verborgen iframe indienen 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.

Fooi

Kopieer en plak de volgende aanvraag in een browsertabblad met behulp van een echte client_id en username vanuit uw app-registratie. Hiermee kunt u de stille tokenaanvraag in actie zien.

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}

Houd er rekening mee dat dit zelfs werkt in browsers zonder cookieondersteuning 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 of mislukt deze onmiddellijk en keert deze terug naar uw toepassing. Het antwoord wordt naar uw app verzonden op de aangegeven, met behulp van de methode die is opgegeven redirect_uriin de response_mode parameter.

Geslaagde reactie

Een geslaagd antwoord ziet response_mode=fragment er als volgt 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 Beschrijving
access_token Inbegrepen indien response_type opgenomen token. Het toegangstoken dat de app heeft 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 is altijd een Bearer.
expires_in Geeft het aantal seconden aan dat het token geldig is voor cachedoeleinden.
scope Geeft een of meer bereiken aan waarvoor het toegangstoken geldig is. Mag niet alle aangevraagde bereiken bevatten, als deze niet van toepassing zijn op de gebruiker (als alleen Microsoft Entra-bereiken worden aangevraagd wanneer een persoonlijk account wordt gebruikt om zich aan te melden).
id_token Een ondertekend JSON-webtoken (JWT). Inbegrepen indien response_type opgenomen id_token. 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 afhankelijk zijn van autorisatie- of beveiligingsgrenzen. Zie de id_token naslaginformatie voor meer informatie over id_tokens.
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd.
state Als een statusparameter is opgenomen in de aanvraag, moet dezelfde waarde worden weergegeven in het antwoord. De app moet controleren of de statuswaarden in de aanvraag en het antwoord identiek zijn.

Foutreactie

Er kunnen ook foutberichten naar de redirect_uri app worden verzonden, zodat de app deze op de juiste manier kan verwerken. Als prompt=none, een verwachte fout is:

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

Als u deze fout ontvangt in de iframe-aanvraag, moet de gebruiker zich interactief opnieuw aanmelden om een nieuw token op te halen. U kunt ervoor kiezen om deze case op welke manier dan ook te verwerken 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 elk type token wilt vernieuwen, kunt u dezelfde verborgen iframe-aanvraag uitvoeren die eerder is beschreven, met behulp van de prompt=none parameter om het gedrag van het identiteitsplatform te beheren. Als u een nieuw id-token wilt ontvangen, moet u dit gebruiken id_token in de response_type en scope=openid, en 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 OpenID Connect end_session_endpoint kan uw app een aanvraag verzenden naar het Microsoft Identity Platform om de sessie van een gebruiker te beëindigen en cookies te wissen die zijn ingesteld door het 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, organizationsen consumerstenant-id's. Zie de basisprincipes van protocollen voor meer informatie.
post_logout_redirect_uri aanbevolen De URL waarnaar de gebruiker moet worden geretourneerd nadat het afmelden is voltooid. Deze waarde moet overeenkomen met een van de omleidings-URI's die zijn geregistreerd voor de toepassing. Als deze niet is opgenomen, wordt de gebruiker een algemeen bericht weergegeven door het Microsoft Identity Platform.

Zie ook

  • Bekijk de MSAL JS-voorbeelden om aan de slag te gaan met coderen.
  • Controleer de autorisatiecodestroom als een nieuwer, beter alternatief voor de impliciete toekenning.