Microsoft identity platform en impliciete toekenningsstroom

  • Artikel
  • 13 minuten om te lezen

De Microsoft identity platform ondersteuning voor de OAuth 2.0 Impliciete toekenningsstroom, zoals beschreven in 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 /authorize-aanvraag, samen met een autorisatiecode.

In dit artikel wordt beschreven hoe u direct kunt Program meren in het protocol in uw toepassing om tokens aan te vragen bij Azure AD. Als dat mogelijk is, kunt u het beste de ondersteunde micro soft-verificatie bibliotheken (MSAL) gebruiken in plaats van tokens te verkrijgen en beveiligde web-api'saan te roepen. Bekijk ook de voor beeld- apps die gebruikmaken van MSAL.

Tip

Probeer deze aanvraag uit te uitvoeren in Postman
Probeer deze aanvraag en meer uit te voeren in Postman. Vergeet niet om tokens en ID's te vervangen.

Geef de voorkeur aan de auth-codestroom

Omdat cookies van derden moeten worden verwijderd uit browsers,is de impliciete toekenningsstroom geen geschikte verificatiemethode meer. De functies voor stille eenmalige aanmelding van de impliciete stroom werken niet zonder cookies van derden, waardoor toepassingen worden stukgemaakt wanneer ze een nieuw token proberen op te halen. 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, en dat bestaande apps met één pagina ook naar de autorisatiecodestroom gaan migreren.

Geschikte scenario's voor de impliciete OAuth2-toekenning

De impliciete toekenning is alleen betrouwbaar voor het initiële, interactieve gedeelte van uw aanmeldingsstroom, waarbij het ontbreken van cookies van derden uw toepassing niet kan beïnvloeden. 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. Dit zorgt ervoor dat uw toepassing een code ontvangt die kan worden ingewisseld voor een vernieuwings token, zodat de aanmeldingssessie van uw app na een periode geldig blijft.

Protocoldiagram

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

Diagram met de impliciete aanmeldingsstroom

De aanmeldingsaanvraag verzenden

Als u de gebruiker in eerste instantie wilt aanmelden bij uw app, kunt u een OpenID Verbinding maken-verificatieaanvraag verzenden en een van de id_token Microsoft identity platform.

Belangrijk

Als u een id-token en/of een toegangstoken wilt aanvragen, moet voor de app-registratie op de pagina Azure Portal - App-registraties de bijbehorende impliciete toekenningsstroom zijn ingeschakeld door ID-tokens en toegangstokens te selecteren in de sectie Impliciete toekenning en hybride stromen. Als deze optie niet is ingeschakeld, wordt unsupported_response er een 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=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

Tip

Als u de aanmelding wilt testen met behulp van de impliciete stroom, klikt u op https://login.microsoftonline.com/common/oauth2/v2.0/authorize.. . Nadat u zich hebt aanmelden, moet uw browser worden omgeleid https://localhost/myapp/ naar met een in de id_token adresbalk.

Parameter Type Description
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 , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie. Voor gastscenario's waarbij u een gebruiker van de ene tenant bij een andere tenant ondertekent, moet u de tenant-id verstrekken om deze correct aan te melden bij de resource-tenant.
client_id vereist De toepassings-id (client) die door de Azure Portal - App-registraties is toegewezen aan uw app.
response_type vereist Moet bevatten id_token voor OpenID-Verbinding maken aanmelden. Het kan ook de token response_type. Als u deze optie gebruikt, kan uw app onmiddellijk een toegangs token ontvangen van het eindpunt voor autor toestemming, zonder dat u een tweede aanvraag bij token het autorische eindpunt moet indienen. Als u de response_type gebruikt, moet de parameter een bereik bevatten dat aangeeft voor welke resource het token moet worden uitgeven token scope (bijvoorbeeld user.read op Microsoft Graph). Het kan ook code bevatten in plaats van om een token autorisatiecode op te geven, voor gebruik in de autorisatiecodestroom. Dit id_token+code-antwoord wordt ook wel de hybride stroom genoemd.
redirect_uri Aanbevolen De redirect_uri van uw app, waar verificatiereacties kunnen worden verzonden en ontvangen door uw app. Deze moet exact overeenkomen met een van de redirect_uris u hebt geregistreerd in de portal, behalve dat deze URL-gecodeerd moet zijn.
scope vereist Een door spatie gescheiden lijst met scopes. Voor OpenID Verbinding maken (id_tokens) moet deze het bereik bevatten, dat wordt omgezet in de machtiging openid 'Aanmelden' in de toestemmings-UI. U kunt eventueel ook de bereiken en opnemen email om toegang te krijgen tot aanvullende profile gebruikersgegevens. U kunt ook andere bereiken opnemen in deze aanvraag voor het aanvragen van toestemming voor verschillende resources, als een toegangs token 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. De standaardinstelling is om alleen een query uit te voeren voor een toegangs token, maar fragment als de aanvraag een id_token.
state Aanbevolen Een waarde die is opgenomen in de aanvraag die ook wordt geretourneerd in het token-antwoord. Dit kan een tekenreeks zijn van elke wenste inhoud. Een willekeurig gegenereerde unieke waarde wordt doorgaans gebruikt om aanvallen met aanvraagvervalsing op andere plaatsen te voorkomen. De status wordt ook gebruikt voor het coderen van informatie over de status van de gebruiker in de app voordat de verificatieaanvraag plaatsvond, zoals de pagina of weergave waarin deze zich voordeed.
nonce vereist Een waarde die is opgenomen in de aanvraag, gegenereerd door de app, die wordt opgenomen in de resulterende id_token als een claim. De app kan deze waarde vervolgens controleren om aanvallen met token opnieuw afspelen te beperken. De waarde is doorgaans een willekeurige, 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 of haar referenties voor die aanvraag in te voeren, wat een een aanmelding onderhandelt. prompt=none is het tegenovergestelde: het zorgt ervoor dat de gebruiker helemaal geen interactieve prompt krijgt te zien. Als de aanvraag niet op de stilzwijgend kan worden voltooid via een aanmelding, wordt Microsoft identity platform foutmelding weergegeven. prompt=select_account verzendt de gebruiker naar een account kiezen waar alle accounts die in de sessie worden onthouden, worden weergegeven. prompt=consent activeert het OAuth-toestemmingsdialoogvenster nadat de gebruiker zich heeft meldt en de gebruiker vraagt om machtigingen te verlenen aan de app.
login_hint optioneel U kunt deze parameter gebruiken om vooraf de gebruikersnaam en het e-mailadresveld van de aanmeldingspagina voor de gebruiker in te vullen, als u de gebruikersnaam van tevoren kent. Vaak gebruiken apps deze parameter tijdens het opnieuw autorisatie, nadat de optionele claim al is geëxtraheert uit een login_hint eerdere aanmelding.
domain_hint optioneel Als dit wordt opgenomen, wordt het detectieproces op basis van e-mail overgeslagen dat de gebruiker op de aanmeldingspagina doormaakt, wat leidt tot een iets gestroomlijnder 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. Houd er rekening mee dat 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 of haar referenties in te voeren en de verificatie te voltooien. De Microsoft identity platform zorgt er ook voor 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 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 de Microsoft identity platform een reactie op uw app op de aangegeven , met behulp van de methode die is opgegeven redirect_uri in de response_mode parameter .

Geslaagd antwoord

Een geslaagd antwoord met response_mode=fragment behulp van en ziet er als volgt uit response_type=id_token+code (met regelbreaks voor leesbaarheid):

GET https://localhost/myapp/#
code=0.AgAAktYV-sfpYESnQynylW_UKZmH-C9y_G1A
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
&state=12345
Parameter Beschrijving
code Opgenomen als response_type code bevat. Dit is een autorisatiecode die geschikt is voor gebruik in de autorisatiecodestroom.
access_token Opgenomen als response_type token bevat. Het toegangs token dat de app heeft aangevraagd. Het toegangsken mag niet worden gedecodeerd of anderszins geïnspecteerd. Het moet worden behandeld als een ondoorzichtige tekenreeks.
token_type Opgenomen als response_type token bevat. Zal altijd Bearer zijn.
expires_in Opgenomen als response_type token bevat. Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
scope Opgenomen als response_type token bevat. Geeft de scope(s) aan waarvoor de access_token geldig is. Mag niet alle aangevraagde scopes bevatten als ze niet van toepassing zijn op de gebruiker (in het geval dat alleen Azure AD-scopes worden aangevraagd wanneer een persoonlijk account wordt gebruikt om zich aan te melden).
id_token Een ondertekend JSON Web Token (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 cachen en weergeven, maar deze mogen niet afhankelijk zijn van deze waarden voor autorisatie of beveiligingsgrenzen. Zie de voor id_tokens informatie over de id_token reference gegevens.
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd en is response_type id_tokens opgenomen.
state Als er 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 die u niet bezit, 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 die ook kan worden versleuteld voor gebruikers (Microsoft-account). Hoewel het lezen van tokens een nuttig hulpprogramma is voor debuggen en leren, moet u hier geen afhankelijkheden van nemen in uw code en geen specifieke informatie aannemen over tokens die niet voor een API zijn die u controleert.

Foutbericht

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

GET https://localhost/myapp/#
error=access_denied
&error_description=the+user+canceled+the+authentication
Parameter Beschrijving
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 dat een ontwikkelaar kan helpen bij het identificeren van de hoofdoorzaak van een verificatiefout.

Toegangstokens op de achtergrond 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 Chromium browsers die zich niet in Incognito, moeten ontwikkelaars overwegen dit deel van de stroom te gebruiken. In browsers die geen cookies van derden ondersteunen, ontvangt u een foutmelding dat er geen gebruikers zijn aangemeld, omdat de sessiecookies van de aanmeldingspagina door de browser zijn verwijderd.

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

In de normale OpenID Verbinding maken/OAuth-stroom doet u dit door een aanvraag te maken bij Microsoft identity platform /token eindpunt. 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=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

Zie De aanmeldingsaanvraag verzenden voor meer informatie over de queryparameters in deURL.

Tip

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

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}

Houd er rekening mee dat dit zelfs werkt in browsers zonder cookieondersteuning van derden, omdat u dit rechtstreeks in een browserbalk inwerkt in plaats van deze te openen binnen een iframe.

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

Geslaagd antwoord

Een geslaagd antwoord met behulp van response_mode=fragment ziet er als volgende 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 Opgenomen als response_type token bevat. Het toegangs token dat de app heeft aangevraagd, in dit geval voor de Microsoft-Graph. Het toegangsken mag niet worden gedecodeerd of anderszins geïnspecteerd. Het moet worden behandeld als een ondoorzichtige tekenreeks.
token_type Zal altijd Bearer zijn.
expires_in Geeft het aantal seconden aan dat het token geldig is voor cachingdoeleinden.
scope Geeft de scope(s) aan waarvoor de access_token geldig is. Mag niet alle aangevraagde scopes bevatten als ze niet van toepassing zijn op de gebruiker (in het geval dat alleen Azure AD-scopes worden aangevraagd wanneer een persoonlijk account wordt gebruikt om zich aan te melden).
id_token Een ondertekend JSON Web Token (JWT). Opgenomen 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 cachen en weergeven, maar deze mogen niet afhankelijk zijn van deze waarden voor autorisatie of beveiligingsgrenzen. Zie de naslaginformatie id_tokens meer informatie over id_token de gegevens.
Opmerking: Alleen opgegeven als openid het bereik is aangevraagd.
state Als er 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.

Foutbericht

Foutreacties kunnen ook naar de worden redirect_uri verzonden, zodat de app deze 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 Beschrijving
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 dat een ontwikkelaar kan helpen bij het identificeren van de hoofdoorzaak van een verificatiefout.

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 ervoor kiezen om deze aanvraag op elke zinnige manier af te handelen voor uw toepassing.

Tokens vernieuwen

De impliciete toekenning biedt geen vernieuwingstokens. Zowel s als s verlopen na een korte periode, dus uw app moet worden voorbereid om deze id_token access_token tokens periodiek te vernieuwen. Als u een van beide typen token wilt vernieuwen, kunt u dezelfde verborgen iframe-aanvraag hierboven uitvoeren met behulp van de parameter om het gedrag van het prompt=none identiteitsplatform te bepalen. Als u een nieuwe wilt id_token ontvangen, moet u gebruiken id_token in de en , response_type 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 aanvraag voor een uitloggen verzenden

Met de OpenID Verbinding maken kan uw app een aanvraag verzenden naar de Microsoft identity platform om de sessie van een gebruiker te beëindigen en cookies te verwijderen die zijn ingesteld door end_session_endpoint de Microsoft identity platform . Als u een gebruiker volledig wilt aftekenen 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 vervolgens de browser omleiden naar:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/logout?post_logout_redirect_uri=https://localhost/myapp/
Parameter Type Description
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 , , en consumers tenant-id's. Zie basisbeginselen van protocollen voor meer informatie.
post_logout_redirect_uri Aanbevolen De URL waar de gebruiker naar moet worden geretourneerd nadat de aanmelding 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 de Microsoft identity platform.

Volgende stappen