Microsoft Identity Platform en de toekenningsstroom OAuth 2.0-apparaatautorisatie

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 aanmeldt, kan het apparaat zo nodig toegangstokens ophalen en tokens vernieuwen.

In dit artikel wordt beschreven hoe u rechtstreeks kunt programmeren 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.

Protocoldiagram

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

Apparaatautorisatieaanvraag

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

Parameter	Voorwaarde	Beschrijving
tenant	Vereist	De waarde kan /common, /consumersof /organizations zijn. Het kan ook de directorytenant zijn waarvoor u toestemming wilt aanvragen in GUID of beschrijvende naamindeling.
client_id	Vereist	De toepassings-id (client) die door het Microsoft Entra-beheercentrum wordt App-registraties ervaring toegewezen aan uw app.
scope	Vereist	Een door spaties gescheiden lijst met bereiken waaraan u de gebruiker toestemming wilt geven.

Apparaatautorisatiereactie

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

Parameter	Notatie	Beschrijving
device_code	String	Een lange tekenreeks die wordt gebruikt om de sessie tussen de client en de autorisatieserver te controleren. De client gebruikt deze parameter om het toegangstoken aan te vragen van de autorisatieserver.
user_code	String	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 met de user_code om zich aan te melden.
expires_in	int	Het aantal seconden voordat de device_code en user_code verlopen.
interval	int	Het aantal seconden dat de client moet wachten tussen polling-aanvragen.
message	String	Een door mensen leesbare tekenreeks met instructies voor de gebruiker. Dit kan worden gelokaliseerd door een queryparameter op te nemen 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, u ziet dat verification_uri_complete wordt vermeld als een optioneel onderdeel van de standaard van 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 verifieert bij de verification_uri, moet de client enquêtes uitvoeren voor het /token-eindpunt voor het aangevraagde token 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...

Parameter	Vereist	Beschrijving
tenant	Vereist	Dezelfde tenant of tenantalias die in de eerste aanvraag is gebruikt.
grant_type	Vereist	Moet urn:ietf:params:oauth:grant-type:device_code zijn
client_id	Vereist	Moet overeenkomen met de client_id die wordt gebruikt in de eerste aanvraag.
device_code	Vereist	De geretourneerde device_code 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	Clientactie
authorization_pending	De gebruiker is niet klaar met verifiëren, maar heeft de stroom niet geannuleerd.	Herhaal de aanvraag na ten minste interval seconden.
authorization_declined	De eindgebruiker heeft de autorisatieaanvraag geweigerd.	Stop met polling en keer 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 met polling en keer terug naar een niet-geverifieerde status.

Geslaagd verificatie-antwoord

Een geslaagd 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..."
}

Parameter	Notatie	Beschrijving
token_type	String	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	int	Het inbegrepen toegangstoken is geldig voor het aantal seconden.
access_token	Ondoorzichtige tekenreeks	Uitgegeven voor de bereiken die zijn aangevraagd.
id_token	JWT	Uitgegeven als de oorspronkelijke scope-parameter het openid-bereik bevatte.
refresh_token	Ondoorzichtige tekenreeks	Uitgegeven als de oorspronkelijke scope-parameter offline_access bevatte.

U kunt het vernieuwingstoken gebruiken om nieuwe toegangstokens te verkrijgen en tokens te vernieuwen met 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 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.