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 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ılardan Google Drive'larında dosya depolama izni almak için OAuth 2.0'ı kullanabilir.

Yüklenen uygulamalar ayrı cihazlara dağıtılır ve bu uygulamaların gizlilik sağlayamayacağı varsayılır. Kullanıcı uygulamadayken veya uygulama arka planda çalışırken Google API'lerine erişebilirler.

Bu yetkilendirme akışı, web sunucusu uygulamaları için kullanılan akışa benzer. Bu iki yöntem arasındaki temel fark, yüklenen 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 uygulamalar için Android veya iOS'te Google ile oturum açma özelliğini tercih edebilirsiniz. Google Sign-in istemci kitaplıkları, kimlik doğrulama ve kullanıcı yetkilendirmesini yönetir. Bu kitaplıkların uygulanması, burada açıklanan alt düzey protokolden daha basit olabilir.

Sistem tarayıcısını desteklemeyen veya sınırlı giriş özelliklerine sahip cihazlarda (ör. TV'ler, oyun konsolları, kameralar veya yazıcılar) ç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 başlıklı makalelere göz atın.

Kitaplıklar ve örnekler

Bu belgede 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ştirme

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

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

1. Open the API Library , Google API Console
2. If prompted, select a project, or create a new one.
3. Bu API Library 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.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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.

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

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ı alma

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

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

Google, yüklü 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" adlı 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, [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" karakterlerini kullanan, en az 43 ve en fazla 128 karakter uzunluğunda, yüksek entropili kriptografik rastgele bir dizedir.

Kod doğrulayıcı, değeri tahmin etmeyi pratik dışı hale getirecek kadar entropi içermelidir.

Kod doğrulamasını oluşturma

Kodlu kimlik doğrulama 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 istek gönderin

Kullanıcı yetkilendirmesi almak için https://accounts.google.com/o/oauth2/v2/auth adresindeki Google yetkilendirme sunucusuna istek gönderin. Bu uç nokta, etkin oturum aramasını yönetir, 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ı reddedilir.

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 seçenekleri için örnek yetkilendirme URL'leri gösterilmektedir.

URL'ler, redirect_uri parametresinin değeri dışında aynıdır. URL'ler, isteğe bağlı state parametresinin yanı sıra zorunlu response_type ve client_id parametrelerini de içerir. Her URL, okunaklılığı artırmak 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ş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 birlikte, verilecek erişim kapsamlarının bir özetini gösterir. Kullanıcı, uygulamanız tarafından istenen bir veya daha fazla kapsama erişim izni vermeyi kabul edebilir ya da isteği reddedebilir.

Google'ın OAuth 2.0 sunucusundan erişim izni verilip verilmediğini belirten yanıtı beklerken uygulamanızın bu aşamada herhangi bir işlem yapması gerekmez. 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 hata (error) içerir. Örneğin, error=access_denied kullanıcının isteği reddettiğini gösterir.

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

5. Adım: Yenileme ve erişim jetonları için yetkilendirme kodu değiş tokuşu yapın

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 süreli bir erişim jetonu ve 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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

Kullanıcılar, tek seferde birden fazla kapsam isteğinde bulunduğunuzda uygulamanızın istediği tüm kapsamları vermeyebilir. Uygulamanız, kullanıcı tarafından hangi kapsamların verildiğini her zaman kontrol etmeli ve ilgili özellikleri devre dışı bırakarak kapsam reddi durumlarını ele almalıdır. Daha fazla bilgi için Ayrıntılı izinleri yönetme başlıklı makaleyi inceleyin.

Kullanıcının uygulamanıza belirli bir kapsama 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 harf duyarlı dizelerin listesi olarak ifade edilir.

Örneğin, aşağıdaki örnek erişim jetonu yanıtı, kullanıcının uygulamanıza salt okunur Drive etkinliği ve Takvim etkinlikleri izinlerine erişim izni verdiğini gösterir:

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

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.

Uygulama yönlendirme yöntemleri

Uygulamalarınızı koruma

Daha fazla bilgi

IETF'nin Doğal Uygulamalar için OAuth 2.0 ile ilgili Mevcut En İyi Uygulamaları belgesinde, burada açıklanan en iyi uygulamaların çoğu yer alır.