Microsoft Identity Platform en de OAuth 2.0-apparaatautorisatiestroom

Het Microsoft Identity Platform ondersteunt de toekenning van apparaatautorisatie, waarmee gebruikers zich kunnen aanmelden bij apparaten met beperkte invoer, zoals een smart TV, IoT-apparaat of een printer. Als u deze stroom wilt inschakelen, heeft het apparaat de gebruiker een webpagina in een browser op een ander apparaat om zich aan te melden. Zodra de gebruiker zich heeft aangemeld, kan het apparaat toegangstokens ophalen en tokens vernieuwen als dat nodig is.

In dit artikel wordt beschreven hoe u rechtstreeks programma's kunt uitvoeren op basis van het protocol in uw toepassing. 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. U kunt verwijzen naar voorbeeld-apps die MSAL gebruiken voor voorbeelden.

Protocolschema

De volledige apparaatcodestroom wordt weergegeven in het volgende diagram. Elke stap wordt in dit artikel uitgelegd.

Aanvraag voor apparaatautorisatie

De client moet eerst controleren op de verificatieserver voor een apparaat en gebruikerscode die wordt gebruikt om verificatie te initiëren. De client verzamelt deze aanvraag vanaf het /devicecode-eindpunt. In de aanvraag moet de client ook de machtigingen opnemen die nodig zijn om van de gebruiker te verkrijgen.

Vanaf het moment dat de aanvraag wordt verzonden, heeft de gebruiker 15 minuten om zich aan te melden. Dit is de standaardwaarde voor expires_in. De aanvraag mag alleen worden ingediend wanneer de gebruiker aangeeft dat hij of zij klaar is om zich aan te melden.

// Line breaks are for legibility only.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile

Maatstaf	Conditie	Beschrijving
tenant	Verplicht	De waarde kan /common, /consumersof /organizations zijn. Het kan ook de maptenant zijn waarvoor u toestemming wilt aanvragen in GUID of beschrijvende naamindeling.
client_id	Verplicht	De toepassings-id (client) die door de Microsoft Entra beheerderscentrum – App-registraties interface aan uw app is toegewezen.
scope	Verplicht	Een door spaties gescheiden lijst met bereiken waaraan u de gebruiker toestemming wilt geven.

Antwoord voor apparaatautorisatie

Een geslaagd antwoord is een JSON-object met de vereiste informatie waarmee de gebruiker zich kan aanmelden.

Maatstaf	Formaat	Beschrijving
device_code	Touwtje	Een lange tekenreeks die wordt gebruikt om de sessie tussen de client en de autorisatieserver te verifiëren. De client gebruikt deze parameter om het toegangstoken aan te vragen van de autorisatieserver.
user_code	Touwtje	Een korte tekenreeks die wordt weergegeven aan de gebruiker die is gebruikt om de sessie op een secundair apparaat te identificeren.
verification_uri	URI	De URI waar de gebruiker naartoe moet gaan om user_code u aan te melden.
expires_in	Integer	Het aantal seconden vóór de device_code en user_code verlopen.
interval	Integer	Het aantal seconden dat de client moet wachten tussen polling-aanvragen.
message	Touwtje	Een door mensen leesbare tekenreeks met instructies voor de gebruiker. Dit kan worden gelokaliseerd door een queryparameter op te vragen in de aanvraag van het formulier ?mkt=xx-XX, waarbij de juiste taalcultuurcode wordt ingevuld.

Notitie

Het verification_uri_complete antwoordveld wordt momenteel niet opgenomen of ondersteund. We noemen dit omdat als u de standaard leest die verification_uri_complete wordt vermeld als een optioneel onderdeel van de standaard voor de apparaatcodestroom.

De gebruiker verifiëren

Nadat de client de waarden heeft ontvangen user_code en verification_uri, worden de waarden weergegeven en wordt de gebruiker omgeleid om zich aan te melden via hun mobiele of pc-browser.

Als de gebruiker zich verifieert met een persoonlijk account, wordt /common hij of /consumerszij gevraagd zich opnieuw aan te melden om de verificatiestatus over te dragen naar het apparaat. Dit komt doordat het apparaat geen toegang heeft tot de cookies van de gebruiker. Ze worden gevraagd om toestemming te geven voor de machtigingen die door de client zijn aangevraagd. Dit geldt echter niet voor werk- of schoolaccounts die worden gebruikt voor verificatie.

Terwijl de gebruiker zich bij de verification_uriverificatie bevindt, moet de client het /token eindpunt voor het aangevraagde token pollen met behulp van de device_code.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Maatstaf	Verplicht	Beschrijving
tenant	Verplicht	Dezelfde tenant- of tenantalias die in de eerste aanvraag wordt gebruikt.
grant_type	Verplicht	Moet urn:ietf:params:oauth:grant-type:device_code zijn
client_id	Verplicht	Moet overeenkomen met de client_id gebruikte waarde in de eerste aanvraag.
device_code	Verplicht	De device_code geretourneerde in de autorisatieaanvraag van het apparaat.

Verwachte fouten

De apparaatcodestroom is een polling-protocol, dus fouten die aan de client worden geleverd, moeten worden verwacht voordat de gebruikersverificatie is voltooid.

Fout	Beschrijving	Klantactie
authorization_pending	De gebruiker heeft de verificatie niet voltooid, maar heeft de stroom niet geannuleerd.	Herhaal de aanvraag na ten minste enkele interval seconden.
authorization_declined	De eindgebruiker heeft de autorisatieaanvraag geweigerd.	Stop polling en ga terug naar een niet-geverifieerde status.
bad_verification_code	Het device_code verzonden naar het /token eindpunt is niet herkend.	Controleer of de client het juiste device_code verzendt in de aanvraag.
expired_token	De waarde is expires_in overschreden en de verificatie is niet meer mogelijk bij device_code.	Stop polling en ga terug naar een niet-geverifieerde status.

Geslaagde verificatiereactie

Een succesvol tokenantwoord ziet er als volgt uit:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Maatstaf	Formaat	Beschrijving
token_type	Touwtje	Altijd Bearer.
scope	Door spaties gescheiden tekenreeksen	Als er een toegangstoken is geretourneerd, worden hiermee de bereiken vermeld waarvoor het toegangstoken geldig is.
expires_in	Integer	Het inbegrepen toegangstoken is geldig voor het aantal seconden.
access_token	Ondoorzichtige tekenreeks	Verleend voor de scope die zijn aangevraagd.
id_token	JWT	Uitgegeven als de oorspronkelijke scope parameter het openid bereik bevat.
refresh_token	Ondoorzichtige tekenreeks	Uitgegeven als de oorspronkelijke scope parameter offline_accessbevat.

U kunt het vernieuwingstoken gebruiken om nieuwe toegangstokens te verkrijgen en tokens te vernieuwen met behulp van dezelfde stroom die wordt beschreven in de OAuth Code-stroomdocumentatie.

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 als JWT wordt gevalideerd en die ook kan 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.