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 taraflı, 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 üzerinden OAuth 2.0 istemci kimlik bilgilerini alın. 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. Google ile OAuth 2.0 kullanımına dair etkileşimli bir tanıtım için (kendi istemci kimlik bilgilerinizi kullanma seçeneği de dahil) OAuth 2.0 Playground ile denemeler yapın.

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

Temel adımlar

Tüm uygulamalar, OAuth 2.0 kullanarak bir Google API'sine erişirken temel bir kalıbı izler. Özetle beş adım uygularsınız:

1. OAuth 2.0 kimlik bilgilerini Google API Consoleadresinden alın.

Hem Google'ın hem de uygulamanızın bildiği 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, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, JavaScript uygulaması gizli anahtar gerektirmez, ancak bir web sunucusu uygulaması gerektirir.

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ın Google API'yi kullanarak özel verilere erişebilmesi için bu API'ye erişim izni veren bir erişim jetonu alması gerekir. Tek bir erişim jetonu, birden çok API'ye farklı derecelerde erişim verebilir. scope adlı değişken parametresi, erişim jetonunun izin verdiği kaynak ve işlem grubunu kontrol eder. Uygulamanız, erişim jetonu isteği sırasında scope parametresinde bir veya daha fazla değer gönderir.

Bu isteği göndermenin birkaç yolu vardır ve bunlar, oluşturduğunuz uygulamanın türüne göre değişiklik gösterir. Örneğin, bir JavaScript uygulaması Google'a tarayıcı yönlendirmesi kullanarak erişim jetonu isteyebilir. Tarayıcısı olmayan bir cihaza yüklenen bir uygulama ise web hizmeti isteklerini kullanır.

Bazı isteklerde, kullanıcının Google hesabıyla giriş yaptığı bir kimlik doğrulama adımı gerekir. Giriş yaptı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 listesini gönderir. Kullanıcı izin vermezse sunucu bir hata döndürür.

Kapsamları önceden değil, erişim gerektiğinde aşamalı olarak istemek genellikle en iyi uygulamadır. Örneğin, bir etkinliğin takvime kaydedilmesini desteklemek isteyen bir uygulama, kullanıcı "Takvime Ekle" düğmesine basana kadar Google Takvim'e erişim isteğinde bulunmamalıdır (Artımlı yetkilendirme bölümüne bakın).

3. Kullanıcının verdiği erişim kapsamlarını inceleme.

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. Uygulamanızın ilgili API'ye erişimi olmadan çalışamayan 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ı öğrenmek üzere her bir Google API'sinin belgelerine bakın. Bir API birden fazla kapsam dize değerini tek bir erişim kapsamıyla eşleyerek istekte izin verilen tüm değerler için aynı kapsam dizesini döndürebilir. Örnek: Bir uygulama, bir kullanıcı https://www.google.com/m8/feeds/ kapsamını yetkilendirme istediğinde Google People API https://www.googleapis.com/auth/contacts kapsamını döndürebilir; Google People API yöntemi people.updateContact için https://www.googleapis.com/auth/contacts kapsamı gerekir.

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

Bir uygulama erişim jetonu aldıktan sonra, jetonu HTTP Yetkilendirme isteği başlığında bir Google API'sine 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 önermiyoruz. Ayrıca, gereksiz URI parametre adları oluşturmaktan kaçınmak da iyi bir REST uygulamasıdır.

Erişim jetonları yalnızca jeton isteğinin scope bölümünde açıklanan işlem ve kaynak grubu için geçerlidir. Örneğin, Google Calendar API için bir erişim jetonu verilirse bu, Google Contacts API'ye erişim izni vermez. Ancak, benzer işlemler için bu erişim jetonunu Google Calendar API'ye birden çok 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 geçerlilik süresinden sonra bir Google API'ye erişmesi gerekirse yenileme jetonu alabilir. Yenileme jetonu, uygulamanızın yeni erişim jetonları elde etmesini sağlar.

Senaryolar

Web sunucusu uygulamaları

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

Yetkilendirme sırası, uygulamanız bir tarayıcıyı bir Google URL'sine 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ı izni konuları Google tarafından yürütülür. Bunun sonucunda, uygulama tarafından erişim jetonu ve yenileme jetonuyla değiştirilebilecek bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanılmak üzere depolamalı ve erişim jetonunu bir Google API'sine erişmek için 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 Sunucusu'na jeton isteği gönderir, yetkilendirme kodu alır, kodu bir jetonla değiştirir ve bir Google API uç noktasını çağırmak için bu jetonu kullanır.

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

Yüklü uygulamalar

Google OAuth 2.0 uç noktası bilgisayarlar, mobil cihazlar ve tabletler gibi cihazlara yüklenen uygulamaları destekler. Google API Console üzerinden istemci kimliği oluşturduğunuzda, bunun Yüklü uygulama olduğunu belirtin ve ardından uygulama türü olarak Android, Chrome uygulaması, iOS, Evrensel Windows Platformu (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ştirdiğiniz bir istemci gizli anahtarı verilir. (Bu bağlamda, istemci gizli anahtarı açık bir şekilde gizli anahtar olarak değerlendirilmez.)

Yetkilendirme sırası, uygulamanız bir tarayıcıyı bir Google URL'sine 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ı izni konuları Google tarafından yürütülür. Bunun sonucunda, uygulama tarafından erişim jetonu ve yenileme jetonuyla değiştirilebilecek bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanılmak üzere depolamalı ve erişim jetonunu bir Google API'sine erişmek için 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 Sunucusu'na jeton isteği gönderir, yetkilendirme kodu alır, kodu bir jetonla değiştirir ve bir Google API uç noktasını çağırmak için bu jetonu kullanır.

Ayrıntılar için Yüklü Uygulamalarda OAuth 2.0'ı Kullanma başlıklı makaleye göz atın.

İ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. URL, istenen erişim türünü belirten sorgu parametrelerini içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni konuları Google tarafından yürütülür.

Bunun sonucunda, istemcinin bunu Google API isteğine eklemeden önce doğrulaması gereken bir erişim jetonu elde edilir. Jetonun süresi dolduğunda uygulama bu işlemi tekrarlar.

JS uygulamanız Google Yetkilendirme Sunucusu'na bir jeton isteği gönderir, bir jeton alır, jetonu doğrular ve bir Google API uç noktasını çağırmak için bu 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 Google URL'sine yetkilendirme kodu için web hizmeti isteğinde bulunmasıyla başlar. Yanıt, bir URL ve uygulamanın kullanıcıya gösterdiği bir kod da dahil olmak üzere çeşitli parametreler içerir.

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 uygulama belirli bir aralıkta bir Google URL'sini yoklar. Kullanıcı erişimi onayladıktan sonra, Google sunucusundan gelen yanıt bir erişim jetonu ve yenileme jetonu içerir. Uygulama, yenileme jetonunu gelecekte kullanılmak üzere depolamalı ve erişim jetonunu bir Google API'sine erişmek için 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 cihazda giriş yapar.

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 hareket edebilir. Böyle durumlarda uygulamanızın kendi kimliğini API'ye kanıtlaması gerekir ancak kullanıcının izni gerekmez. Benzer şekilde, kurumsal senaryolarda uygulamanız bazı kaynaklara yetki verilmiş erişim isteğinde bulunabilir.

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

Bir hizmet hesabının Google API Consoleüzerinden aldığınız kimlik bilgilerinde, oluşturulmuş benzersiz bir e-posta adresi, bir istemci kimliği ve en az bir genel/özel anahtar çifti bulunur. İmzalanmış 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 isteğini Google OAuth 2.0 Yetkilendirme Sunucusuna gönderir ve bu sunucu, bir erişim jetonu döndürür. Uygulama, bu jetonu Google API'lerine erişmek için kullanır. Jetonun süresi dolduğunda uygulama bu işlemi tekrarlar.

Sunucu uygulamanız, Google Yetkilendirme Sunucusu'ndan jeton istemek için bir JWT kullanır, daha sonra bu jetonu bir Google API uç noktası çağırmak için kullanır. Hiçbir son kullanıcı dahil değildir.

Ayrıntılar için hizmet hesabı belgelerini 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 Güvenlik Jetonu Hizmet API'si 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ılı bilgi için API belgelerine bakın.

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

Yenileme jetonu geçerlilik süresi

Verilen yenileme jetonunun artık çalışmayabileceğini öngörmek için kodunuzu yazmanız gerekir. Yenileme jetonunun çalışmamasının nedeni aşağıdakilerden biri olabilir:

OAuth izin ekranı harici bir kullanıcı türü için yapılandırılmış ve yayınlanma durumu "Test ediliyor" olarak belirlenmiş bir Google Cloud Platform projesi için yalnızca ad, e-posta adresi ve kullanıcı profili alt kümesi ( userinfo.email, userinfo.profile, openid kapsamları veya OpenID Connect eşdeğerleri aracılığıyla) yalnızca OAuth kapsamı 7 gün içinde sona erecek 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. Sınıra ulaşılırsa yeni bir yenileme jetonu oluşturmak, en eski yenileme jetonunu herhangi bir uyarı verilmeden otomatik olarak geçersiz kılar. 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. Normal kullanıcıların çoğu bu sınırı aşmaz. Ancak, bir uygulamayı test etmek için kullanılan geliştirici hesabı bu sınırı aşmayabilir.

Birden fazla programı, makineyi veya cihazı yetkilendirmeniz gerekiyorsa geçici çözümlerden biri, 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 bazılarını istemcilerden bazılarını yetkilendirmek için kullanabilirsiniz.

Google Cloud Platform (GCP) kuruluşları için oturum denetimi politikalarını ele alma

GCP kuruluşlarının yöneticileri, GCP kaynaklarına eriştiklerinde kullanıcıların Google Cloud oturum denetimi özelliğini kullanarak sık sık yeniden kimlik doğrulaması yapmasını zorunlu kılabilir. Bu politika Google Cloud Console'a, Google Cloud SDK'ya (gcloud KSA olarak da bilinir) ve Cloud Platform kapsamının kullanılmasını gerektiren tüm üçüncü taraf OAuth uygulamalarına erişimi etkiler. Kullanıcının oturum denetimi politikası varsa oturum süresi sona erdiğinde API çağrılarınız, yenileme jetonunun iptal edilmesi durumunda yaşanacak gibi bir hata verir. Çağrı, invalid_grant hata türüyle başarısız olur. error_subtype alanı, iptal edilen jeton ile bir oturum kontrolü politikası nedeniyle hatayı birbirinden ayırt etmek için kullanılabilir (örneğin, "error_subtype": "invalid_rapt"). Oturum süresi 24 saat arasında bir şekilde yeniden başlatılabileceğinden, bu senaryoda oturum sayısı çok sınırlı olabilir (1 saat arasında).

Aynı şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya kullanılması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 müşteri bu 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 yönetici odaklı bu yardım makalesini inceleyin.

İstemci kitaplıkları

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