Delen 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 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. 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 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 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 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 resource-tenant.
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 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 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 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 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 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. 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 is 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 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 optioneel 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 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 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 om zijn 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.

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_type code bevat. Het is een autorisatiecode die geschikt is voor gebruik in de autorisatiecodestroom.
access_token Inclusief als response_type token 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_type token bevat. Dit is altijd een Bearer.
expires_in Inclusief als response_type token bevat. Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
scope Inclusief als response_type token bevat. 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 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_type id_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

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

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

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_type token 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 is altijd een Bearer.
expires_in Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
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). Inclusief als response_type id_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. 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 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 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 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 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