TV ve Sınırlı Girişli Cihaz Uygulamaları için OAuth 2.0

Bu dokümanda, TV, oyun konsolu ve yazıcı gibi cihazlarda çalışan uygulamalar aracılığıyla Google API'lerine erişmek için OAuth 2.0 yetkilendirmesinin nasıl uygulanacağı açıklanmaktadır. Daha ayrıntılı belirtmek gerekirse bu akış, tarayıcı erişimi olmayan veya sınırlı giriş özelliklerine sahip cihazlar için tasarlanmıştır.

OAuth 2.0 sayesinde kullanıcılar, bir uygulamayla belirli verileri paylaşırken kullanıcı adlarını, şifrelerini ve diğer bilgilerini gizli tutabilir. Örneğin, bir TV uygulaması Google Drive'da depolanan bir dosyayı seçme izni almak için OAuth 2.0'u kullanabilir.

Bu akışı kullanan uygulamalar ayrı cihazlara dağıtıldığı için uygulamaların gizlilik sağlayamayacağı varsayılır. Kullanıcı uygulamadayken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Alternatifler

Android, iOS, macOS, Linux veya Windows (Universal Windows Platform dahil) gibi bir platform için tarayıcıya ve tam giriş özelliklerine erişimi olan bir uygulama yazıyorsanız mobil ve masaüstü uygulamaları için OAuth 2.0 akışını kullanın. (Uygulamanız grafik arayüzü olmayan bir komut satırı aracı olsa bile bu akışı kullanmanız gerekir.)

Kullanıcıların yalnızca Google Hesaplarıyla oturum açmasını ve temel kullanıcı profili bilgilerini almak için JWT kimlik jetonunu kullanmak istiyorsanız TV'lerde ve sınırlı giriş cihazlarında oturum açma başlıklı makaleyi inceleyin.

Ön koşullar

Projeniz için API'leri etkinleştirme

Google API'lerini çağıran tüm uygulamaların bu API'leri 'te etkinleştirmesi gerekir.

Projeniz için bir API'yi etkinleştirmek üzere:

1. ,
3. Bu sayfada, ürün ailesine ve popülerliğe göre gruplandırılmış tüm mevcut API'ler listelenir. Etkinleştirmek istediğiniz API listede görünmüyorsa arama yaparak bulabilir veya ait olduğu ürün ailesinde Tümünü Görüntüle'yi tıklayabilirsiniz.
4. Etkinleştirmek istediğiniz API'yi seçin ve ardından Etkinleştir düğmesini tıklayın.

Yetkilendirme kimlik bilgileri oluşturma

Google API'lerine erişmek için OAuth 2.0 kullanan tüm uygulamaların, Google'ın OAuth 2.0 sunucusunda uygulamayı tanımlayan yetkilendirme kimlik bilgilerine sahip olması gerekir. Aşağıdaki adımlarda, projeniz için kimlik bilgilerinin nasıl oluşturulacağı açıklanmaktadır. Ardından, uygulamalarınız bu proje için etkinleştirdiğiniz API'lere erişmek üzere kimlik bilgilerini kullanabilir.

2. Kimlik bilgisi oluştur > OAuth istemci kimliği seçeneğini tıklayın.
3. TV'ler ve Sınırlı Giriş cihazları uygulama türünü seçin.
4. OAuth 2.0 istemcinize ad verin ve Oluştur'u tıklayın.

Erişim kapsamlarını belirleme

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim isteğinde bulunmasını sağlarken kullanıcıların da uygulamanıza verdikleri erişim miktarını kontrol etmelerini sağlar. Bu nedenle, istenen kapsamların sayısı ile kullanıcı izni alma olasılığı arasında ters bir ilişki olabilir.

OAuth 2.0 yetkilendirmesini uygulamaya başlamadan önce, uygulamanızın erişmek için izin alması gereken kapsamları belirlemenizi öneririz.

Yüklü uygulamalar veya cihazlar için İzin verilen kapsamlar listesine bakın.

OAuth 2.0 erişim jetonları alma

Uygulamanız sınırlı giriş özelliklerine sahip bir cihazda çalışsa bile kullanıcıların bu yetkilendirme akışını tamamlamak için daha zengin giriş özelliklerine sahip bir cihaza ayrı erişimleri olmalıdır. Akış aşağıdaki adımları içerir:

1. Uygulamanız, Google'ın yetkilendirme sunucusuna bir istek göndererek uygulamanızın erişim izni isteyeceği kapsamları tanımlar.
2. Sunucu, sonraki adımlarda kullanılan cihaz kodu ve kullanıcı kodu gibi çeşitli bilgilerle yanıt verir.
3. Kullanıcının uygulamanızı yetkilendirmek için ayrı bir cihazda girebileceği bilgileri gösterirsiniz.
4. Uygulamanız, kullanıcının uygulamanıza yetki verip vermediğini belirlemek için Google'ın yetkilendirme sunucusunu yoklamaya başlar.
5. Kullanıcı, daha zengin giriş özelliklerine sahip bir cihaza geçer, bir web tarayıcısı başlatır, 3. adımda gösterilen URL'ye gider ve 3. adımda da gösterilen bir kodu girer. Kullanıcı, uygulamanıza erişim izni verebilir (veya reddedebilir).
6. Anket isteğinize verilen bir sonraki yanıt, uygulamanızın kullanıcı adına istekleri yetkilendirmek için ihtiyaç duyduğu jetonları içerir. (Kullanıcı uygulamanıza erişimi reddettiyse yanıt jeton içermez.)

Aşağıdaki resimde bu işlem gösterilmektedir:

Aşağıdaki bölümlerde bu adımlar ayrıntılı olarak açıklanmıştır. Cihazların sahip olabileceği çeşitli özellikler ve çalışma ortamı dikkate alınarak bu dokümanda gösterilen örneklerde curl komut satırı yardımcı programı kullanılmıştır. Bu örneklerin çeşitli dillere ve çalışma zamanlarına taşınması kolay olmalıdır.

1. adım: Cihaz ve kullanıcı kodları isteyin

Bu adımda cihazınız, https://oauth2.googleapis.com/device/code adresindeki Google'ın yetkilendirme sunucusuna bir HTTP POST isteği gönderir. Bu istek, uygulamanızın yanı sıra uygulamanızın kullanıcı adına erişmek istediği erişim kapsamlarını tanımlar. Bu URL'yi, device_authorization_endpoint meta veri değerini kullanarak Discovery belgesinden almanız gerekir. Aşağıdaki HTTP istek parametrelerini ekleyin:

Örnekler

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

Bu örnekte, aynı isteği göndermek için bir curl komutu gösterilmektedir:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

2. adım: Yetkilendirme sunucusu yanıtını işleyin

Yetkilendirme sunucusu aşağıdaki yanıtlardan birini döndürür:

Başarı yanıtı

İstek geçerliyse yanıtınız aşağıdaki özellikleri içeren bir JSON nesnesi olacaktır:

Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Kota aşıldı yanıtı

Cihaz kodu isteğiniz, istemci kimliğinizle ilişkili kotayı aştıysa aşağıdaki hatayı içeren bir 403 yanıtı alırsınız:

{
  "error_code": "rate_limit_exceeded"
}

Bu durumda, istek hızını azaltmak için geri çekilme stratejisi kullanın.

3. Adım: Kullanıcı kodunu gösterin

2. adımda elde edilen verification_url ve user_code değerlerini kullanıcıya gösterin. Her iki değer de US-ASCII karakter kümesinden herhangi bir yazdırılabilir karakter içerebilir. Kullanıcıya gösterdiğiniz içerikte, kullanıcıya ayrı bir cihazda verification_url'e gidip user_code'yi girmesini söylemelisiniz.

Kullanıcı arayüzünüzü (UI) aşağıdaki kuralları göz önünde bulundurarak tasarlayın:

• user_code
  • user_code, 15 adet "W" boyutunda karakteri işleyebilecek bir alanda gösterilmelidir. Diğer bir deyişle, WWWWWWWWWWWWWWW kodunu doğru şekilde gösterebiliyorsanız kullanıcı arayüzünüz geçerlidir ve user_code değerinin kullanıcı arayüzünüzde gösterilme şeklini test ederken bu dize değerini kullanmanızı öneririz.
  • user_code büyük/küçük harfe duyarlıdır ve büyük/küçük harf durumunu değiştirme veya başka biçimlendirme karakterleri ekleme gibi herhangi bir şekilde değiştirilmemelidir.
• verification_url
  • verification_url değerini görüntülediğiniz alan, 40 karakter uzunluğundaki bir URL dizesini barındıracak kadar geniş olmalıdır.
  • Gösterim şemasını isteğe bağlı olarak kaldırmak dışında verification_url'te hiçbir şekilde değişiklik yapmamalısınız. Görüntüleme nedeniyle URL'den şemayı (ör. https://) kaldırmayı planlıyorsanız uygulamanızın hem http hem de https varyantlarını işleyebildiğinden emin olun.

4. Adım: Google'ın yetkilendirme sunucusunu yoklayın

Kullanıcı, verification_url'e gitmek ve erişim izni vermek (veya reddetmek) için ayrı bir cihaz kullanacağından, kullanıcı erişim isteğine yanıt verdiğinde istek yapan cihaz otomatik olarak bilgilendirilmez. Bu nedenle, istek gönderen cihazın, kullanıcının isteğe ne zaman yanıt verdiğini belirlemek için Google'ın yetkilendirme sunucusunu sorgulaması gerekir.

İstekte bulunan cihaz, kullanıcının erişim isteğine yanıt verdiğini belirten bir yanıt alana veya 2. adımda elde edilen device_code ve user_code değerlerinin süresi dolana kadar anket isteği göndermeye devam etmelidir. 2. adımda döndürülen interval, istekler arasında beklemeniz gereken saniye cinsinden süreyi belirtir.

Anket yapılacak uç noktanın URL'si https://oauth2.googleapis.com/token. Anket isteği aşağıdaki parametreleri içerir:

Örnekler

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

Bu örnekte, aynı isteği göndermek için bir curl komutu gösterilmektedir:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

5. adım: Kullanıcı, erişim isteğine yanıt verir

Aşağıdaki resimde, 3. adımda gösterdiğiniz verification_url sayfasına gittiklerinde kullanıcıların göreceği sayfaya benzer bir sayfa gösterilmektedir:

Kullanıcı, user_code'yi girdikten ve henüz giriş yapmadıysa Google'a giriş yaptıktan sonra aşağıda gösterilen gibi bir izin ekranı görür:

6. adım: Anket isteklerine verilen yanıtları işleme

Google'ın yetkilendirme sunucusu, her anket isteği için aşağıdaki yanıtlardan biriyle yanıt verir:

Erişim izni verildi

Kullanıcı cihaza erişim izni verdiyse (izin ekranında Allow simgesini tıklayarak) yanıtta bir erişim jetonu ve yenileme jetonu bulunur. Jetonlar, cihazınızın kullanıcı adına Google API'lerine erişmesini sağlar. (Yanıttaki scope mülkü, cihazın hangi API'lere erişebileceğini belirler.)

Bu durumda API yanıtı aşağıdaki alanları içerir:

Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Erişim jetonlarının kullanım ömrü sınırlıdır. Uygulamanızın uzun süre boyunca bir API'ye erişmesi gerekiyorsa yeni bir erişim jetonu almak için yenileme jetonunu kullanabilir. Uygulamanızın bu tür erişime ihtiyacı varsa yenileme jetonunu daha sonra kullanmak için saklamalıdır.

Erişim reddedildi

Kullanıcı cihaza erişim izni vermezse sunucu yanıtında 403 HTTP yanıt durum kodu (Forbidden) bulunur. Yanıt şu hatayı içerir:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Yetkilendirme bekleniyor

Kullanıcı henüz yetkilendirme akışını tamamlamadıysa sunucu bir 428 HTTP yanıt durum kodu (Precondition Required) döndürür. Yanıt şu hatayı içerir:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Çok sık anket yapılması

Cihaz çok sık anket isteği gönderirse sunucu bir 403 HTTP yanıt durum kodu (Forbidden) döndürür. Yanıt, aşağıdaki hatayı içerir:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Diğer hatalar

Yetkilendirme sunucusu, anket isteğinde gerekli parametreler eksikse veya yanlış bir parametre değeri varsa da hata döndürür. Bu isteklerin genellikle 400 (Bad Request) veya 401 (Unauthorized) HTTP yanıt durum kodu vardır. Bu hatalar şunlardır:

Google API'lerini çağırma

Uygulamanız bir erişim jetonu aldıktan sonra, API tarafından istenen erişim kapsamları verilmişse belirli bir kullanıcı hesabı adına bir Google API'sine çağrı yapmak için jetonu kullanabilirsiniz. Bunu yapmak için access_token sorgu parametresi veya Authorization HTTP üst bilgisi Bearer değeri ekleyerek erişim jetonunu API'ye gönderilen bir isteğe ekleyin. Sorgu dizeleri sunucu günlüklerinde görünmeye eğilimli olduğundan, mümkün olduğunda HTTP üst bilgisi tercih edilir. Çoğu durumda, Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, Drive Files API'yi çağırırken).

Tüm Google API'lerini deneyebilir ve kapsamlarını OAuth 2.0 Playground'da görüntüleyebilirsiniz.

HTTP GET örnekleri

Authorization: Bearer HTTP üst bilgisi kullanılarak drive.files uç noktasına (Drive Dosyalar API'si) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Kimliği doğrulanmış kullanıcı için access_token sorgu dizesi parametresini kullanan aynı API'ye yapılan bir çağrı aşağıda verilmiştir:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl örnek

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üst bilgisi seçeneğini kullanan bir örneği aşağıda bulabilirsiniz (tercih edilir):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternatif olarak sorgu dizesi parametresi seçeneğini de kullanabilirsiniz:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Erişim jetonunu yenileme

Erişim jetonlarının süresi düzenli olarak dolar ve ilgili API isteği için geçersiz kimlik bilgileri haline gelir. Jetonla ilişkili kapsamlara çevrimdışı erişim isteğinde bulunduysanız kullanıcıdan izin istemeden (kullanıcı mevcut olmadığında dahil) bir erişim jetonunu yenileyebilirsiniz.

Uygulamanız, bir erişim jetonunu yenilemek için Google'ın yetkilendirme sunucusuna (https://oauth2.googleapis.com/token) aşağıdaki parametreleri içeren bir HTTPS POST isteğinde bulunur:

Aşağıdaki snippet'te örnek bir istek gösterilmektedir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Kullanıcı, uygulamaya verilen erişimi iptal etmediği sürece jeton sunucusu yeni bir erişim jetonu içeren bir JSON nesnesi döndürür. Aşağıdaki snippet'te örnek bir yanıt gösterilmektedir:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Verilecek yenileme jetonu sayısıyla ilgili sınırlamalar olduğunu unutmayın. Bu sınırlamalar, istemci/kullanıcı kombinasyonu başına bir tane ve tüm istemciler genelinde kullanıcı başına bir tanedir. Yenileme jetonlarını uzun süreli depolama alanına kaydetmeniz ve geçerli oldukları sürece kullanmaya devam etmeniz gerekir. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara ulaşabilir. Bu durumda eski yenileme jetonları çalışmayı durdurur.

Jetonu iptal etme

Bazı durumlarda kullanıcılar, bir uygulamaya verilen erişimi iptal etmek isteyebilir. Kullanıcılar Hesap Ayarları'nı ziyaret ederek erişimi iptal edebilir. Daha fazla bilgi için Hesabınıza erişimi olan üçüncü taraf site ve uygulamaların Site veya uygulama erişimini kaldırma bölümünü inceleyin.

Bir uygulamanın kendisine verilen erişimi programatik olarak iptal etmesi de mümkündür. Programatik iptal, kullanıcının aboneliğini iptal ettiği, bir uygulamayı kaldırdığı veya bir uygulamanın ihtiyaç duyduğu API kaynaklarının önemli ölçüde değiştiği durumlarda önemlidir. Diğer bir deyişle, kaldırma işleminin bir kısmı, daha önce uygulamaya verilen izinlerin kaldırılmasını sağlamak için bir API isteği içerebilir.

Bir jetonu programatik olarak iptal etmek için uygulamanız https://oauth2.googleapis.com/revoke adresine bir istek gönderir ve jetonu parametre olarak ekler:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Jeton, erişim jetonu veya yenileme jetonu olabilir. Jeton bir erişim jetonuysa ve buna karşılık gelen bir yenileme jetonu varsa yenileme jetonu da iptal edilir.

İptal işlemi başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata durumlarında, hata koduyla birlikte bir HTTP durum kodu 400 döndürülür.

İzin verilen kapsamlar

Cihazlar için OAuth 2.0 akışı yalnızca aşağıdaki kapsamlarda desteklenir: