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 Sunucusu'ndan bir 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 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'e göz atın.

Temel adımlar

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

1. Google API Consoleadresinden OAuth 2.0 kimlik bilgilerini 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 edinmek için Google API Console sayfasını ziyaret edin. Değer grubu, derlediğ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ı gerektirir.

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

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

Uygulamanızın bir Google API'sini kullanarak özel verilere erişebilmesi için öncelikle 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 izni 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 istekte bulunmanın birkaç yolu vardır ve bunlar, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, bir JavaScript uygulaması Google'a yönelik bir tarayıcı yönlendirmesi kullanarak erişim jetonu isterken, tarayıcısı olmayan bir cihaza yüklenen bir uygulama web hizmeti isteklerini kullanır.

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.

Genellikle en iyi uygulama, önceden değil erişim gerektiğinde kapsamları artımlı olarak istemektir. Ö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 (bkz. Artımlı yetkilendirme).

3. Kullanıcının verdiği 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. İlgili API'ye erişim olmadan uygulamanızın çalışamayan ö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ıdan https://www.google.com/m8/feeds/ kapsamını yetkilendirme isteğinde bulunduğunda Google People API'si https://www.googleapis.com/auth/contacts kapsamını döndürebilir. Google People API yöntemi ise people.updateContact için verilen kapsamın https://www.googleapis.com/auth/contacts olmasını gerektirir.

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

Bir uygulama erişim jetonu aldıktan sonra, jetonu HTTP Yetkilendirme istek 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ına girebileceğinden bunu önermeyiz. Ayrıca, gereksiz URI parametresi adları oluşturmaktan kaçınmak 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ü sonrasında bir Google API'sine 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, Go, 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şimin türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izniyle Google ilgilenir. Sonuç olarak, uygulama, bir 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, yenileme jetonunu kullanarak yeni bir jeton alır.

Uygulamanız Google Yetkilendirme Sunucusu'na 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 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ı; bilgisayar, mobil cihaz ve tablet gibi cihazlara yüklenen uygulamaları destekler. Google API Console aracılığıyla bir istemci kimliği oluştururken 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ı oluşturulur. (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şimin türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izniyle Google ilgilenir. Sonuç olarak, uygulama, bir 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, yenileme jetonunu kullanarak yeni bir jeton alır.

Uygulamanız Google Yetkilendirme Sunucusu'na 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 bu jetonu kullanır.

Ayrıntılar için Yüklü Uygulamalarda OAuth 2.0'ı Kullanma bölümüne 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şimin türünü belirten sorgu parametreleri içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izniyle Google ilgilenir.

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

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

Kullanıcı, cihazdan URL'yi ve kodu alır, ardından daha zengin giriş yeteneklerine sahip ayrı bir cihaza veya bilgisayara geçer. Kullanıcı bir tarayıcı 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 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, yenileme jetonunu kullanarak yeni bir jeton alı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 göz atı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 tür 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ı izni gerekebilir.)

Google API Consoleüzerinden edindiğiniz bir hizmet hesabının kimlik bilgilerinde benzersiz şekilde oluşturulmuş 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 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. Jetonun süresi dolduğunda uygulama, işlemi tekrarlar.

Sunucu uygulamanız, Google Yetkilendirme Sunucusu'ndan jeton istemek için bir JWT kullanır, ardından jetonu bir Google API uç noktasını çağırmak için kullanır. Bu sürece 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 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ış olsa da 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ı buna 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:

Harici bir kullanıcı türü için yapılandırılmış bir OAuth izin ekranına ve "Test ediliyor" durumuna sahip bir Google Cloud Platform projesine 7 gün içinde süresi dolacak bir yenileme jetonu verilir. İstenen yegane OAuth kapsamları yalnızca ad, e-posta adresi ve kullanıcı profili alt kümesi ( userinfo.email, userinfo.profile, openid kapsamları veya bunların OpenID Connect eşdeğerleri aracılığıyla) olmadığı sürece.

Ş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şturmak en eski yenileme jetonunu 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ı veya hizmet hesabının tüm istemcilerde 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ş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 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ı yapmasını gerektirebilir. Bu politika Google Cloud Console'a, Google Cloud SDK'ya (gcloud KSA 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 ne olacağına benzer 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ından kaynaklanan hata arasındaki farkı ayırt etmek için kullanılabilir (örneğin, "error_subtype": "invalid_rapt"). Oturum süresi çok sınırlı olduğundan, oturum süresi ç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ü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ı 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.