Microsoft Identity Platform und der OAuth 2.0-Flow für die Geräteautorisierungsgenehmigung

Microsoft Identity Platform unterstützt die Geräteautorisierungsgewährung, die Benutzern die Anmeldung bei Geräten mit Eingabeeinschränkung wie einem Smart-TV, IoT-Gerät oder Drucker ermöglicht. Damit dieser Flow genutzt werden kann, veranlasst das Gerät den Benutzer, in einem Browser auf einem anderen Gerät eine Webseite zu besuchen, um sich anzumelden. Sobald sich der Benutzer anmeldet, kann das Gerät nach Bedarf Zugriffstoken und Aktualisierungstoken abrufen.

In diesem Artikel wird beschrieben, wie Sie direkt mit dem Protokoll in Ihrer Anwendung programmieren. Es wird stattdessen empfohlen, ggf. die unterstützten Microsoft Authentication Libraries (MSAL) zu verwenden, um Token zu erhalten und gesicherte Web-APIs aufzurufen. Beispiele finden Sie unter Beispiel-Apps, die MSAL verwenden.

Protokolldiagramm

Der gesamte Gerätecodeflow ist im folgenden Diagramm dargestellt. Die einzelnen Schritte werden in diesem Artikel erläutert.

Geräteautorisierungsanforderung

Der Client muss zuerst beim Authentifizierungsserver auf einen Geräte- und Benutzercode überprüfen, die zum Initiieren der Authentifizierung verwendet werden. Der Client sammelt diese Anforderung vom /devicecode-Endpunkt. In der Anforderung sollte der Client auch die Berechtigungen angeben, die er vom Benutzer erhalten muss.

Ab dem Zeitpunkt, an dem die Anforderung gesendet wird, hat der Benutzer 15 Minuten Zeit, sich anzumelden. Dies ist der Standardwert für expires_in. Die Anforderung sollte erst erfolgen, wenn der Benutzer angezeigt hat, dass er bereit ist, sich anzumelden.

// 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	Condition	Beschreibung
tenant	Erforderlich	Kann /common, /consumers oder /organizations sein. Dies kann auch der Verzeichnismandant sein, von dem Sie die Berechtigung im GUID- oder Anzeigenamensformat anfordern möchten.
client_id	Erforderlich	Die Anwendungs-ID (Client-ID), die Ihrer App auf der Benutzeroberfläche „App-Registrierungen“ im Microsoft Entra Admin Center zugewiesen ist.
scope	Erforderlich	Eine durch Leerzeichen getrennte Liste mit Bereichen , denen der Benutzer zustimmen soll.

Geräteautorisierungsantwort

Eine erfolgreiche Antwort ist ein JSON-Objekt mit den erforderlichen Informationen, die den Benutzer*innen die Anmeldung ermöglichen.

Parameter	Format	BESCHREIBUNG
device_code	String	Eine lange Zeichenfolge, die zum Verifizieren der Sitzung zwischen dem Client und dem Autorisierungsserver verwendet wird. Der Client fordert über diesen Parameter das Zugriffstoken vom Autorisierungsserver an.
user_code	String	Eine kurze, dem Benutzer angezeigte Zeichenfolge, mit der die Sitzung auf einem sekundären Gerät identifiziert wird.
verification_uri	URI	Der URI, den der Benutzer mit dem user_code besuchen sollte, um sich anzumelden.
expires_in	INT	Die Anzahl der Sekunden, bevor device_code und user_code ablaufen.
interval	INT	Die Anzahl der Sekunden, die der Client zwischen Abrufanforderungen warten soll.
message	String	Eine lesbare Zeichenfolge mit Anweisungen für den Benutzer. Diese kann lokalisiert werden, indem ein Abfrageparameter in die Anforderung des Formulars ?mkt=xx-XX aufgenommen und der entsprechende Sprachkulturcode eingetragen wird.

Hinweis

Das Antwortfeld verification_uri_complete ist derzeit nicht vorhanden bzw. wird nicht unterstützt. Dies ist wichtig zu wissen, da im Standardverification_uri_complete als optionaler Teil des Gerätecodeflow-Standards aufgeführt wird.

Authentifizieren des Benutzers

Wenn der Client die Werte user_code und verification_uri empfangen hat, werden die Werte angezeigt, und der Benutzer wird aufgefordert, sich über sein Mobilgerät oder einen PC-Browser anzumelden.

Wenn sich der Benutzer mit einem persönlichen Konto (mit /common oder /consumers) authentifiziert, wird er aufgefordert, sich erneut anzumelden, um den Authentifizierungsstatus an das Gerät zu übertragen. Der Grund dafür ist, dass das Gerät nicht auf die Cookies des Benutzers zugreifen kann. Der Benutzer wird auch aufgefordert, den vom Client angeforderten Berechtigungen zuzustimmen. Dies gilt jedoch nicht für Geschäfts-, Schul- oder Unikonten, die für die Authentifizierung verwendet werden.

Während sich der Benutzer bei dem verification_uri authentifiziert, sollte der Client beim /token-Endpunkt das angeforderte Token mithilfe des device_code abrufen.

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	Erforderlich	BESCHREIBUNG
tenant	Erforderlich	Derselbe Mandant oder Mandantenalias, der in der ursprünglichen Anforderung verwendet wurde.
grant_type	Erforderlich	Muss gleich urn:ietf:params:oauth:grant-type:device_code sein.
client_id	Erforderlich	Muss mit der in der anfänglichen Anforderung verwendeten client_id übereinstimmen.
device_code	Erforderlich	Der in der Geräteautorisierungsanforderung zurückgegebene device_code.

Erwartete Fehler

Der Gerätecodeflow ist ein Abrufprotokoll, sodass vor Abschluss der Benutzerauthentifizierung mit Fehlern gerechnet werden muss, die dem Client übermittelt werden.

Fehler	BESCHREIBUNG	Clientaktion
authorization_pending	Der Benutzer hat die Authentifizierung nicht abgeschlossen, den Flow aber nicht abgebrochen.	Wiederholen Sie die Anforderung nach mindestens interval Sekunden.
authorization_declined	Der Endbenutzer hat die Autorisierungsanforderung verweigert.	Beenden des Abrufens und Wiederherstellen eines nicht authentifizierten Zustands.
bad_verification_code	Der an den /token-Endpunkt gesendete device_code wurde nicht erkannt.	Stellen Sie sicher, dass der Client den richtigen device_code in der Anforderung sendet.
expired_token	Der Wert von expires_in wurde überschritten, und die Authentifizierung ist mit device_code nicht mehr möglich.	Beenden des Abrufens und Wiederherstellen eines nicht authentifizierten Zustands.

Erfolgreiche Authentifizierungsantwort

Eine erfolgreiche Token-Antwort sieht wie folgt aus:

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

Parameter	Format	BESCHREIBUNG
token_type	String	Immer Bearer.
scope	Durch Leerzeichen getrennte Zeichenfolgen	Wenn ein Zugriffstoken zurückgegeben wurde, werden hiermit die Bereiche aufgeführt, für die das Zugriffstoken gültig ist.
expires_in	INT	Die Anzahl von Sekunden, die das enthaltene Zugriffstoken gültig ist.
access_token	Nicht transparente Zeichenfolge	Ausgestellt für die Bereiche, die angefordert wurden.
id_token	JWT	Ausgestellt, wenn der ursprüngliche scope-Parameter den openid-Bereich enthalten hat.
refresh_token	Nicht transparente Zeichenfolge	Ausgestellt, wenn der ursprüngliche scope-Parameter offline_access enthalten hat.

Sie können mit dem Aktualisierungstoken neue Zugriffstoken und Aktualisierungstoken abrufen. Verwenden Sie dazu den in der Dokumentation für den OAuth-Codeflow beschriebenen Flow.

Warnung

Versuchen Sie nicht, Token für eine API zu überprüfen oder zu lesen, die Sie nicht besitzen, einschließlich der Token in Ihrem Code in diesem Beispiel. Token für Microsoft-Dienste können ein spezielles Format verwenden, das nicht als JWT überprüft und auch für Consumerbenutzer (Microsoft-Konto) verschlüsselt werden kann. Das Lesen von Token ist zwar ein nützliches Debug- und Lerntool, aber integrieren Sie weder Abhängigkeiten davon in Ihren Code noch setzen Sie Einzelheiten über Token voraus, die nicht für eine von Ihnen kontrollierte API gelten.