Platforma tożsamości Microsoft i przepływ udzielania autoryzacji urządzenia OAuth 2.0

Platforma tożsamości Microsoft obsługuje przyznawanie autoryzacji urządzenia, co umożliwia użytkownikom logowanie się do urządzeń z ograniczonymi danymi wejściowymi, takich jak smart TV, urządzenie IoT lub drukarka. Aby włączyć ten przepływ, urządzenie odwiedza stronę internetową w przeglądarce na innym urządzeniu, aby się zalogować. Po zalogowaniu się użytkownik będzie mógł uzyskać tokeny dostępu i odświeżyć tokeny zgodnie z potrzebami.

W tym artykule opisano, jak programować aplikację bezpośrednio w oparciu o protokół. Jeśli to możliwe, zalecamy używanie obsługiwanych bibliotek Microsoft Authentication Libraries (MSAL) zamiast uzyskiwania tokenów i wywoływania zabezpieczonych internetowych interfejsów API. Przykładowe aplikacje korzystające z biblioteki MSAL można znaleźć na przykładach.

Diagram protokołu

Cały przepływ kodu urządzenia przedstawiono na poniższym diagramie. Każdy krok jest objaśniony w tym artykule.

Device code flow

Żądanie autoryzacji urządzenia

Klient musi najpierw sprawdzić serwer uwierzytelniania dla urządzenia i kodu użytkownika używanego do inicjowania uwierzytelniania. Klient zbiera to żądanie z punktu końcowego /devicecode . W żądaniu klient powinien również uwzględnić uprawnienia, które musi uzyskać od użytkownika.

Od momentu wysłania żądania użytkownik ma 15 minut na zalogowanie. Jest to wartość domyślna dla .expires_in Żądanie powinno zostać wykonane tylko wtedy, gdy użytkownik wskaże, że jest gotowy do zalogowania.

// 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=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=user.read%20openid%20profile

Parametr Warunek opis
tenant Wymagania Może to być /common, /consumerslub /organizations. Może to być również dzierżawa katalogów, z której chcesz zażądać uprawnień w formacie GUID lub przyjaznej nazwy.
client_id Wymagania Identyfikator aplikacji (klienta) przypisany do aplikacji przez centrum administracyjne firmy Microsoft — Rejestracje aplikacji.
scope Wymagania Rozdzielona spacjami lista zakresów , do których użytkownik ma wyrazić zgodę.

Odpowiedź na autoryzację urządzenia

Pomyślna odpowiedź to obiekt JSON zawierający wymagane informacje, aby umożliwić użytkownikowi logowanie się.

Parametr Format opis
device_code String Długi ciąg używany do weryfikowania sesji między klientem a serwerem autoryzacji. Klient używa tego parametru do żądania tokenu dostępu z serwera autoryzacji.
user_code String Krótki ciąg wyświetlany użytkownikowi w celu zidentyfikowania sesji na urządzeniu pomocniczym.
verification_uri Identyfikator URI Identyfikator URI, do user_code których użytkownik powinien przejść, aby się zalogować.
expires_in int Liczba sekund przed wygaśnięciem device_code i user_code .
interval int Liczba sekund, przez które klient powinien czekać między żądaniami sondowania.
message String Ciąg czytelny dla człowieka z instrukcjami dla użytkownika. Może to być zlokalizowane przez dołączenie parametru zapytania w żądaniu formularza ?mkt=xx-XX, wypełniając odpowiedni kod kultury języka.

Uwaga

Pole verification_uri_complete odpowiedzi nie jest obecnie uwzględniane ani obsługiwane. Wspominamy o tym, ponieważ jeśli przeczytasz standard , zostanie verification_uri_complete wyświetlony jako opcjonalna część standardu przepływu kodu urządzenia.

Uwierzytelnianie użytkownika

Po odebraniu user_code przez klienta wartości i verification_uriwartości są wyświetlane, a użytkownik jest kierowany do logowania się za pośrednictwem przeglądarki dla urządzeń przenośnych lub komputerów.

Jeśli użytkownik uwierzytelnia się przy użyciu konta osobistego, używając polecenia /common lub /consumers, zostanie poproszony o ponowne zalogowanie się w celu przeniesienia stanu uwierzytelniania na urządzenie. Dzieje się tak, ponieważ urządzenie nie może uzyskać dostępu do plików cookie użytkownika. Użytkownik musi wyrazić zgodę na uprawnienia żądane przez klienta. Nie dotyczy to jednak kont służbowych używanych do uwierzytelniania.

Podczas uwierzytelniania użytkownika w obiekcie verification_uriklient powinien sondować /token punkt końcowy dla żądanego tokenu przy użyciu .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=535fb089-9ff3-47b6-9bfb-4f1264799865&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
Parametr Wymagania opis
tenant Wymagania Ten sam alias dzierżawy lub dzierżawy używany w początkowym żądaniu.
grant_type Wymagania Musi być urn:ietf:params:oauth:grant-type:device_code
client_id Wymagania Musi być zgodna z wartością client_id używaną w początkowym żądaniu.
device_code Wymagania Element device_code zwrócony w żądaniu autoryzacji urządzenia.

Oczekiwane błędy

Przepływ kodu urządzenia jest protokołem sondowania, więc błędy obsługiwane klientowi muszą być oczekiwane przed ukończeniem uwierzytelniania użytkownika.

Błąd opis Akcja klienta
authorization_pending Użytkownik nie zakończył uwierzytelniania, ale nie anulował przepływu. Powtórz żądanie po co najmniej interval sekundach.
authorization_declined Użytkownik końcowy zaprzeczył żądaniu autoryzacji. Zatrzymaj sondowanie i przywróć stan nieuwierzytelniony.
bad_verification_code Wysłane device_code do punktu końcowego /token nie zostało rozpoznane. Sprawdź, czy klient wysyła poprawną wartość device_code w żądaniu.
expired_token Wartość parametru expires_in została przekroczona, a uwierzytelnianie nie jest już możliwe w przypadku device_codeelementu . Zatrzymaj sondowanie i przywróć stan nieuwierzytelniony.

Pomyślna odpowiedź uwierzytelniania

Pomyślna odpowiedź tokenu wygląda następująco:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Parametr Format opis
token_type String Zawsze wartość Bearer.
scope Oddzielone spacjami ciągi Jeśli zostanie zwrócony token dostępu, zostanie wymieniony zakresy, w których token dostępu jest prawidłowy.
expires_in int Liczba sekund prawidłowego dołączonego tokenu dostępu.
access_token Nieprzezroczystym ciągiem Wystawiono dla żądanych zakresów .
id_token JWT Wystawiono, jeśli oryginalny scope parametr zawierał openid zakres.
refresh_token Nieprzezroczystym ciągiem Wystawiono, jeśli oryginalny scope parametr zawiera offline_accesswartość .

Token odświeżania umożliwia uzyskanie nowych tokenów dostępu i tokenów odświeżania przy użyciu tego samego przepływu opisanego w dokumentacji przepływu kodu OAuth.

Ostrzeżenie

Nie próbuj weryfikować ani odczytywać tokenów dla żadnego interfejsu API, którego nie jesteś właścicielem, w tym tokenów w tym przykładzie, w kodzie. Tokeny dla usługi firmy Microsoft mogą używać specjalnego formatu, który nie będzie weryfikowany jako JWT, a także może być szyfrowany dla użytkowników klienta (konta Microsoft). Podczas odczytywania tokenów jest przydatnym narzędziem do debugowania i uczenia, nie należy brać zależności od tego w kodzie ani zakładać konkretnych informacji o tokenach, które nie są przeznaczone dla kontrolującego interfejsu API.