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

Bu dokümanda, telefon, tablet ve bilgisayar gibi cihazlara yüklenen uygulamaların, Google API'lerine erişimi yetkilendirmek için Google'ın OAuth 2.0 uç noktalarını nasıl kullandığı açıklanmaktadır.

OAuth 2.0, kullanıcıların kullanıcı adlarını, şifrelerini ve diğer bilgilerini gizli tutarken kullanıcıların belirli verileri bir uygulamayla paylaşmasına olanak tanır. Örneğin, bir uygulama, kullanıcılardan Google Drive'larında dosya depolama izni almak için OAuth 2.0'ı kullanabilir.

Yüklü uygulamalar ayrı ayrı cihazlara dağıtılır ve bu uygulamaların sır tutamayacağı varsayılır. Google API'lerine, kullanıcı uygulamada varken veya uygulama arka planda çalışırken erişebilir.

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

Alternatifler

Mobil uygulamalarda Android veya iOS için Google ile Oturum Açma özelliğini kullanmayı tercih edebilirsiniz. Google ile Oturum Açma istemci kitaplıkları, kimlik doğrulama ve kullanıcı yetkilendirme işlemlerini yönetir. Bu kitaplıkların uygulanması, burada açıklanan alt düzey protokolden daha basit olabilir.

Sistem tarayıcısını desteklemeyen veya TV'ler, oyun konsolları, kameralar veya yazıcılar gibi sınırlı giriş özelliklerine sahip cihazlarda çalışan uygulamalar için TV'ler ve Cihazlar için OAuth 2.0 veya TV'lerde ve Sınırlı Giriş Cihazlarında oturum açma bölümlerine bakın.

Kitaplıklar ve örnekler

Bu dokümanda açıklanan OAuth 2.0 akışını uygulamanıza yardımcı olması için aşağıdaki kitaplıkları ve örnekleri öneririz:

• Android için AppAuth kitaplığı
• iOS için AppAuth kitaplığı
• Uygulamalar için OAuth: Windows Örnekleri

Ön koşullar

Projeniz için API'leri etkinleştirin

Google API'lerini çağıran uygulamaların, bu API'leri API Consoleiçinde etkinleştirmesi gerekir.

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

1. Open the API Library Google API Consoleiçinde gösteriliyor.
2. If prompted, select a project, or create a new one.
3. API Library sütununda, ürün ailesine ve popülerliğe göre gruplandırılmış tüm API'ler listelenir. Etkinleştirmek istediğiniz API listede görünmüyorsa bulmak için aramayı kullanın veya ait olduğu ürün ailesinde Tümünü Görüntüle'yi tıklayın.
4. Etkinleştirmek istediğiniz API'yi seçip Etkinleştir düğmesini tıklayın.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Yetkilendirme kimlik bilgileri oluştur

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

1. Go to the Credentials page.
2. Kimlik bilgisi oluştur > OAuth istemci kimliği seçeneğini tıklayın.
3. Aşağıdaki bölümlerde, Google'ın yetkilendirme sunucusunun desteklediği istemci türleri ve yönlendirme yöntemleri açıklanmaktadır. Uygulamanız için önerilen istemci türünü seçin, OAuth istemcinize ad verin 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 istemesine olanak tanırken kullanıcıların uygulamanıza verdikleri erişim miktarını da kontrol edebilmesini sağlar. Dolayısıyla, istenen kapsamların sayısı ile kullanıcıdan izin alma olasılığı arasında ters bir ilişki olabilir.

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

OAuth 2.0 API Kapsamları belgesi, Google API'lerine erişmek için kullanabileceğiniz kapsamların tam listesini içerir.

OAuth 2.0 erişim jetonları edinme

Aşağıdaki adımlarda, uygulamanızın kullanıcı adına API isteği gerçekleştirme izni almak için Google'ın OAuth 2.0 sunucusuyla nasıl etkileşimde bulunduğu gösterilmektedir. Uygulamanızın, kullanıcı yetkilendirmesi gerektiren bir Google API isteğini yürütebilmesi için önce bu izni alması gerekir.

1. Adım: Kod doğrulayıcı ve giriş sorgulaması oluşturun

Google, yüklü uygulama akışını daha güvenli hale getirmek için Kod Değişimi İçin Kanıt Anahtarı (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ğer, yetkilendirme kodunu almak üzere yetkilendirme sunucusuna gönderilir.

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

code_verifier, ayrılmamış [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" karakterlerinin kullanıldığı, en az 43 karakter ve maksimum 128 karakter uzunluğunda olan yüksek entropili kriptografik rastgele bir dizedir.

Kod doğrulayıcı, değerin tahmin edilmesini imkansız hale getirecek kadar entropiye sahip olmalıdır.

Kod sorgulamasını oluşturma

Kod sorgulamasını oluşturmanın iki yöntemi desteklenir.

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

code_challenge = code_verifier

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

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

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

Örnek yetkilendirme URL'leri

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

redirect_uri parametresinin değeri dışında URL'ler aynıdır. URL'ler gerekli 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=email%20profile&
 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=email%20profile&
 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şim iznini 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 ve verilecek erişim kapsamlarının özetini gösteren bir izin penceresi gösterir. Böylece kullanıcı, uygulamanızın istediği bir veya daha fazla kapsama erişim izni verebilir veya isteği reddedebilir.

Google'ın OAuth 2.0 sunucusundan herhangi bir erişim verilip verilmediğini belirten yanıtı beklediği için uygulamanızın bu aşamada herhangi bir işlem yapmasına gerek yoktur. Bu yanıt, aşağıdaki adımda açıklanmıştı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ıt, bir yetkilendirme kodu (code) veya bir hata (error) içerir. Örneğin, error=access_denied, kullanıcının isteği reddettiğini belirtir.

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

5. Adım: Yenileme ve erişim jetonları için yetkilendirme kodunu değiştirin

Erişim jetonuyla yetkilendirme kodunu 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ü erişim jetonu ve yenileme jetonu içeren bir JSON nesnesi döndürerek yanıt verir.

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,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "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 bu jetonu belirli bir kullanıcı hesabı adına bir Google API'ye çağrı yapmak için kullanabilirsiniz. Bunu yapmak için access_token sorgu parametresi veya Authorization HTTP üst bilgisi Bearer değeri ekleyerek API'ye yapılan bir isteğe erişim jetonunu ekleyin. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üst bilgisi tercih edilir. Çoğu durumda (örneğin, Drive Files API'yi çağırırken) Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz.

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

HTTP GET örnekleri

Authorization: Bearer HTTP üst bilgisini kullanarak drive.files uç noktasına (Drive Files API) 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

Burada, access_token sorgu dizesi parametresini kullanan kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı gösterilmektedir:

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

curl örnekleri

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

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

Alternatif olarak sorgu dizesi parametresi seçeneğinden de yararlanabilirsiniz:

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

Erişim jetonunu yenileme

Erişim jetonlarının süresi belirli aralıklarla dolar ve ilgili API isteği için geçersiz kimlik bilgileri haline gelir. Bir erişim jetonunu, jetonla ilişkili kapsamlara çevrimdışı erişim isteğinde bulunduysanız kullanıcıdan izin istemeden (kullanıcının bulunmadığı durumlar dahil) 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ğ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"
}

Verilecek yenileme jetonlarının sayısıyla ilgili sınırlar olduğunu unutmayın. Bu sınırlar istemci/kullanıcı kombinasyonu başına bir sınır ve tüm istemcilerde kullanıcı başına bir sınırdır. 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ırlarla karşılaşabilir. Bu durumda eski yenileme jetonları çalışmayı durdurur.

Jetonu iptal etme

Bazı durumlarda kullanıcı, bir uygulamaya verilen erişimi iptal etmek isteyebilir. Kullanıcı, Hesap Ayarları sayfası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 başlıklı destek belgesini inceleyin.

Ayrıca bir uygulama, kendisine verilen erişimi programlı olarak iptal edebilir. Kullanıcının abonelikten çıktığı, uygulamayı kaldırdığı veya uygulamanın gerektirdiği API kaynaklarının önemli ölçüde değiştiği durumlarda programatik iptal önemlidir. Başka bir deyişle, kaldırma süreci kapsamında, uygulamaya daha önce verilmiş olan izinlerin kaldırıldığından emin olmak için bir API isteği gönderilebilir.

Uygulamanız, bir jetonu programlı olarak iptal etmek için https://oauth2.googleapis.com/revoke adresine 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}

Bu 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 başarıyla işlenirse yanıtın HTTP durum kodu 200 olur. Hata koşullarında hata koduyla birlikte 400 HTTP durum kodu döndürülür.

Ek Okumalar

IETF'nin Mevcut En İyi Uygulaması olan Yerel Uygulamalar için OAuth 2.0, burada belirtilen en iyi uygulamaların birçoğunu oluşturmaktadır.