Share via


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.

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