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 bir erişim jetonu ister, yanıttan bir jeton çıkarır ve jetonu, erişmek istediğiniz Google API'sine gönderir. Google ile OAuth 2.0 kullanmayı etkileşimli bir şekilde göstermek için (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) OAuth 2.0 Playground ile denemeler yapın.

Bu sayfada Google'ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bakış sağlanmakta 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 bakın.

Temel adımlar

OAuth 2.0 kullanarak Google API'ye erişen 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 alın.

Hem Google hem de uygulamanız tarafından bilinen bir 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şir. Ö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 Sunucusundan bir erişim jetonu alın.

Uygulamanızın bir Google API'yi kullanarak özel verilere erişebilmesi için önce 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ı bir değişken parametresi, 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 yerine getirmenin çeşitli yolları vardır ve oluşturduğunuz uygulama türüne göre değişiklik gösterir. Örneğin, bir JavaScript uygulaması Google'a tarayıcı yönlendirmesini kullanarak bir erişim jetonu isteyebilirken, tarayıcısı olmayan bir cihaza yüklenen uygulamalar web hizmeti isteklerini kullanır.

Bazı istekler için 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 izin vermek isteyip istemediği sorulur. Bu işleme 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 bir hata döndürür.

Genellikle, önceden erişim sağlamak yerine erişim gerekli olduğunda kapsamları adım adım istemek en iyi uygulamadır. Örneğin, bir etkinliği takvime kaydetmeyi desteklemek isteyen bir kullanıcı, kullanıcı "Takvime Ekle" düğmesine basana kadar Google Takvim'e erişim isteğinde bulunmamalıdır. Ek 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ı olan 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ışamadığı tüm özellikleri devre dışı bırakın.

Kullanıcı tüm istenen kapsamları vermiş olsa bile, isteğinize dahil edilen kapsam, yanıtınıza dahil edilen kapsamla eşleşmeyebilir. Erişim için gereken kapsamlar için her Google API'nin dokümanlarına bakın. Bir API, birden çok kapsam dizesi 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ının https://www.google.com/m8/feeds/ kapsamını yetkilendirmesini istediğinde Google People API, https://www.googleapis.com/auth/contacts kapsamı döndürebilir. Google Kişiler API yöntemi people.updateContact ise izin verilen https://www.googleapis.com/auth/contacts kapsamı gerektirir.

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

Bir uygulama bir 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 yapmanızı önermiyoruz. Ayrıca, gereksiz URI parametre 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 kaynak kümesi için geçerlidir. Örneğin, Google Calendar API için bir erişim jetonu verilmişse bu jeton, Google Contacts API'ye erişim izni vermez. Ancak bu erişim jetonunu, 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 süresinden daha uzun süre boyunca bir Google API'sine erişmesi gerekiyorsa 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, Yakut ve ASP.NET gibi dil ve çerçeveleri kullanan web sunucusu uygulamalarını destekler.

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'sine yönlendirdiğinde başlar. URL, istenen erişim türünü gösteren sorgu parametrelerini içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı iznini işler. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonu değiş tokuşu yapabileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanabilmek için depolamalı ve bir Google API'sine 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ı makaleye bakın.

Yüklü uygulamalar

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

Bu işlem, bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştireceğiniz bir istemci gizli anahtarı ile sonuçlanır. (Bu bağlamda istemci sırrı kesinlikle bir sır olarak değerlendirilmez.)

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'sine yönlendirdiğinde başlar. URL, istenen erişim türünü gösteren sorgu parametrelerini içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı iznini işler. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonu değiş tokuşu yapabileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanabilmek için depolamalı ve bir Google API'sine 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ılı bilgi 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ı, bir tarayıcıda çalışan JavaScript uygulamalarını destekler.

Yetkilendirme sırası, uygulamanız bir tarayıcıyı Google URL'sine yönlendirdiğinde başlar. URL, istenen erişim türünü gösteren sorgu parametrelerini içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı iznini işler.

Sonuç, istemcinin bir Google API isteğine eklemeden önce doğrulaması gereken bir erişim jetonudur. Jetonun süresi dolduğunda uygulama 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ılı bilgi için İstemci Tarafı Uygulamalar için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

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ğinde bulunmasıyla başlar. Yanıtta, URL ve uygulamanın kullanıcıya gösterdiği kod da dahil olmak üzere birkaç parametre bulunuyor.

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.

Bununla birlikte uygulama, bir Google URL'sini belirli bir aralıkta anket 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 gelecekte kullanabilmek için depolamalı ve bir Google API'sine 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ısı olan ayrı bir cihazda oturum açar

Ayrıntılı bilgi 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 durumlarda, uygulamanızın kendi kimliğini API'ye kanıtlaması gerekir ancak kullanıcı rızası gerekmez. Benzer şekilde, kurumsal senaryolarda uygulamanız bazı kaynaklara yetki verilmiş erişim isteğinde bulunabilir.

Bu tür sunucudan sunucuya etkileşimler için bir hizmet hesabı gerekir. Bu hesap, 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 gerekli değildir. (Hizmet harici hesap senaryolarında, uygulamanız son kullanıcılar adına Google API'lerini çağırır ve bazen kullanıcı izni gerekir.)

Google API Consolehesabından aldığınız hizmet hesabının kimlik bilgileri; benzersiz bir oluşturulan e-posta adresi, bir 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 isteğini Google OAuth 2.0 Yetkilendirme Sunucusu'na gönderir. Bu da 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 tekrar eder.

Sunucu uygulamanız, Google Yetkilendirme Sunucusundan jeton istemek için bir JWT kullanır, ardından jetonu bir Google API uç noktasını çağırmak için kullanır. Son kullanıcının müdahalesi söz konusu 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şebilir:

  • 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ılı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. Uygulamanız, değişken jeton boyutlarını uygun şekilde desteklemelidir.

Jeton geçerlilik bitiş tarihini yenile

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

Harici kullanıcı türü için yapılandırılmış OAuth izin ekranına ve yayınlanma durumu "Test" olan bir Google Cloud Platform projesine; istenen ad, e-posta adresi ve kullanıcı profilinin bir alt kümesi ( userinfo.email, userinfo.profile, openid kapsamları veya OpenID Connect eşdeğerleri aracılığıyla) olmadığı takdirde 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. Bu sınıra ulaşıldığında, yeni bir yenileme jetonu oluşturulması en eski yenileme jetonunu 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ı 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 geliştiricinin hesabını test etmek için kullanılan bir uygulama söz konusu olabilir.

Birden fazla program, makine veya cihazı yetkilendirmeniz gerekiyorsa geçici bir çözüm olarak 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 başka kullanıcılar oluşturabilir ve bu istemcileri bazı istemcileri yetkilendirmek için kullanabilirsiniz.

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

GCP kuruluşlarının yöneticileri, Google Cloud oturum denetimi özelliğini kullanarak GCP kaynaklarına erişirken kullanıcıların 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. Oturum süresi sona ermiş olan kullanıcıların oturum kontrol politikası varsa API çağrılarınız, yenileme jetonu iptal edildiğinde olana benzer bir hatayla sonuçlanır. Arama, invalid_grant hata türüyle başarısız olur. İptal edilmiş bir jeton ile oturum kontrol politikasından kaynaklanan bir hata (örneğin, "error_subtype": "invalid_rapt") arasında ayırt etmek için error_subtype alanı kullanılabilir. Oturum süreleri, 1 saat ile sınırlı bir süre için nadiren 1 saat ile sınırlanabilir.

Aynı şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya kullanmamalarını teşvik etmelisiniz. Kullanıcı kimlik bilgileri bir sunucuda uzun süre çalışan işler veya işlemler için dağıtılırsa ve bir müşteri bu tür oturumlarda oturum denetimi politikalarını uygularsa oturum süresi dolduğunda 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 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 olarak OAuth 2.0'ı uygulamayı kolaylaştırır. Zamanla kitaplıklara daha fazla özellik eklenecektir.