Mobil ve Masaüstü Uygulamaları için OAuth 2.0

Bu belgede, telefon, tablet ve bilgisayar gibi cihazlara yüklenen uygulamaların YouTube Data API'ye erişimi yetkilendirmek için Google'ın OAuth 2.0 uç noktalarını nasıl kullandığı açıklanmaktadı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 uygulama, kullanıcının YouTube kanalına video yükleme izni almak için OAuth 2.0'ı kullanabilir.

Yüklenen uygulamalar tek tek cihazlara dağıtılır ve bu uygulamaların sır saklayamayacağı varsayılır. Kullanıcı uygulamada bulunurken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Bu yetkilendirme akışı, web sunucusu uygulamaları için kullanılan akışa benzer. Aradaki temel fark, yüklü uygulamaların sistem tarayıcısını açması ve Google'ın yetkilendirme sunucusundan gelen yanıtları işlemek için yerel bir yönlendirme URI'si sağlaması gerektiğidir.

Kitaplıklar ve örnekler

Mobil uygulamalar için Android'de Google Kimlik Hizmetleri yerel kitaplığının, iOS'te ise Google ile Oturum Açma yerel kitaplığının en yeni sürümünü kullanmanızı öneririz. Bu kitaplıklar, kullanıcı yetkilendirmesini yönetir ve burada açıklanan alt düzey protokole kıyasla uygulaması daha kolaydır.

Sistem tarayıcısını desteklemeyen veya sınırlı giriş özelliklerine sahip cihazlarda (ör. TV'ler, oyun konsolları, kameralar ya da yazıcılar) çalışan uygulamalar için TV'ler ve Cihazlar İçin OAuth 2.0 veya 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 API Console'de etkinleştirmesi gerekir.

Projenizde bir API'yi etkinleştirmek için:

1. Open the API Library in the Google API Console.
2. If prompted, select a project, or create a new one.
3. YouTube Data API'yi bulup etkinleştirmek için Kitaplık sayfasını kullanın. Uygulamanızın kullanacağı diğer API'leri bulun ve bunları da etkinleştirin.

Yetkilendirme kimlik bilgileri oluşturma

Google API'lerine erişmek için OAuth 2.0'ı kullanan tüm uygulamaların, uygulamayı Google'ın OAuth 2.0 sunucusuna tanıtan yetkilendirme kimlik bilgilerine sahip olması gerekir. Aşağıdaki adımlarda, projeniz için nasıl kimlik bilgisi oluşturacağınız açıklanmaktadır. Uygulamalarınız daha sonra bu kimlik bilgilerini kullanarak söz konusu proje için etkinleştirdiğiniz API'lere erişebilir.

1. Go to the Credentials page.
2. Müşteri oluştur'u tıklayın.
3. Aşağıdaki bölümlerde, Google'ın yetkilendirme sunucusunun desteklediği istemci türleri açıklanmaktadır. Uygulamanız için önerilen istemci türünü seçin, OAuth istemcinizi adlandırın ve formdaki diğer alanları uygun şekilde ayarlayın.

Erişim kapsamlarını belirleme

Kapsamlar, uygulamanızın yalnızca ihtiyaç duyduğu kaynaklara erişim isteğinde bulunmasını sağlar. Ayrıca, kullanıcıların uygulamanıza verdiği erişim miktarını kontrol etmesine de olanak tanır. Bu nedenle, istenen kapsam 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şim izni gerektireceği kapsamları belirlemenizi öneririz.

YouTube Data API v3 aşağıdaki kapsamları kullanır:

OAuth 2.0 API Kapsamları dokümanında, Google API'lerine erişmek için kullanabileceğiniz kapsamların tam listesi yer alır.

OAuth 2.0 erişim jetonlarını edinme

Aşağıdaki adımlarda, uygulamanızın Google'ın OAuth 2.0 sunucusuyla nasıl etkileşimde bulunarak kullanıcı adına bir API isteği gerçekleştirmek için kullanıcının iznini aldığı gösterilmektedir. Uygulamanızın, kullanıcı yetkilendirmesi gerektiren bir Google API isteğini yürütebilmesi için bu izne sahip olması gerekir.

1. adım: Kod doğrulayıcı ve sorgu oluşturun

Google, yüklenen uygulama akışını daha güvenli hale getirmek için Proof Key for Code Exchange (PKCE) protokolünü destekler. Her yetkilendirme isteği için benzersiz bir kod doğrulayıcı oluşturulur ve "code_challenge" adı verilen dönüştürülmüş değeri, yetkilendirme kodunu almak için yetkilendirme sunucusuna gönderilir.

Kod doğrulayıcıyı oluşturma

code_verifier, ayrılmamış karakterler [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" kullanılarak oluşturulan, yüksek entropili bir kriptografik rastgele dizedir. Minimum uzunluğu 43 karakter, maksimum uzunluğu ise 128 karakterdir.

Kod doğrulayıcı, değeri tahmin etmeyi pratik olmayacak kadar zorlaştıracak kadar yeterli entropiye sahip olmalıdır.

Kod doğrulamasını oluşturma

Kod zorluğu oluşturmak için iki yöntem desteklenir.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

2. adım: Google'ın OAuth 2.0 sunucusuna istek gönderin

Kullanıcı yetkisi almak için https://accounts.google.com/o/oauth2/v2/auth adresindeki Google'ın yetkilendirme sunucusuna istek gönderin. Bu uç nokta, etkin oturum aramasını işler, kullanıcının kimliğini doğrular ve kullanıcı iznini alır. Uç noktaya yalnızca SSL üzerinden erişilebilir ve HTTP (SSL olmayan) bağlantıları reddeder.

Yetkilendirme sunucusu, yüklü uygulamalar için aşağıdaki sorgu dizesi parametrelerini destekler:

Örnek yetkilendirme URL'leri

Aşağıdaki sekmelerde, farklı yönlendirme URI'si seçenekleri için örnek yetkilendirme URL'leri gösterilmektedir.

URL'ler, redirect_uri parametresinin değeri dışında aynıdır. URL'ler, zorunlu response_type ve client_id parametrelerinin yanı sıra isteğe bağlı state parametresini de içerir. Her URL, okunabilirlik için satır sonları ve boşluklar içerir.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

3. adım: Google, kullanıcıdan izin ister

Bu adımda kullanıcı, uygulamanıza istenen erişimi verip vermeyeceğine karar verir. Bu aşamada Google, uygulamanızın adını ve kullanıcının yetkilendirme kimlik bilgileriyle erişim izni istediği Google API hizmetlerini gösteren bir izin penceresi ile verilecek erişim kapsamlarının özetini gösterir. Kullanıcı daha sonra uygulamanızın istediği bir veya daha fazla kapsam için erişim izni vermeyi kabul edebilir ya da isteği reddedebilir.

Uygulamanızın, Google'ın OAuth 2.0 sunucusundan erişim izni verilip verilmediğini belirten yanıtı beklerken bu aşamada herhangi bir işlem yapması gerekmez. Bu yanıt, sonraki adımda açıklanmaktadır.

4. adım: OAuth 2.0 sunucu yanıtını işleyin

Uygulamanızın yetkilendirme yanıtını alma şekli, kullandığı yönlendirme URI şemasına bağlıdır. Şemadan bağımsız olarak yanıtta yetkilendirme kodu (code) veya hata (error) bulunur. Örneğin, error=access_denied, kullanıcının isteği reddettiğini gösterir.

Kullanıcı uygulamanıza erişim izni verirse yetkilendirme kodunu, bir sonraki adımda açıklandığı gibi erişim jetonu ve yenileme jetonuyla değiştirebilirsiniz.

5. adım: Yetkilendirme kodunu yenileme ve erişim jetonlarıyla değiştirin

Yetkilendirme kodunu erişim jetonuyla değiştirmek için https://oauth2.googleapis.com/token uç noktasını çağırın ve aşağıdaki parametreleri ayarlayın:

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google, bu isteğe kısa ömürlü bir erişim jetonu ve bir yenileme jetonu içeren bir JSON nesnesi döndürerek yanıt verir.

Yanıtta aşağıdaki alanlar bulunur:

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

6. adım: Kullanıcıların hangi kapsamları verdiğini kontrol edin

Kullanıcılar, birden fazla izin (kapsam) istediğinizde uygulamanızın hepsine erişmesine izin vermeyebilir. Uygulamanız, hangi kapsamların gerçekten verildiğini doğrulamalı ve bazı izinlerin reddedildiği durumları sorunsuz bir şekilde ele almalıdır. Bu genellikle reddedilen kapsamları kullanan özelliklerin devre dışı bırakılmasıyla yapılır.

Ancak istisnalar bulunmaktadır. Alan genelinde yetki devri olan Google Workspace Enterprise uygulamaları veya Güvenilir olarak işaretlenen uygulamalar, ayrıntılı izinler kullanıcı rızası ekranını atlar. Bu uygulamalarda kullanıcılar ayrıntılı izin onay ekranını görmez. Bunun yerine, uygulamanız istenen tüm kapsamları veya hiçbirini almaz.

Daha ayrıntılı bilgi için Ayrıntılı izinleri yönetme başlıklı makaleyi inceleyin.

Kullanıcının uygulamanıza belirli bir kapsam için erişim izni verip vermediğini kontrol etmek için erişim jetonu yanıtındaki scope alanını inceleyin. access_token tarafından verilen erişim kapsamları, boşlukla ayrılmış, büyük/küçük harfe duyarlı dizeler listesi olarak ifade edilir.

Örneğin, aşağıdaki örnek erişim jetonu yanıtı, kullanıcının uygulamanıza kullanıcının YouTube videolarını, derecelendirmelerini, yorumlarını ve altyazılarını görme, düzenleme ve kalıcı olarak silme izni verdiğini gösterir:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Google API'lerini çağırma

Uygulamanız bir erişim jetonu aldıktan sonra, API'nin gerektirdiği erişim kapsamları verilmişse jetonu kullanarak belirli bir kullanıcı hesabı adına Google API'sine çağrı yapabilirsiniz. Bunu yapmak için API'ye yapılan bir isteğe erişim jetonunu ekleyin. Bunun için access_token sorgu parametresini veya Authorization HTTP üstbilgisi Bearer değerini ekleyebilirsiniz. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üstbilgisi tercih edilir. Çoğu durumda, Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, YouTube Data API'yi çağırırken).

YouTube Data API'nin yalnızca plak şirketleri ve film stüdyoları gibi birden fazla YouTube kanalına sahip olan ve bu kanalları yöneten YouTube içerik sahipleri için hizmet hesaplarını desteklediğini unutmayın.

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

HTTP GET örnekleri

Authorization: Bearer HTTP üstbilgisi kullanılarak youtube.channels uç noktasına (YouTube Data API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Aşağıda, access_token sorgu dizesi parametresi kullanılarak kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı verilmiştir:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

curl örnek

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üstbilgisi seçeneğinin (tercih edilen) kullanıldığı bir örneği aşağıda bulabilirsiniz:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

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 kapsamlar için çevrimdışı erişim isteğinde bulunduysanız kullanıcıdan izin istemeden (kullanıcı mevcut değilken de dahil olmak üzere) erişim jetonunu yenileyebilirsiniz.

Erişim jetonunu yenilemek için uygulamanız, Google'ın yetkilendirme sunucusuna (https://oauth2.googleapis.com/token) aşağıdaki parametreleri içeren bir HTTPS POST isteği gönderir:

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",
  "token_type": "Bearer"
}

Yenileme jetonlarının sayısıyla ilgili sınırlamalar olduğunu unutmayın. Bir sınırlama, istemci/kullanıcı kombinasyonu başına, diğeri ise tüm istemcilerdeki kullanıcı başına uygulanır. Yenileme jetonlarını uzun süreli depolama alanına kaydetmeli ve geçerli oldukları sürece kullanmaya devam etmelisiniz. Uygulamanız çok fazla yenileme jetonu isterse bu sınırlara takılabilir. 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ı, 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 başlıklı destek belgesinin Site veya uygulama erişimini kaldırma bölümüne bakın.

Bir uygulamanın, kendisine verilen erişimi programatik olarak iptal etmesi de mümkündür. Kullanıcının e-posta listesinden çıktığı, bir uygulamayı kaldırdığı veya bir uygulamanın ihtiyaç duyduğu API kaynaklarının önemli ölçüde değiştiği durumlarda programatik iptal önemlidir. Diğer bir deyişle, kaldırma işleminin bir parçası olarak, daha önce uygulamaya verilen izinlerin kaldırıldığından emin olmak için bir API isteği gönderilebilir.

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

Uygulama yönlendirme yöntemleri

Uygulamalarınızı koruma

Zamana dayalı erişim

Zamana dayalı erişim, kullanıcının bir işlemi tamamlamak için sınırlı bir süre boyunca uygulamanıza verilerine erişim izni vermesine olanak tanır. İzin akışı sırasında belirli Google ürünlerinde kullanılabilen zamana dayalı erişim, kullanıcılara sınırlı bir süre için erişim izni verme seçeneği sunar. Örneğin, Data Portability API, tek seferlik veri aktarımına olanak tanır.

Kullanıcı, uygulamanıza zamana dayalı erişim izni verdiğinde yenileme jetonunun süresi belirtilen süre sonunda dolar. Yenileme jetonlarının belirli durumlarda daha erken geçersiz kılınabileceğini unutmayın. Ayrıntılar için bu durumlara bakın. Yetkilendirme kodu değiştirme yanıtında döndürülen refresh_token_expires_in alanı, bu gibi durumlarda yenileme jetonunun süresinin dolmasına kadar kalan süreyi gösterir.

Daha fazla bilgi

IETF Best Current Practice OAuth 2.0 for Native Apps (Yerel Uygulamalar İçin OAuth 2.0) burada belgelenen en iyi uygulamaların çoğunu belirler.