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.

Tipp

Diese Anforderung in Postman ausführen
Führen Sie diese Anforderung und weitere Funktionen in Postman aus. Vergessen Sie nicht, Token und IDs zu ersetzen.

Protokolldiagramm

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

Gerätecodefluss

Geräteautorisierungsanforderung

Der Client muss zuerst den 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20openid%20profile

Parameter Bedingung 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 im Azure-Portal auf der Seite „App-Registrierungen“ zugewiesen wurde.
scope Erforderlich Eine durch Leerzeichen getrennte Liste mit Bereichen , denen der Benutzer zustimmen soll.

Geräteautorisierungsantwort

Eine erfolgreiche Antwort wird ein JSON-Objekt sein, das die erforderlichen Informationen enthält, um dem Benutzer die Anmeldung zu 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, für den 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

Nach dem Empfang von user_code und verification_uri zeigt der Client diese für den Benutzer an und weist ihn an, sich mit seinem Mobiltelefon oder 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=6731de76-14a6-49ae-97bc-6eba6914391e&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 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 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.