Microsoft Identity Platform en de toekenningsstroom OAuth 2.0-apparaatautorisatie

Artikel
04/08/2024

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.

Device code flow

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`, `/consumers`of `/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.

Delen via