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ü uygulamalar 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 edinin. Ardından istemci uygulamanız Google Yetkilendirme Sunucusu'ndan erişim jetonu ister, yanıttan bir jeton çıkarır ve jetonu erişmek istediğiniz Google API'ye gönderir. OAuth 2.0'ı Google ile kullanmayla ilgili etkileşimli bir gösterim (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ış sunulmakta ve daha ayrıntılı içeriklerin bağlantıları sağlanmaktadır. Kimlik doğrulama için OAuth 2.0'ı kullanma hakkında ayrıntılı bilgi için OpenID Connect başlıklı makaleyi inceleyin.

Temel adımlar

Tüm uygulamalar, OAuth 2.0'ı kullanarak bir Google API'sine erişirken 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 edinmek için Google API Console adresini ziyaret edin. Değer grubu, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, JavaScript uygulamaları için gizli anahtar gerekmez ancak web sunucusu uygulamaları için gerekir.

Uygulamanızın çalışacağı platforma uygun bir OAuth istemcisi oluşturmanız gerekir. Örneğin:

2. Google Yetkilendirme Sunucusu'ndan erişim jetonu alın.

Uygulamanız, Google API'sini kullanarak gizli verilere erişebilmek için söz konusu API'ye erişim izni veren bir erişim jetonu almalıdır. Tek bir erişim jetonu, birden fazla API'ye farklı erişim düzeyleri verebilir. scope adlı değişken parametre, 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 bu yollar, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, bir JavaScript uygulaması Google'a yönlendiren bir tarayıcı kullanarak erişim jetonu isteyebilir. Tarayıcı bulunmayan bir cihaza yüklenen bir uygulama ise web hizmeti isteklerini kullanır.

Bazı istekler, kullanıcının Google Hesabı ile giriş yaptığı bir kimlik doğrulama adımı gerektirir. Oturum açtıktan sonra kullanıcıya, uygulamanızın istediği bir veya daha fazla izni vermek isteyip istemediği sorulur. Bu sürece kullanıcı izni denir.

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 jeton tarafından verilen erişim kapsamlarının bir listesini gönderir. Kullanıcı izin vermezse sunucu hata döndürür.

Genellikle, erişim gerektiğinde kapsamları kademeli olarak istemek, önceden istemekten daha iyi bir uygulamadır. Örneğin, bir etkinliği takvime kaydetmeyi desteklemek isteyen bir uygulama, kullanıcı "Takvime ekle" düğmesine basana kadar Google Takvim erişimi istememelidir. Artımlı yetkilendirme bölümüne bakın.

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

Erişim jetonu yanıtında yer alan 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. İlgili API'ye erişimi olmadan çalışamayan uygulamanızın tüm özelliklerini devre dışı bırakın.

Kullanıcı istenen tüm kapsamları vermiş olsa bile isteğinizde yer alan kapsam, yanıtınızda yer alan kapsamla eşleşmeyebilir. Erişim için gereken kapsamlar hakkında bilgi edinmek üzere her Google API'sinin dokümanlarına bakın. API, birden çok kapsam dizesi değerini tek bir erişim kapsamıyla eşleyebilir ve istekte izin verilen tüm değerler için aynı kapsam dizesini döndürebilir. Örnek: Google People API, bir uygulama kullanıcıdan https://www.google.com/m8/feeds/ kapsamı için yetkilendirme isteğinde bulunduğunda https://www.googleapis.com/auth/contacts kapsamı döndürebilir; Google People API yöntemi people.updateContact için ise https://www.googleapis.com/auth/contacts kapsamının verilmesi gerekir.

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

Uygulama, erişim jetonunu aldıktan sonra jetonu bir Google API'sine HTTP Yetkilendirme istek üst bilgisinde 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ına girebileceğinden bunu önermeyiz. Ayrıca, gereksiz URI parametre adları oluşturmamak da iyi bir REST uygulamasıdır.

Erişim jetonları yalnızca jeton isteğinin scope bölümünde açıklanan işlemler ve kaynaklar için geçerlidir. Örneğin, Google Takvim API için verilen bir erişim jetonu, Google Kişiler API'ye erişim izni vermez. Ancak bu erişim jetonunu, benzer işlemler için Google Takvim API'ye birden çok kez gönderebilirsiniz.

5. Gerekirse erişim jetonunu yenileyin.

Erişim jetonlarının geçerlilik süreleri sınırlıdır. Uygulamanızın tek bir erişim jetonunun ömründen daha uzun süre boyunca bir Google API'sine erişmesi gerekiyorsa yenileme jetonu alabilir. Yenileme jetonu, uygulamanızın yeni erişim jetonları almasına olanak tanır.

Senaryolar

Web sunucusu uygulamaları

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

Yetkilendirme sırası, uygulamanız bir tarayıcıyı bir Google URL'sine yönlendirdiğinde başlar. Bu URL, istenen erişim türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından yönetilir. Sonuç olarak, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduktan sonra uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Uygulamanız Google Yetkilendirme Sunucusu'na bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jetonla 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ı makaleyi inceleyin.

Yüklü uygulamalar

Google OAuth 2.0 uç noktası; bilgisayar, mobil cihaz ve tablet gibi cihazlara yüklenen uygulamaları destekler. Google API Console üzerinden istemci kimliği oluşturduğunuzda, bunun yüklü bir 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.

Bu işlem sonucunda bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştireceğiniz bir istemci sırrı elde edersiniz. (Bu bağlamda, istemci gizli anahtarı gizli olarak kabul edilmez.)

Yetkilendirme sırası, uygulamanız bir tarayıcıyı bir Google URL'sine yönlendirdiğinde başlar. Bu URL, istenen erişim türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından yönetilir. Sonuç olarak, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduktan sonra uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Uygulamanız Google Yetkilendirme Sunucusu'na bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jetonla 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 iç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ı bir Google URL'sine yönlendirdiğinde başlar. Bu URL, istenen erişim türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından yönetilir.

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

JS uygulamanız Google Yetkilendirme Sunucusu'na bir jeton isteği gönderir, 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 cihazlardaki uygulamalar

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ği göndermesiyle başlar. Yanıt, URL ve uygulamanın kullanıcıya gösterdiği kod da dahil olmak üzere çeşitli parametreler içerir.

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

Bu sırada uygulama, belirli bir aralıkta bir Google URL'sini sorgulamaya devam eder. Kullanıcı erişimi onayladıktan sonra Google sunucusundan gelen yanıtta bir erişim jetonu ve yenileme jetonu bulunur. Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye erişmek için erişim jetonunu kullanmalıdır. Erişim jetonunun süresi dolduktan sonra uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.

Kullanıcı, tarayıcı bulunan ayrı bir cihazda oturum açar.

Ayrıntılar için Cihazlar için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

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 durumlarda uygulamanızın API'ye kendi kimliğini kanıtlaması gerekir ancak kullanıcı izni gerekmez. Benzer şekilde, kurumsal senaryolarda uygulamanız bazı kaynaklara atanmış erişim isteyebilir.

Bu tür sunucudan sunucuya etkileşimler için bir hizmet hesabına ihtiyacınız vardır. Bu hesap, bireysel bir son kullanıcıya değil, uygulamanıza aittir. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır ve kullanıcı izni gerekmez. (Hizmet hesabı olmayan senaryolarda, uygulamanız son kullanıcılar adına Google API'lerini çağırır ve bazen kullanıcı izni gerekir.)

Google API Console'den aldığınız hizmet hesabının kimlik bilgileri, benzersiz bir e-posta adresi, istemci kimliği ve en az bir herkese açık/özel anahtar çifti içerir. İmzalı bir JWT oluşturmak ve uygun biçimde bir erişim anahtarı isteği oluşturmak için müşteri kimliğini ve bir özel anahtarı kullanırsınız. Ardından uygulamanız, jeton isteğini Google OAuth 2.0 Yetkilendirme Sunucusu'na gönderir. Bu sunucu, erişim jetonu döndürür. Uygulama, bir Google API'sine erişmek için jetonu kullanır. Jetonun geçerlilik süresi dolduğunda uygulama işlemi tekrarlar.

Sunucu uygulamanız, Google Yetkilendirme Sunucusu'ndan jeton istemek için JWT kullanır, ardından jetonu bir Google API uç noktasını çağırmak için kullanır. Son kullanıcılar bu işleme dahil değildir.

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

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ırlamalarına sahiptir. Ayrıntılar için API belgelerine bakın.

Google, jeton boyutunu bu sınırlar dahilinde değiştirme hakkını saklı tutar ve uygulamanız değişken jeton boyutlarını buna göre desteklemelidir.

Yenileme jetonunun son kullanma tarihi

Kodunuzu, verilen yenileme jetonunun artık çalışmayabileceği ihtimalini öngörecek şekilde yazmanız gerekir. Yenileme jetonunun çalışmayı durdurmasının nedeni aşağıdakilerden biri olabilir:

Harici bir kullanıcı türü için yapılandırılmış bir OAuth kullanıcı rızası ekranına ve "Test Ediliyor" yayın durumu olan bir Google Cloud Platform projesine, istenen tek OAuth kapsamları ad, e-posta adresi ve kullanıcı profilinin alt kümesi ( userinfo.email, userinfo.profile, openid kapsamları veya OpenID Connect eşdeğerleriyle) olmadığı sürece 7 gün içinde süresi dolan bir 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. Bu sınıra ulaşıldığında, yeni bir yenileme anahtarı oluşturma işlemi en eski yenileme anahtarını herhangi bir uyarı olmaksızın geçersiz hale getirir. Bu sınır hizmet hesapları için geçerli değildir.

Ayrıca, bir kullanıcı hesabının 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 vardır. Çoğu normal kullanıcı bu sınırı aşmaz ancak bir uygulamayı test etmek için kullanılan geliştirici hesabı bu sınırı aşabilir.

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

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

GCP kuruluşlarının yöneticileri, Google Cloud oturum denetimi özelliğini kullanarak kullanıcıların GCP kaynaklarına erişirken sık sık yeniden kimlik doğrulaması yapmasını zorunlu tutabilir. Bu politika, Google Cloud Console'a, Google Cloud SDK'sına (gcloud CLI olarak da bilinir) ve Cloud Platform kapsamını gerektiren tüm üçüncü taraf OAuth uygulamalarına erişimi etkiler. Bir kullanıcının oturum denetimi politikası varsa oturum süresi sona erdiğinde API çağrılarınız, yenileme jetonu iptal edildiğinde ortaya çıkacak hataya benzer bir hata verir. Çağrı, invalid_grant hata türüyle başarısız olur. error_subtype alanı, iptal edilen jeton ile oturum denetimi politikasından (ör. "error_subtype": "invalid_rapt") kaynaklanan bir hatayı ayırt etmek için kullanılabilir. Oturum süreleri çok sınırlı olabileceğinden (1 ila 24 saat arasında) bu senaryo, kimlik doğrulama oturumu yeniden başlatılarak sorunsuz bir şekilde ele alınmalıdır.

Benzer şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya bu bilgilerin kullanımını teşvik etmemelisiniz. Kullanıcı kimlik bilgileri, uzun süre çalışan işler veya işlemler için bir sunucuya dağıtılırsa ve bir 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ğrulamanın bir yolu olmadığından sunucu uygulaması başarısız olur.

Müşterilerinizin bu özelliği kullanıma sunmasına nasıl yardımcı olabileceğiniz hakkında daha fazla bilgi için bu yöneticilere yönelik yardım makalesine göz atın.

İstemci kitaplıkları

Aşağıdaki istemci kitaplıkları popüler çerçevelerle entegre olduğundan OAuth 2.0'ı uygulamak daha kolaydır. Zaman içinde kitaplıklara daha fazla özellik eklenecektir.