Google API'lerine Erişmek için OAuth 2.0'ı Kullanma

Google API'leri, kimlik doğrulama ve yetkilendirme için OAuth 2.0 protokolünü kullanır. Google; web sunucusu, istemci tarafı, yüklü ve sınırlı girişli cihaz uygulamaları gibi yaygın OAuth 2.0 senaryolarını destekler.

Başlamak için Google API Console adresinden OAuth 2.0 istemci kimlik bilgilerini alın. Ardından istemci uygulamanız Google Yetkilendirme Sunucusundan bir erişim jetonu ister, yanıttaki bir jetonu alır ve jetonu, erişmek istediğiniz Google API'sine gönderir. OAuth 2.0'ı Google ile kullanma etkileşimine dair bir tanıtım (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) için OAuth 2.0 Playground'u deneyin.

Bu sayfada, Google'ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bir bakış ve daha ayrıntılı içeriğe bağlantılar yer almaktadır. Kimlik doğrulama için OAuth 2.0'ı kullanma hakkında ayrıntılı bilgi için OpenID Connect'e bakın.

Temel adımlar

OAuth 2.0 kullanarak Google API'ye erişirken tüm uygulamalar temel bir kalıp izler. Özet olarak beş adımı uygularsınız:

1. Google API Consoleadresinden OAuth 2.0 kimlik bilgilerini edinin.

Hem Google hem de uygulamanız tarafından bilinen istemci kimliği ve istemci gizli anahtarı gibi OAuth 2.0 kimlik bilgilerini almak için Google API Console sayfasını ziyaret edin. Değer grubu, geliştirdiğiniz uygulamanın türüne göre değişiklik gösterir. Örneğin, bir JavaScript uygulaması gizli anahtar gerektirmez ancak bir web sunucusu uygulaması bunu gerektirir.

2. Google Yetkilendirme Sunucusundan bir erişim jetonu alın.

Uygulamanızın bir Google API'yi kullanarak özel verilere erişebilmesi için uygulamanızın API'ye erişim veren bir erişim jetonu alması gerekir. Tek bir erişim jetonu, birden fazla API'ye farklı derecelerde erişim sağlayabilir. scope adlı değişken parametresi, bir erişim jetonunun izin verdiği kaynak ve işlem grubunu kontrol eder. Erişim jetonu isteği sırasında uygulamanız, scope parametresinde bir veya daha fazla değer gönderir.

Bu isteği göndermenin birkaç yolu vardır ve geliştirmekte olduğunuz uygulamanın türüne göre değişiklik gösterir. Örneğin, bir JavaScript uygulaması Google'a tarayıcı yönlendirmesini kullanarak erişim jetonu isteyebilirken, tarayıcısında yüklü olmayan bir uygulama web hizmeti isteklerini kullanabilir.

Bazı istekler, kullanıcının Google hesabıyla giriş yaptığı bir kimlik doğrulama adımını gerektirir. Giriş yaptıktan sonra, kullanıcıya uygulamanızın istediği bir veya daha fazla izin vermek isteyip istemediği sorulur. Bu sürece kullanıcı izni adı verilir.

Kullanıcı en az bir izin verirse Google Yetkilendirme Sunucusu, uygulamanıza bir erişim jetonu (veya uygulamanızın erişim jetonu almak için kullanabileceği bir yetkilendirme kodu) ve bu jetonun verdiği erişim kapsamlarının listesini gönderir. Kullanıcı izin vermezse sunucu bir hata döndürür.

Genellikle önceden erişim yerine erişim gerekli olduğunda kapsam artışı istemek iyi bir uygulamadır. Örneğin, bir etkinliğin bir takvime kaydedilmesini desteklemek isteyen uygulama, kullanıcı "Takvime Ekle" düğmesine basana kadar Google Takvim'den erişim isteğinde bulunmamalıdır. Artımlı yetkilendirme sayfasına göz atın.

3. Kullanıcı tarafından verilen erişim kapsamlarını inceleyin.

Erişim jetonu yanıtına dahil edilen kapsamları, ilgili bir Google API'sine erişime bağlı olarak uygulamanızın özelliklerine ve işlevlerine erişmek için gereken kapsamlarla karşılaştırın. Uygulamanızın, ilgili API'ye erişim olmadan çalışamayan özelliklerini devre dışı bırakın.

Kullanıcı istenen tüm kapsamları vermiş olsa bile isteğinize dahil edilen kapsam, yanıtınızda yer alan kapsamla eşleşmeyebilir. Erişim için gerekli olan kapsamlar hakkında her Google API'nin dokümanlarına bakın. Bir API, birden fazla kapsam dizesi değerini tek bir erişim kapsamıyla eşleştirerek istekte izin verilen tüm değerler için aynı kapsam dizesini döndürebilir. Örnek: Google People API, bir uygulama https://www.google.com/m8/feeds/ kapsamının onaylanmasını istediğinde https://www.googleapis.com/auth/contacts kapsamını döndürebilir; Google People API yöntemi people.updateContact için izin verilen bir https://www.googleapis.com/auth/contacts kapsamı gerekir.

4. Erişim jetonunu API'ye gönderin.

Bir uygulama bir erişim jetonu aldıktan sonra, jetonu HTTP Yetkilendirme isteği başlığında bir Google API'ye gönderir. Jetonları URI sorgu dizesi parametreleri olarak göndermek mümkündür ancak URI parametreleri tamamen güvenli olmayan günlük dosyalarında bulunabileceğinden bunu önermeyiz. Ayrıca, gereksiz URI parametre adları oluşturmaktan kaçınmak için REST'te kullanılması önerilir.

Erişim jetonları yalnızca jeton isteğinin scope bölümünde açıklanan işlem ve kaynak kümesi için geçerlidir. Örneğin, Google Calendar API için bir erişim jetonu verildiyse erişim jetonu, Google Contacts API için erişim izni vermez. Ancak, erişim jetonlarını benzer işlemler için Google Calendar API'ye birden fazla kez gönderebilirsiniz.

5. Gerekirse erişim jetonunu yenileyin.

Erişim jetonlarının kullanım ömrü sınırlıdır. Uygulamanız, tek bir erişim jetonunun kullanım ömrü dışında bir Google API'sine erişmesi gerekiyorsa yenileme jetonu alabilir. Yenileme jetonu, uygulamanızın yeni erişim jetonları elde etmesine olanak tanır.

Senaryolar

Web sunucusu uygulamaları

Google OAuth 2.0 uç noktası; PHP, Java, Python, Wild ve ASP.NET gibi dilleri ve çerçeveleri kullanan web sunucusu uygulamalarını destekler.

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'ye yönlendirdiğinde başlar. URL, istenen erişim türünü belirten sorgu parametrelerini içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı rızası Google tarafından işlenir. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonu ile değiştirebileceği bir yetkilendirme kodu oluşturulur.

Uygulama, yenileme jetonunu ileride kullanılmak üzere depolamalı ve bir Google API'sine erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Uygulamanız, Google Yetkilendirme Sunucusuna bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jeton için değiştirir ve bir Google API uç noktasını çağırmak için jetonu kullanır.

Ayrıntılar için Web Sunucusu Uygulamaları için OAuth 2.0'ı Kullanma başlıklı makaleye bakın.

Yüklü uygulamalar

Google OAuth 2.0 uç noktası; bilgisayarlar, mobil cihazlar ve tabletler gibi cihazlarda yüklü uygulamaları destekler. Google API Console üzerinden bir istemci kimliği oluşturduğunuzda, bu uygulamanın bir Yüklü uygulama olduğunu belirtin ve ardından uygulama türü olarak Android, Chrome uygulaması, iOS, Universal Windows Platform (UWP) veya Masaüstü uygulamasını seçin.

İşlem, bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştirdiğiniz bir istemci gizli anahtarının sağlanmasıyla sonuçlanır. (Bu bağlamda istemci gizli anahtarı açıkça bir sır olarak ele alınmaz.)

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'ye yönlendirdiğinde başlar. URL, istenen erişim türünü belirten sorgu parametrelerini içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı rızası Google tarafından işlenir. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonu ile değiştirebileceği bir yetkilendirme kodu oluşturulur.

Uygulama, yenileme jetonunu ileride kullanılmak üzere depolamalı ve bir Google API'sine erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Uygulamanız, Google Yetkilendirme Sunucusuna bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jeton için değiştirir ve bir Google API uç noktasını çağırmak için jetonu kullanır.

Ayrıntılar için Yüklü Uygulamalar İçin OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

İstemci tarafı (JavaScript) uygulamalar

Google OAuth 2.0 uç noktası, tarayıcıda çalışan JavaScript uygulamalarını destekler.

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'ye yönlendirdiğinde başlar. URL, istenen erişim türünü belirten sorgu parametrelerini içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı rızası Google tarafından işlenir.

Sonuç olarak istemcinin bir Google API isteğine dahil etmeden önce doğrulaması gereken bir erişim jetonu elde edilir. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.

JS uygulamanız Google Yetkilendirme Sunucusuna bir jeton isteği gönderir, bir jeton alır, jetonu doğrular ve bir Google API uç noktasını çağırmak için jetonu kullanır.

Ayrıntılar için İstemci Tarafı Uygulamalar için OAuth 2.0'ı Kullanma başlıklı makaleye bakın.

Sınırlı girişli cihazlarda uygulama sayısı

Google OAuth 2.0 uç noktası; oyun konsolları, video kameralar ve yazıcılar gibi sınırlı girişli cihazlarda çalışan uygulamaları destekler.

Yetkilendirme sırası, uygulamanın bir yetkilendirme kodu için Google URL'sine web hizmeti isteğinde bulunmasıyla başlar. Yanıtta, URL ve uygulamanın kullanıcıya gösterdiği kod dahil olmak üzere birkaç parametre bulunur.

Kullanıcı, URL'yi ve kodu cihazdan alır, ardından daha zengin giriş özelliklerine sahip ayrı bir cihaza veya bilgisayara geçer. Kullanıcı bir tarayıcıyı başlatır, belirtilen URL'ye gider, giriş yapar ve kodu girer.

Bu arada da uygulama, belirtilen aralıklarla Google URL'si anketi yapar. Kullanıcı erişimi onayladıktan sonra, Google sunucusundan gelen yanıt bir erişim jetonu ve yenileme jetonu içerir. Uygulama, yenileme jetonunu ileride kullanılmak üzere saklamalı ve bir Google API'sine erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Kullanıcı, tarayıcısı olan ayrı bir cihazdan giriş yaptığında

Ayrıntılar için Cihazlar için OAuth 2.0'ı kullanma başlıklı makaleye bakın.

Hizmet hesapları

Prediction API ve Google Cloud Storage gibi Google API'leri, kullanıcı bilgilerine erişmeden uygulamanız adına işlem yapabilir. Bu gibi durumlarda, uygulamanızın API'de kendi kimliğini doğrulaması gerekir ancak kullanıcı izni gerekmez. Benzer şekilde, kurumsal senaryolarda uygulamanız, bazı kaynaklar için erişim yetkisi isteyebilir.

Bu tür sunucular arası etkileşimler için ayrı bir son kullanıcı yerine uygulamanıza ait bir hesap olan hizmet hesabını kullanmanız gerekir. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır ve kullanıcı rızası gerekmez. (Hizmet hesabı harici senaryolarda, uygulamanız son kullanıcılar adına Google API'lerini çağırır ve bazen kullanıcı izni gerekir.)

Google API Console'dan edindiğiniz bir hizmet hesabının kimlik bilgileri; benzersiz bir oluşturulan e-posta adresi, istemci kimliği ve en az bir ortak/özel anahtar çifti içerir. İmzalı bir JWT oluşturmak ve uygun biçimde bir erişim jetonu isteği oluşturmak için istemci kimliğini ve bir özel anahtarı kullanırsınız. Ardından, uygulamanız jeton jetonunu Google OAuth 2.0 Yetkilendirme Sunucusu'na gönderir ve bu sunucu bir erişim jetonu döndürür. Uygulama, jetonu bir Google API'sine erişmek için kullanır. Belirtecin süresi dolduğunda uygulama, işlemi tekrarlar.

Sunucu uygulamanız, Google Yetkilendirme Sunucusundan bir jeton istemek için bir JWT kullanır, ardından bir Google API uç noktasını çağırmak için jetonu kullanır. Söz konusu son kullanıcı dahil değildir.

Ayrıntılar için hizmet hesabı dokümanlarına bakın.

Jeton boyutu

Jetonların boyutu, aşağıdaki sınırlara kadar değişiklik gösterebilir:

  • Yetkilendirme kodları: 256 bayt
  • Erişim jetonları: 2.048 bayt
  • Yenileme jetonları: 512 bayt

Google Cloud'un Security Token Service API tarafından döndürülen erişim jetonları, Google API OAuth 2.0 erişim jetonlarına benzer şekilde yapılandırılmıştır, ancak farklı jeton boyutu sınırlarına sahiptir. Ayrıntılar için API dokümanlarına göz atın.

Google, bu sınırlar içinde jeton boyutunu değiştirme hakkını saklı tutar ve uygulamanızın değişken jeton boyutlarını buna uygun olarak desteklemesi gerekir.

Yenileme jetonunun geçerlilik süresi

Verilen bir yenileme jetonunun çalışmama olasılığını tahmin etmek için kodunuzu yazmanız gerekir. Yenileme jetonu, aşağıdakilerden biri nedeniyle çalışmayı durdurabilir:

  • Kullanıcı, uygulamanızın erişimini iptal etti.
  • Yenileme jetonu altı aydır kullanılmamıştır.
  • Kullanıcı şifreleri değiştirdi ve yenileme jetonu Gmail kapsamlarını içeriyor.
  • Kullanıcı hesabı, verilen (canlı) yenileme jetonlarının maksimum sayısını aştı.
  • Kullanıcı, oturum denetimi politikalarının geçerli olduğu bir Google Cloud Platform kuruluşuna aittir.

Harici kullanıcı türü için yapılandırılmış OAuth izin ekranı ve yayınlanma durumu "Test" olan bir Google Cloud Platform projesine 7 gün içinde yenileme jetonu verilir.

Şu anda OAuth 2.0 istemci kimliği başına Google Hesabı başına 100 yenileme jetonu sınırı vardır. Sınıra ulaşıldığında, yeni yenileme jetonu oluşturma işlemi en eski yenileme jetonunu otomatik olarak geçersiz kılar. Bu sınır, hizmet hesapları için geçerli değildir.

Ayrıca, bir kullanıcı veya hizmet hesabının tüm istemcilerde sahip olabileceği toplam yenileme jetonu sayısıyla ilgili daha büyük bir sınır da vardır. Normal kullanıcıların çoğu bu sınırı aşmaz, ancak uygulamaları test etmek için kullanılan geliştiricilerin hesapları bundan etkilenebilir.

Birden fazla program, makine veya cihazı yetkilendirmeniz gerekiyorsa geçici bir çözüm, Google Hesabı başına yetkilendirdiğiniz istemci sayısını 15 veya 20 ile sınırlandırmaktır. Google Workspace yöneticisiyseniz yönetici ayrıcalıklarına sahip ek kullanıcılar oluşturabilir ve bazı müşterileri yetkilendirmek için bunları kullanabilirsiniz.

Google Cloud Platform (GCP) kuruluşları için oturum denetimi politikalarıyla ilgilenme

GCP kuruluşlarının yöneticileri, GCP kaynaklarına erişirken kullanıcıların Google Cloud oturum denetimi özelliğini kullanarak sık sık yeniden kimlik doğrulaması gerçekleştirmesini zorunlu kılabilir. Bu politika Google Cloud Console, Google Cloud SDK (gcloud KSA olarak da bilinir) ve Cloud Platform kapsamının kullanılmasını gerektiren üçüncü taraf OAuth uygulamalarına erişimi etkiler. Kullanıcının geçerli bir oturum denetimi politikası varsa oturum süresinin sona ermesi halinde API çağrılarınız, yenileme jetonu iptal edildiğinde yaşanacaklara benzer şekilde hata verir. Çağrı, invalid_token hata türüyle başarısız olur. İptal hatasını ve oturum kontrol politikası nedeniyle oluşan hataları ayırt etmek için alt hata türü kullanılabilir. Oturum süreleri çok sınırlı olabileceğinden (1 saat ile 24 saat arasında), bir kimlik doğrulama oturumu yeniden başlatılarak bu senaryo gerektiği gibi ele alınmalıdır.

Aynı şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya kullanımını teşvik etmemelisiniz. Kullanıcı kimlik bilgileri uzun süreli iş veya işlemler için bir sunucuya dağıtılırsa ve müşteri bu tür kullanıcılara oturum denetimi politikaları uygularsa oturum süresi sona erdiğinde kullanıcının kimliğini yeniden doğrulamak mümkün olmayacağından sunucu uygulaması başarısız olur.

Müşterilerinizin bu özelliği dağıtmasına nasıl yardımcı olabileceğiniz hakkında daha fazla bilgi edinmek için bu yönetici odaklı yardım makalesine bakın.

İstemci kitaplıkları

Aşağıdaki istemci kitaplıkları, popüler çerçevelerle entegre olarak OAuth 2.0'ı uygulamayı kolaylaştırır. Zaman içinde kitaplıklara daha fazla özellik eklenecektir.