Microsoft Identity Platform en de toekenningsstroom OAuth 2.0-apparaatautorisatie
Artikel
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.
HTTP
// 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.
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.
HTTP
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.
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.
Learn about OIDC authentication and OAuth 2.0 in the Microsoft identity platform. Understand authentication flows and OIDC endpoints for secure user authentication.