Microsoft Identity Platform und der Autorisierungsfluss für OAuth 2.0-Geräte

Die Microsoft Identity Platform unterstützt die Geräteautorisierungserteilung, die es Benutzern ermöglicht, sich bei eingabeeinschränkten Geräten wie einem Smart TV, IoT-Gerät oder einem Drucker anzumelden. Um diesen Fluss zu aktivieren, hat das Gerät, dass der Benutzer eine Webseite in einem Browser auf einem anderen Gerät besucht, 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. Sie können auf Beispiel-Apps verweisen, die MSAL für Beispiele verwenden.

Protokolldiagramm

Der gesamte Gerätecodefluss wird im folgenden Diagramm dargestellt. Jeder Schritt wird in diesem Artikel erläutert.

Geräteautorisierungsanforderung

Der Client muss zuerst den Authentifizierungsserver für ein Gerät und benutzercode überprüfen, der zum Initiieren der Authentifizierung verwendet wird. Der Client sammelt diese Anforderung vom /devicecode Endpunkt. In der Anforderung sollte der Client auch die Berechtigungen enthalten, die er vom Benutzer erwerben 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 nur erfolgen, wenn der Benutzer angibt, 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	Zustand	BESCHREIBUNG
tenant	Erforderlich	Kann /common, /consumers oder /organizations sein. Es kann auch der Verzeichnismandant sein, den Sie im GUID- oder Anzeigenamenformat 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, das die erforderlichen Informationen enthält, damit sich der Benutzer anmelden kann.

Parameter	Format	BESCHREIBUNG
device_code	Schnur	Eine lange Zeichenfolge, die verwendet wird, um die Sitzung zwischen dem Client und dem Autorisierungsserver zu überprüfen. Der Client verwendet diesen Parameter, um das Zugriffstoken vom Autorisierungsserver anzufordern.
user_code	Schnur	Eine kurze Zeichenfolge, die dem Benutzer angezeigt wird, um die Sitzung auf einem sekundären Gerät zu identifizieren.
verification_uri	URI (Uniform Resource Identifier)	Der URI, zu dem user_code der Benutzer wechseln soll, 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	Schnur	Eine lesbare Zeichenfolge mit Anweisungen für den Benutzer. Dies kann lokalisiert werden, indem ein Abfrageparameter in die Anforderung des Formulars ?mkt=xx-XXeingeschlossen wird und der entsprechende Sprachkulturcode ausgefüllt wird.

Hinweis

Das verification_uri_complete Antwortfeld wird zurzeit nicht eingeschlossen oder unterstützt. Dies wird erwähnt, da beim Lesen des Standards dies verification_uri_complete als optionaler Teil des Gerätecodeflussstandards aufgeführt ist.

Authentifizieren des Benutzers

Nachdem der Client die Werte empfängt user_code und verification_uri, werden die Werte angezeigt, und der Benutzer wird aufgefordert, sich über seinen mobilen oder PC-Browser anzumelden.

Wenn sich der Benutzer mit einem persönlichen Konto authentifiziert, unter Verwendung /common oder /consumers, wird er aufgefordert, sich erneut anzumelden, um den Authentifizierungsstatus auf das Gerät zu übertragen. Dies liegt daran, dass das Gerät nicht auf die Cookies des Benutzers zugreifen kann. Sie werden 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 der Benutzer authentifiziert verification_uriwird, sollte der Client den /token Endpunkt für das angeforderte Token mit dem 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	Erforderlich	BESCHREIBUNG
tenant	Erforderlich	Derselbe Mandanten- oder Mandantenalias, der in der anfänglichen Anforderung verwendet wird.
grant_type	Erforderlich	Muss gleich urn:ietf:params:oauth:grant-type:device_code sein.
client_id	Erforderlich	Muss mit der client_id in der ursprünglichen Anforderung verwendeten übereinstimmen.
device_code	Erforderlich	Die device_code in der Geräteautorisierungsanforderung zurückgegebene.

Erwartete Fehler

Der Gerätecodefluss ist ein Abrufprotokoll, sodass Fehler, die dem Client bereitgestellt werden, vor Abschluss der Benutzerauthentifizierung erwartet werden müssen.

Fehler	BESCHREIBUNG	Kundenaktion
authorization_pending	Der Benutzer hat die Authentifizierung nicht abgeschlossen, aber den Ablauf nicht abgebrochen.	Wiederholen Sie die Anforderung nach mindestens interval Sekunden.
authorization_declined	Der Endbenutzer hat die Autorisierungsanforderung verweigert.	Beenden Sie das Abrufen und Wiederherstellen eines nicht authentifizierten Zustands.
bad_verification_code	Der device_code an den /token Endpunkt gesendete Wurde nicht erkannt.	Stellen Sie sicher, dass der Client die richtige device_code In der Anforderung sendet.
expired_token	Der Wert wurde expires_in überschritten, und die Authentifizierung ist nicht mehr möglich.device_code	Beenden Sie das Abrufen und Wiederherstellen eines nicht authentifizierten Zustands.

Erfolgreiche Authentifizierungsantwort

Eine erfolgreiche Tokenantwort 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	Schnur	Immer Bearer.
scope	Durch Leerzeichen getrennte Zeichenfolgen	Wenn ein Zugriffstoken zurückgegeben wurde, werden die Bereiche aufgelistet, für die das Zugriffstoken gültig ist.
expires_in	Int	Die Anzahl der Sekunden, für die das enthaltene Zugriffstoken gültig ist.
access_token	Nicht transparente Zeichenfolge	Ausgestellt für die Bereiche, die angefordert wurden.
id_token	JWT	Wird ausgegeben, wenn der ursprüngliche scope Parameter den openid Bereich enthält.
refresh_token	Nicht transparente Zeichenfolge	Wird ausgegeben, wenn der ursprüngliche Parameter scopeoffline_accessenthält.

Sie können das Aktualisierungstoken verwenden, um neue Zugriffstoken und Aktualisierungstoken mithilfe desselben Flusses abzurufen, der in der OAuth-Codeflussdokumentation dokumentiert ist.

Warnung

Versuchen Sie nicht, Token für eine API zu überprüfen oder zu lesen, die Sie nicht besitzen, einschließlich der Token in diesem Beispiel, in Ihrem Code. Token für Microsoft-Dienste können ein spezielles Format verwenden, das nicht als JWT überprüft wird, und kann auch für Verbraucherbenutzer (Microsoft-Konto) verschlüsselt werden. Während das Lesen von Token ein nützliches Debugging- und Lerntool ist, nehmen Sie keine Abhängigkeiten davon in Ihrem Code ab, oder gehen Sie von Besonderheiten zu Token aus, die nicht für eine von Ihnen gesteuerte API gelten.