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 kaynağından 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ı (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) hakkında etkileşimli bir tanıtım için OAuth 2.0 Playground ile denemeler yapın.

Bu sayfada, Google'ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bakış ve daha ayrıntılı içeriklere 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 sayfasına göz atın.

Temel adımlar

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

1. OAuth 2.0 kimlik bilgilerini Google API Consoleadresinden edinin.

Hem Google'ın hem de uygulamanızın 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, 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ı bunu gerektirir.

Uygulamanızın çalışacağı platform için 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'lerini kullanarak özel verilere erişebilmesi için önce bu API'ye erişim izni 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, erişim jetonunun izin verdiği kaynak ve işlemler 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 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 kullanabilir.

Bazı istekler, kullanıcının Google hesabıyla giriş yaptığı bir kimlik doğrulama adımı gerektirir. 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 kademeli 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 izin verdiği 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şim olmadan uygulamanızın ç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 hakkında bilgi edinmek için her Google API'sinin belgelerine bakın. Bir API, birden çok 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 isteğinde bulunduğunda Google People API, https://www.googleapis.com/auth/contacts kapsamını döndürebilir. Google People API yöntemi people.updateContact için izin verilen 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'ye gönderir. Jetonları, URI sorgu dizesi parametreleri olarak göndermek mümkündür, ancak URI parametreleri tamamıyla 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 kaynaklar grubu için geçerlidir. Örneğin, Google Calendar API için bir erişim jetonu verilirse bu jeton, 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 kullanım ömrü boyunca 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 parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından gerçekleştirilir. Bunun sonucunda uygulama, erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde eder.

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 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 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ı; bilgisayar, mobil cihaz ve tablet gibi cihazlara yüklenen uygulamaları destekler. Google API Console aracılığıyla bir 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.

İş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ça gizli kabul edilmez.)

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 parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından gerçekleştirilir. Bunun sonucunda uygulama, erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde eder.

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 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 jetonu kullanır.

Ayrıntılı bilgi 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 parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından gerçekleştirilir.

Bunun sonucunda istemci, Google API isteğine eklemeden önce bunu doğrulaması gereken bir erişim jetonu elde eder. 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 jetonu kullanır.

Ayrıntılar için İstemci Tarafı Uygulamalar için OAuth 2.0'ı Kullanma bölümüne 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 yetkilendirme kodu için bir Google URL'sine web hizmeti isteğinde bulunmasıyla başlar. Yanıt, bir URL ve uygulamanın kullanıcıya gösterdiği kod da dahil olmak üzere birkaç parametre 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ı tarayıcıyı başlatır, belirtilen URL'ye gider, giriş yapar ve kodu girer.

Bu sırada 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 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.

Kullanıcı, tarayıcısı olan ayrı bir cihazda giriş yapar

Ayrıntılar için Cihazlar için OAuth 2.0'ı kullanma bölümüne 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. Bu 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ına ihtiyacınız vardır. 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ının izni gerekir.)

Google API Consoleüzerinden aldığınız bir hizmet hesabının kimlik bilgileri arasında benzersiz olan üretilmiş bir e-posta adresi, istemci kimliği ve en az bir ortak/ö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ği ve bir özel anahtar kullanırsınız. Daha sonra uygulamanız, jeton isteğini Google OAuth 2.0 Yetkilendirme Sunucusu'na gönderir ve bu sunucu da bir erişim jetonu döndürür. Uygulama, bir Google API'sine erişmek için jetonu 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. Bu sürece 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ılar için API belgelerine bakın.

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

Yenileme jetonu geçerlilik süresi

Verilen yenileme jetonunun artık çalışmama ihtimalini öngörmek için kodunuzu yazmanız gerekir. Yenileme jetonu, aşağıdaki nedenlerden biri dolayısıyla çalışmayı durdurabilir:

Harici kullanıcı türü için yapılandırılmış OAuth izin ekranına ve "Test ediliyor" durumuna sahip bir Google Cloud Platform projesine 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) aracılığıyla izin verilmesi gereken 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. Bu sınıra ulaşıldığında, yeni bir yenileme jetonu oluşturulması, en eski yenileme jetonunu herhangi bir uyarı olmaksızın 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 istemciler genelinde sahip olabileceği toplam yenileme jetonu sayısı için daha büyük bir sınır vardır. Normal kullanıcıların çoğu bu sınırı aşmayacaktır. 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 çö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 bunları 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ştikleri sırada kullanıcıların Google Cloud oturum denetimi özelliğini kullanarak sık sık yeniden kimlik doğrulamasını zorunlu kılabilir. Bu politika Google Cloud Console, Google Cloud SDK (gcloud CLI olarak da bilinir) ve Cloud Platform kapsamı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 jetonu iptal edildiğinde olduğu gibi bir hataya neden olur. Çağrı, invalid_grant hata türünde bir hata nedeniyle başarısız olur. error_subtype alanı, iptal edilen jeton ile bir oturum kontrolü politikası nedeniyle oluşan hatayı ayırt etmek için kullanılabilir (örneğin, "error_subtype": "invalid_rapt"). Oturum süresi tam olarak 4 saat olduğundan, oturum süresi çok sınırlı olarak yeniden başlatılabilir (1 saatlik ek süre ile).

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şler veya işlemler için bir sunucuya dağıtılırsa ve bir müşteri bu tür kullanıcılar üzerinde 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 yardımcı olma hakkında daha fazla bilgi için yönetici odaklı bu yardım makalesini inceleyin.

İstemci kitaplıkları

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