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 ürününden 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. Google ile OAuth 2.0'ı kullanmanın (kendi istemci kimlik bilgilerinizi kullanma seçeneği de dahil) etkileşimli bir gösterimi için OAuth 2.0 Playground ile deneme yapın.
Bu sayfa, Google’ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bakış ve daha ayrıntılı içeriğe bağlantılar sağlar. Kimlik doğrulama için OAuth 2.0'ı kullanma hakkında ayrıntılı bilgiyi OpenID Connect'te bulabilirsiniz.
Temel adımlar
Tüm uygulamalar, OAuth 2.0 kullanarak Google API'ye erişirken temel bir kalıp izler. Yüksek düzeyde 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 adresini ziyaret edin. Değer grubu, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, bir JavaScript uygulaması gizli anahtar gerektirmez ancak bir web sunucusu uygulaması bunu gerektirmez.
2. Google Yetkilendirme Sunucusundan bir erişim jetonu alın.
Uygulamanızın bir Google API'sini 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, 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 istekte bulunmanın birkaç yolu 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 bir erişim jetonu isteğinde bulunabilirken, tarayıcısı olmayan bir cihazda yüklü olan 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 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 bir listesini gönderir. Kullanıcı izin vermezse sunucu bir hata döndürür.
Genel olarak, önceden değil, erişim gerektiğinde kapsamları aşamalı olarak istemek en iyi uygulamadır. Örneğin, bir etkinliği takvime kaydetmeyi desteklemek isteyen bir uygulama, kullanıcı "Takvime Ekle" düğmesine basana kadar Google Takvim'e erişim istememelidir. Ek yetkilendirme konusuna 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. İ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ı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 fazla 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ürür.
Örnek: Google People API, bir uygulamanı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 People API
yöntemi için
people.updateContact izin verilen bir
https://www.googleapis.com/auth/contacts kapsamı gerektirir.
4. Erişim jetonunu 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ında bulunabileceği için bunu önermeyiz. Ayrıca, gereksiz URI parametre adları oluşturmaktan kaçınmak için REST uygulaması önerilir.
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 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 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 ömründen uzun bir Google API'ye erişmesi gerekiyorsa 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, Ruby ve ASP.NET gibi dilleri ve çerçeveleri 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. Google, kullanıcı kimlik doğrulama, oturum seçimi ve kullanıcı rızası işlemlerini gerçekleştirir. Sonuç, uygulamanın bir erişim jetonu ve bir yenileme jetonu karşılığında kullanabileceği bir yetkilendirme kodudur.
Uygulama, yenileme jetonunu ileride kullanılmak üzere kaydetmeli ve bir Google API'sine erişmek için erişim jetonu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.
Ayrıntılı bilgileri, 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 cihazlarda yüklü olan uygulamaları destekler. Google API Console aracılığıyla bir istemci kimliği oluşturduğunuzda, bunun bir Yüklü uygulama olduğunu belirtin ve ardından uygulama türü olarak Android, Chrome uygulaması, iOS, Universal Windows Platform (UWP) veya Masaüstü uygulamasını seçin.
İşlem, bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştirdiğiniz bir istemci gizli anahtarı ile sonuçlanır. (Bu bağlamda, istemci gizli anahtarının gizli anahtar olarak ele alınmadığı kesindir.)
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. Google, kullanıcı kimlik doğrulama, oturum seçimi ve kullanıcı rızası işlemlerini gerçekleştirir. Sonuç, uygulamanın bir erişim jetonu ve bir yenileme jetonu karşılığında kullanabileceği bir yetkilendirme kodudur.
Uygulama, yenileme jetonunu ileride kullanılmak üzere kaydetmeli ve bir Google API'sine erişmek için erişim jetonu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.
Ayrıntılar için Yüklü Uygulamalar için OAuth 2.0'ı Kullanma bölümüne bakı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. Google, kullanıcı kimlik doğrulama, oturum seçimi ve kullanıcı rızası işlemlerini gerçekleştirir.
Sonuç, istemcinin bir Google API isteğine dahil etmeden önce doğrulaması gereken bir erişim jetonudur. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.
Ayrıntılı bilgi için İstemci Tarafı Uygulamaları için OAuth 2.0'ı kullanma başlıklı makaleye bakın.
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ı, yetkilendirme kodu için bir Google URL'sine web hizmeti isteği gönderen uygulamayla başlar. Yanıtta, URL ve uygulamanın kullanıcıya gösterdiği kod dahil olmak üzere ç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ıyı başlatır, belirtilen URL'ye gider, giriş yapar ve kodu girer.
Bu arada, uygulama belirli bir aralıkta Google URL'si 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 ileride kullanılmak üzere kaydetmeli ve bir Google API'sine erişmek için erişim jetonu kullanmalıdır. Erişim jetonunun süresi dolduğunda uygulama, yeni bir jeton almak için yenileme jetonunu kullanır.
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 işlem yapabilir. Bu gibi durumlarda, uygulamanızın API'de 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 tek bir son kullanıcıya değil, uygulamanıza ait bir hizmet hesabı gereklidir. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır ve kullanıcı izni gerekli değildir. (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 Consolearacılığıyla aldığınız hizmet hesabının kimlik bilgileri; benzersiz bir oluşturulmuş e-posta adresi, istemci kimliği ve en az bir ortak/özel anahtar çifti içerir. İstemci kimliğini ve bir özel anahtar kullanarak imzalı bir JWT oluşturmak ve uygun biçimde bir erişim jetonu isteği oluşturmak için kullanırsınız. Uygulamanız, jeton isteğini bir erişim jetonu döndüren Google OAuth 2.0 Yetkilendirme Sunucusuna gönderir. Uygulama, jetonu bir Google API'sine erişmek için kullanır. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.
Ayrıntılar için hizmet hesabı dokümanlarına bakın.
Jeton boyutu
Jetonlar, aşağıdaki sınırlara kadar farklı boyutlarda olabilir:
- Yetkilendirme kodları: 256 bayt
- Erişim jetonları: 2.048 bayt
- Yenileme jetonları: 512 bayt
Google Cloud\u30;un Güvenlik Jetonu Hizmeti 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ı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, 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.
Yenileme jetonunın son kullanma tarihi
Verilen yenileme jetonunun artık çalışmama ihtimalini tahmin etmek için kodunuzu yazmanız gerekir. Yenileme jetonu, aşağıdakilerden biri nedeniyle çalışmayı durdurabilir:
- Kullanıcı, uygulamanızın erişimini iptal etti.
- Yenileme jetonu altı aydır kullanılmadı.
- Kullanıcı şifreleri değiştirdi ve yenileme jetonu Gmail kapsamlarını içeriyor.
- Kullanıcı hesabı, verilen (canlı) yenileme jetonlarının maksimum sayısını aştı.
- Kullanıcı, oturum denetimi politikalarının etkin olduğu bir Google Cloud Platform kuruluşuna ait olur.
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 7 gün içinde yenileme jetonu verilir.
Şu anda OAuth 2.0 istemci kimliği başına Google Hesabı başına 50 yenileme jetonu sınırı vardır. Bu sınıra ulaşıldığında, yeni bir yenileme jetonu oluşturulduğunda en eski yenileme jetonu herhangi bir uyarı olmaksızın otomatik olarak geçersiz kılınır. 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ı için de daha büyük bir sınır vardır. Çoğu normal kullanıcı bu sınırı aşmaz. Ancak bir uygulamayı test etmek için kullanılan geliştirici hesabı olabilir.
Birden çok 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 başka kullanıcılar oluşturabilir ve bunları bazı istemcileri yetkilendirmek için kullanabilirsiniz.
Google Cloud Platform (GCP) kuruluşları için oturum denetimi politikalarıyla başa çıkma
GCP kuruluşlarının yöneticileri, Google Cloud oturum denetimi özelliğini kullanarak GCP kaynaklarına eriştikleri sırada sık sık yeniden kimlik doğrulama yapılmasını gerektirebilir. Bu politika Google Cloud Console'a, Google Cloud SDK'ya (gcloud CLI olarak da bilinir) ve Cloud Platform kapsamını gerektiren tüm üçüncü taraf OAuth uygulamalarına erişimi etkiler. Bir kullanıcının oturum kontrolü politikası varsa oturum süresinin sona ermesi halinde API aramalarınız, yenileme jetonu iptal edildiğinde gerçekleşeceklere benzer şekilde hata verir. Çağrı,
invalid_token hata türüyle başarısız olur. Alt hata türü, iptal jetonu ile oturum kontrolü politikası nedeniyle oluşan hata arasında ayrım yapmak için kullanılabilir. Oturum süreleri çok sınırlı olabileceğinden (1 saat ile 24 saat arasında) bu senaryoda kimlik doğrulama oturumu yeniden başlatılarak sorunsuz bir şekilde ele alınması gerekir.
Aynı şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya bunların kullanımını teşvik etmemelisiniz. Kullanıcı kimlik bilgileri uzun süreli iş veya işlemler için bir sunucuya dağıtılırsa ve müşteri bu tür kullanıcılara oturum kontrol politikaları uygularsa oturum süresi sona erdiğinde kullanıcının kimliğini yeniden doğrulamak mümkün olmayacağı için 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 bu yönetici odaklı yardım makalesine bakı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.
- Java için Google API İstemci Kitaplığı
- Python için Google API İstemci Kitaplığı
- Go için Google API İstemci Kitaplığı
- .NET için Google API İstemci Kitaplığı
- Ruby için Google API İstemci Kitaplığı
- PHP için Google API İstemci Kitaplığı
- JavaScript için Google API İstemci Kitaplığı
- GTMAppAuth - Mac ve iOS için OAuth İstemci Kitaplığı