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.
Żą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=00001111-aaaa-2222-bbbb-3333cccc4444
&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=00001111-aaaa-2222-bbbb-3333cccc4444&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.