Aracılığıyla paylaş


Microsoft kimlik platformu ve OAuth 2.0 cihaz yetkilendirme izni akışı

Microsoft kimlik platformu, kullanıcıların akıllı TV, IoT cihazı veya yazıcı gibi giriş kısıtlanmış cihazlarda oturum açmasına olanak tanıyan cihaz yetkilendirme iznini destekler. Cihaz, bu akışı etkinleştirmek için kullanıcının oturum açmak üzere başka bir cihazdaki bir tarayıcıdaki web sayfasını ziyaret etmelerini sağlar. Kullanıcı oturum açtığında, cihaz gerektiğinde erişim belirteçleri alabilir ve belirteçleri yenileyebilir.

Bu makalede uygulamanızda doğrudan protokol için programlama işlemi açıklanır. Mümkün olduğunda, belirteçleri almak ve güvenli web API’lerini aramak yerine desteklenen Microsoft Kimlik Doğrulama Kitaplıklarını (MSAL) kullanmanızı öneririz. Örnekler için MSAL kullanan örnek uygulamalara başvurabilirsiniz.

Protokol diyagramı

Cihaz kodu akışının tamamı aşağıdaki diyagramda gösterilmiştir. Her adım bu makale boyunca açıklanmıştır.

Device code flow

Cihaz yetkilendirme isteği

İstemcinin önce kimlik doğrulamasını başlatmak için kullanılan cihaz ve kullanıcı kodu için kimlik doğrulama sunucusuyla denetim yapması gerekir. İstemci bu isteği /devicecode uç noktadan toplar. İstekte, istemcinin kullanıcıdan alması gereken izinleri de içermesi gerekir.

İstek gönderildiği andan itibaren kullanıcının oturum açması için 15 dakikası vardır. Bu, için expires_invarsayılan değerdir. İstek yalnızca kullanıcı oturum açmaya hazır olduğunu belirttiğinde yapılmalıdır.

// 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

Parametre Koşul Açıklama
tenant Gerekli , /consumersveya /organizationsolabilir/common. Ayrıca, GUID veya kolay ad biçiminde izin istemek istediğiniz dizin kiracısı da olabilir.
client_id Zorunlu Microsoft Entra yönetim merkezinin uygulamanıza atanmış Uygulama kayıtları deneyimi olan Uygulama (istemci) kimliği.
scope Zorunlu Kullanıcının onaylamasını istediğiniz kapsamların boşlukla ayrılmış listesi.

Cihaz yetkilendirme yanıtı

Başarılı bir yanıt, kullanıcının oturum açmasına izin vermek için gerekli bilgileri içeren bir JSON nesnesidir.

Parametre Biçimlendir Açıklama
device_code String İstemci ile yetkilendirme sunucusu arasındaki oturumu doğrulamak için kullanılan uzun dize. İstemci, yetkilendirme sunucusundan erişim belirtecini istemek için bu parametreyi kullanır.
user_code String İkincil bir cihazdaki oturumu tanımlamak için kullanılan kullanıcıya gösterilen kısa dize.
verification_uri URI Oturum açmak için kullanıcının ile birlikte user_code gitmesi gereken URI.
expires_in int ve user_code süresi dolmadan önceki device_code saniye sayısı.
interval int İstemcinin yoklama istekleri arasında beklemesi gereken saniye sayısı.
message String Kullanıcı için yönergeler içeren, insan tarafından okunabilen bir dize. Bu, formun ?mkt=xx-XXisteğine bir sorgu parametresi eklenerek, uygun dil kültürü kodunu doldurarak yerelleştirilebilir.

Not

Yanıt verification_uri_complete alanı şu anda dahil değil veya desteklenmiyor. Bunun nedeni, standardı okursanız cihaz kodu akışı standardının isteğe bağlı bir parçası olarak listelendiğini görmenizdir verification_uri_complete .

Kullanıcının kimliğini doğrulama

İstemci ve verification_urideğerini aldıktan user_code sonra değerler görüntülenir ve kullanıcı mobil veya bilgisayar tarayıcısı üzerinden oturum açmaya yönlendirilir.

Kullanıcı veya /consumerskullanarak /common kişisel bir hesapla kimlik doğrulaması yaparsa, kimlik doğrulama durumunu cihaza aktarmak için yeniden oturum açması istenir. Bunun nedeni cihazın kullanıcının tanımlama bilgilerine erişememesidir. İstemci tarafından istenen izinlere onay vermeleri istenir. Ancak bu, kimlik doğrulaması için kullanılan iş veya okul hesapları için geçerli değildir.

Kullanıcı adresinde verification_urikimlik doğrulaması yaparken istemcinin istenen belirtecin uç noktasını kullanarak device_codeyoklaması /token gerekir.

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...
Parametre Zorunlu Açıklama
tenant Gerekli İlk istekte kullanılan kiracı veya kiracı diğer adı.
grant_type Zorunlu Olmalıdır urn:ietf:params:oauth:grant-type:device_code
client_id Zorunlu İlk istekte client_id kullanılanla eşleşmelidir.
device_code Zorunlu Cihaz device_code yetkilendirme isteğinde döndürülen.

Beklenen hatalar

Cihaz kodu akışı bir yoklama protokolü olduğundan, kullanıcı kimlik doğrulaması tamamlanmadan önce istemciye sunulan hataların beklenmesi gerekir.

Hata Açıklama İstemci Eylemi
authorization_pending Kullanıcı kimlik doğrulamasını tamamlamamış ancak akışı iptal etmemiştir. İsteği en az interval saniye sonra yineleyin.
authorization_declined Son kullanıcı yetkilendirme isteğini reddetti. Yoklamayı durdurun ve kimliği doğrulanmamış bir duruma geri döndürin.
bad_verification_code device_code Uç noktaya gönderilenler /token tanınmadı. İstemcinin istekte doğruyu device_code gönderdiğini doğrulayın.
expired_token expires_in değeri aşıldı ve ile device_codekimlik doğrulaması artık mümkün değil. Yoklamayı durdurun ve kimliği doğrulanmamış bir duruma geri döndürin.

Başarılı kimlik doğrulaması yanıtı

Başarılı bir belirteç yanıtı şöyle görünür:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
Parametre Biçimlendir Açıklama
token_type String Her zaman Bearer.
scope Boşlukla ayrılmış dizeler Erişim belirteci döndürülürse, erişim belirtecinin geçerli olduğu kapsamlar listelenir.
expires_in int Dahil edilen erişim belirtecinin geçerli olduğu saniye sayısı.
access_token Opak dize İstenen kapsamlar için verildi.
id_token JWT Özgün scope parametre kapsamı dahil ettiyse verilir openid .
refresh_token Opak dize Özgün scope parametre dahil offline_accessedilmişse verilir.

Yenileme belirtecini, OAuth Code akışı belgelerinde belgelenen akışı kullanarak yeni erişim belirteçleri almak ve belirteçleri yenilemek için kullanabilirsiniz.

Uyarı

Bu örnekteki belirteçler de dahil olmak üzere sahip olmadığınız API'lerin belirteçlerini kodunuzda doğrulamayı veya okumayı denemeyin. Microsoft hizmetleri belirteçleri JWT olarak doğrulanmayacak özel bir biçim kullanabilir ve tüketici (Microsoft hesabı) kullanıcıları için de şifrelenebilir. Belirteçleri okumak yararlı bir hata ayıklama ve öğrenme aracı olsa da, kodunuzda buna bağımlılıkları almayın veya denetlediğiniz bir API için olmayan belirteçlerle ilgili belirli bilgileri varsaymayın.