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 üzerinden OAuth 2.0 istemci kimlik bilgilerini alın. Ardından, istemci uygulamanız Google Yetkilendirme Sunucusundan bir erişim jetonu ister, yanıttan bir jeton çıkarır ve jetonu, erişmek istediğiniz Google API'sine gönderir. OAuth 2.0'ı Google ile etkileşimli olarak kullanmak 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ış sunulmakta ve daha ayrıntılı içeriklerin bağlantıları yer almaktadı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 bir Google API'sine erişirken 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 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 kullanılmasını gerektirmez ancak bir web sunucusu uygulaması bunu gerektirmez.

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 gizli verilere erişebilmesi için öncelikle 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, bir 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 iletmenin çeşitli yolları vardır ve oluşturmakta olduğ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 isterken, tarayıcının olmadığı bir cihazda web uygulaması istekleri kullanan bir uygulama tarafından yüklenebilir.

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 izin vermek isteyip istemediği sorulur. Bu sürece kullanıcı izni adı verilir.

Kullanıcı en az bir izin verirse Google Yetkilendirme Sunucusu, uygulamanıza bir erişim jetonu (veya uygulamanızın bir erişim jetonu almak için kullanabileceği bir yetkilendirme kodu) ve bu jetonun verdiği erişim kapsamlarının listesini gönderir. Kullanıcı izin vermezse sunucu bir hata döndürür.

Genellikle en iyi uygulama, önceden erişim yapmak yerine erişim gerekli olduğunda aşamalı olarak istekte bulunmaktır. Örneğin, bir etkinliğin takvime kaydedilmesini desteklemek isteyen 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ı tarafından verilen 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. Uygulamanızın ilgili API'ye erişimi olmadan çalışamayan özelliklerini devre dışı bırakın.

Kullanıcı istenen tüm 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ı öğrenmek üzere her bir Google API'nin dokümanlarına bakın. Bir API, birden fazla kapsam dize değerini tek bir erişim kapsamıyla eşleyebilir. Böylece, istekte izin verilen tüm değerler için aynı kapsam dizesi döndürülür. Örnek: Google People API, bir kullanıcının https://www.google.com/m8/feeds/ kapsamı için yetkilendirme isteğinde bulunması durumunda https://www.googleapis.com/auth/contacts kapsamı döndürebilir. Google Kişiler API'si yöntemi people.updateContact için izin verilen https://www.googleapis.com/auth/contacts kapsamı gerekir.

4. Erişim jetonunu 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 düşebileceği için bunu önermeyiz. Ayrıca, gereksiz URI parametre adları oluşturmaktan kaçınmak için REST iyi bir uygulamadı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 verildiyse Google Kişiler API'sine erişim izni vermez. Ancak benzer işlemler için bu erişim jetonunu 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 ömrü kadar Google API erişimine ihtiyaç duyuyorsa 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, Python, Yakut ve ASP.NET gibi dilleri 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ü belirten sorgu parametrelerini içerir. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı rızası Google tarafından yönetilir. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanılmak üzere saklamalı 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 Sunucusuna bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jeton için değiştirir ve bir Google API uç noktasını çağırmak için jetonu kullanır.

Ayrıntıları, Web Sunucusu Uygulamaları için OAuth 2.0'ı Kullanma başlıklı makalede bulabilirsiniz.

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, bunun Yüklü uygulama olduğunu belirtin, ardından uygulama türü olarak Android, Chrome uygulaması, iOS, Evrensel Windows Platformu (UWP) veya Masaüstü uygulamasını seçin.

Bu işlem, istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştireceğiniz bir istemci gizli anahtarıyla sonuçlanır. (Bu bağlamda, istemci gizli anahtarı açık bir şekilde gizli olarak ele alınmaz.)

Yetkilendirme sırası, uygulamanız bir tarayıcıyı 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ı rızası Google tarafından yönetilir. Sonuçta, uygulamanın bir erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.

Uygulama, yenileme jetonunu gelecekte kullanılmak üzere saklamalı 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 Sunucusuna bir jeton isteği gönderir, bir yetkilendirme kodu alır, kodu bir jeton için 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.

İ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ı 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ı rızası Google tarafından yönetilir.

Sonuç olarak, istemcinin bir Google API isteğine dahil edilmeden önce doğrulanması gereken bir erişim jetonu oluşturulur. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.

JS uygulamanız, Google Yetkilendirme Sunucusuna 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 cihazlarda 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 gibi çeşitli parametreler bulunur.

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ı başlatır, belirtilen URL'ye gider, giriş yapar ve kodu girer.

Bu arada, uygulama belirli bir aralıkta bir Google URL'si yok sayar. 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 saklamalı 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ının olduğu ayrı bir cihazdan giriş yapar

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 gibi 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 yetki verilmiş erişim isteğinde bulunabilir.

Bu tür sunucular arası etkileşimler için bir hizmet hesabına ihtiyacınız vardır. Bu hesap, 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ı rızası gerekmez. (Hizmet hesabı dışındaki senaryolarda, 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 Sunucusuna gönderir. Bu durumda erişim jetonu döndürülü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 bir jeton istemek için bir JWT kullanır, ardından bir Google API uç noktasını çağırmak için jetonu kullanır. Oyunda son kullanıcı yer almaz.

Ayrıntılı bilgi için hizmet hesabı dokümanlarına bakın.

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ırlarına sahiptir. Ayrıntılar için API dokümanlarına göz atın.

Google, jeton boyutlarını 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.

Jetonun geçerlilik süresini yenile

Verilen yenileme jetonunun artık çalışmayabileceğini tahmin etmek için kodunuzu yazmanız gerekir. Yenileme jetonu, aşağıdaki nedenlerin birinden dolayı çalışmayı durdurabilir:

Harici kullanıcı türü için yapılandırılmış OAuth izin ekranına ve "Test" yayınlama durumuna sahip olan bir Google Cloud Platform projesi için istenen tek OAuth kapsamları ad, e-posta adresi ve kullanıcı profilinin bir alt kümesi olmadığı sürece ( userinfo.email, userinfo.profile, openid kapsamları veya OpenID Connect eşdeğerleri) 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. Sınıra ulaşılırsa yeni bir yenileme jetonu oluşturmak en yeni yenileme jetonunu uyarı olmadan 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 uygulamayı test etmek için kullanılan bir geliştirici hesabı olabilir.

Birden fazla programı, makineyi 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ırlandırabilirsiniz. Google Workspace yöneticisiyseniz yönetici ayrıcalıklarına sahip ek kullanıcılar oluşturabilir ve bu istemcilerden bazılarını yetkilendirmek için kullanabilirsiniz.

Google Cloud Platform (GCP) kuruluşları için oturum denetimi politikalarını yönetme

GCP kuruluşlarının yöneticileri, Google Cloud oturum denetimi özelliğini kullanarak GCP kaynaklarına erişirlerken kullanıcıların yeniden kimlik doğrulaması yapmasını gerektirebilir. Bu politika Google Cloud Console'a, Google Cloud SDK'sına (gcloud KSA olarak da bilinir) ve Cloud Platform kapsamını gerektiren tüm üçüncü taraf OAuth uygulamalarına erişimi etkiler. Kullanıcı tarafından belirlenen bir oturum denetimi politikası varsa, oturum süresi sona erdiğinde 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. error_subtype alanı, iptal edilen bir jeton ile bir oturum denetimi politikası nedeniyle oluşan bir hata (örneğin, "error_subtype": "invalid_rapt") arasında ayırt etmek için kullanılabilir. Oturum süreleri, 1 saat ile 1 saat arasında yeniden seçilebilir ve 1 saatin kısaltılması gerekebilir.

Aynı şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya kullanmayı teşvik etmemelisiniz. Kullanıcı kimlik bilgileri bir sunucu üzerinde uzun süreli işler veya işlemler için dağıtılırsa ve bir müşteri bu tür kullanıcılara oturum denetimi politikaları uygularsa, oturum süresi dolduğunda 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 dağıtmasına yardımcı olma hakkında daha fazla bilgi edinmek için yönetici odaklı yardım makalesine göz atın.

İstemci kitaplıkları

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