Microsoft kimlik platformu ve OAuth 2.0 cihaz yetkilendirmesi verme akışı

2025-04-02

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ızdaki protokole karşı doğrudan programlama açıklanmaktadır. Mümkün olduğunda, belirteçleri almak ve güvenli web API'lerini çağırmak içindesteklenen 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.

Cihaz kodu akışı

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ç noktasından 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, expires_iniçin varsayı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	, `/common`veya `/consumers`olabilir`/organizations`. Ayrıca, GUID veya kolay ad biçiminde izin istemek istediğiniz dizin kiracısı da olabilir.
`client_id`	Gerekli	Microsoft Entra yönetim merkezi – Uygulama kayıtları deneyiminin uygulamanıza atadığı Uygulama (istemci) kimliği.
`scope`	Gerekli	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çim	Açıklama
`device_code`	Dize	İ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`	Dize	İkincil bir cihazdaki oturumu tanımlamak için kullanılan kullanıcıya gösterilen kısa dize.
`verification_uri`	URI (Evrensel Kaynak Tanımlayıcısı)	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`	Dize	Kullanıcı için yönergeler içeren, insan tarafından okunabilen bir dize. Bu, formun `?mkt=xx-XX`isteğine bir sorgu parametresi eklenerek, uygun dil kültürü kodunu doldurarak yerelleştirilebilir.

Uyarı

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	Gerekli	Açıklama
`tenant`	Gerekli	İlk istekte kullanılan kiracı veya kiracı diğer adı.
`grant_type`	Gerekli	Olmalıdır `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Gerekli	İlk istekte `client_id` kullanılanla eşleşmelidir.
`device_code`	Gerekli	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_code`kimlik 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çim	Açıklama
`token_type`	Dize	Her zaman `Bearer`.
`scope`	Boşlukla ayrılmış ifadeler	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 metin	İstenen kapsamları için verilir.
`id_token`	JWT	Özgün `scope` parametresi `openid` kapsamını dahil ettiyse verilir.
`refresh_token`	Opak metin	Özgün `scope` parametresi `offline_access`dahil edilmiş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 için belirteçler 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.

Aracılığıyla paylaş