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.
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=535fb089-9ff3-47b6-9bfb-4f1264799865&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.