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

2025-04-02

Platforma tożsamości firmy 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 sposób programowania bezpośrednio względem protokołu w aplikacji. Jeśli to możliwe, zalecamy użycie obsługiwanych bibliotek uwierzytelniania firmy Microsoft (MSAL), aby uzyskać tokeny i wywołać zabezpieczone internetowe interfejsy 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.

Przepływ kodu urządzenia

Żą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 domyślna wartość 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=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile

Parametr	Warunek	Opis
`tenant`	Wymagane	Może to być `/common`, `/consumers`lub `/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`	Wymagane	Identyfikator aplikacji (klienta) przypisany do Twojej aplikacji przez Microsoft Entra admin center – App registrations.
`scope`	Wymagane	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	Forma	Opis
`device_code`	Sznurek	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`	Sznurek	Krótki ciąg wyświetlany użytkownikowi w celu zidentyfikowania sesji na urządzeniu pomocniczym.
`verification_uri`	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`	Sznurek	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=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Parametr	Wymagane	Opis
`tenant`	Wymagane	Ten sam alias dzierżawy lub dzierżawy używany w początkowym żądaniu.
`grant_type`	Wymagane	Musi być `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Wymagane	Musi być zgodna z wartością `client_id` używaną w początkowym żądaniu.
`device_code`	Wymagane	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_code`elementu .	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	Forma	Opis
`token_type`	Sznurek	Zawsze `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`	Nieprzezroczysty ciąg	Wystawione dla zakresów , które zostały żądane.
`id_token`	JWT	Wystawiono, jeśli oryginalny parametr `scope` zawierał zakres `openid`.
`refresh_token`	Nieprzezroczysty ciąg	Wystawiono, jeśli oryginalny parametr `scope` zawierał `offline_access`.

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ług 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 konsumenckich (konta Microsoft). Odczytywanie tokenów jest przydatnym narzędziem do debugowania i uczenia się, ale nie należy polegać na tym w kodzie ani zakładać szczególnych informacji o tokenach, które nie są przeznaczone dla API, które kontrolujesz.