Google API'leri, kimlik doğrulama ve yetkilendirme için OAuth 2.0 protokolünü kullanır. Google; web sunucusu, istemci tarafı, yüklü uygulamalar 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 edinin. 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. OAuth 2.0'ı Google ile kullanmayla ilgili etkileşimli bir gösterim (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) için OAuth 2.0 Playground'u deneyin.
Bu sayfada, Google'ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bir bakış sunulmakta ve daha ayrıntılı içeriklerin 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 başlıklı makaleyi inceleyin.
Temel adımlar
OAuth 2.0 kullanarak bir Google API'sine erişirken tüm uygulamalar temel bir kalıbı izler. Özetle beş adım izlersiniz:
1. Google API Consoleadresinden OAuth 2.0 kimlik bilgilerini edinin.
Hem Google hem de uygulamanız tarafından bilinen istemci kimliği ve istemci gizli anahtarı gibi OAuth 2.0 kimlik bilgilerini edinmek için Google API Console adresini ziyaret edin. Değer grubu, oluşturduğunuz uygulama türüne göre değişiklik gösterir. Örneğin, JavaScript uygulaması gizli anahtar gerektirmez ancak bir web sunucusu uygulaması bunu gerektirir.
Uygulamanızın çalışacağı platforma uygun bir OAuth istemcisi oluşturmanız gerekir. Örneğin:
- Sunucu tarafı veya JavaScript web uygulamaları için "web" istemci türünü kullanın. Bu istemci türünü yerel uygulamalar veya mobil uygulamalar gibi başka hiçbir uygulama için kullanmayın.
- Android uygulamaları için "Android" istemci türünü kullanın.
- iOS ve macOS uygulamaları için "iOS" istemci türünü kullanın.
- Evrensel Windows Platformu uygulamaları için "Evrensel Windows Platformu" istemci türünü kullanın.
- TV veya yerleşik cihazlar gibi sınırlı giriş cihazları için "TV'ler ve Sınırlı Giriş cihazları" istemci türünü kullanın.
- Sunucudan sunucuya etkileşimler için hizmet hesaplarını kullanın.
2. Google Yetkilendirme Sunucusu'ndan erişim jetonu alın.
Uygulamanız, Google API'sini kullanarak gizli verilere erişebilmek için söz konusu API'ye erişim izni veren bir erişim jetonu almalıdır. Tek bir erişim jetonu, birden fazla API'ye farklı erişim düzeyleri 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 isteği göndermenin birkaç yolu vardır ve bunlar, oluşturduğunuz uygulama türüne göre değişiklik gösterir. Örneğin, bir JavaScript uygulaması Google'a yönlendiren bir tarayıcı kullanarak erişim jetonu isteyebilir. Tarayıcı bulunmayan bir cihaza yüklenen bir uygulama ise web hizmeti isteklerini kullanır.
Bazı istekler, kullanıcının Google Hesabı ile 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 bir listesini gönderir. Kullanıcı izin vermezse sunucu hata döndürür.
Genellikle, erişim gerektiğinde kapsamları kademeli olarak istemek, önceden istemekten daha iyi bir uygulamadır. Örneğin, bir etkinliği takvime kaydetmeyi desteklemek isteyen bir uygulama, kullanıcı "Takvime ekle" düğmesine basana kadar Google Takvim erişimi istememelidir. 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ı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şmeden 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 hakkında bilgi edinmek istiyorsanız her bir Google API'sinin belgelerini inceleyin. API, birden çok kapsam dizesi değerini tek bir erişim kapsamıyla eşleyebilir ve istekte izin verilen tüm değerler için aynı kapsam dizesini döndürebilir.
Örnek: Google People API, bir uygulama kullanıcıdan https://www.google.com/m8/feeds/
kapsamı için yetkilendirme isteğinde bulunduğunda https://www.googleapis.com/auth/contacts
kapsamı döndürebilir; Google People API yöntemi people.updateContact
için ise https://www.googleapis.com/auth/contacts
kapsamının verilmesi gerekir.
4. Erişim jetonunu bir API'ye gönderin.
Uygulama, erişim jetonunu aldıktan sonra jetonu bir Google API'sine HTTP Yetkilendirme istek üst bilgisinde 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 parametre adları oluşturmamak da iyi bir REST uygulamasıdır.
Erişim jetonları yalnızca jeton isteğinin scope
bölümünde açıklanan işlemler ve kaynaklar için geçerlidir. Örneğin, Google Takvim API için verilen bir erişim jetonu, Google Kişiler API'ye erişim izni vermez. Ancak bu erişim jetonunu, benzer işlemler için Google Takvim API'ye birden çok kez gönderebilirsiniz.
5. Gerekirse erişim jetonunu yenileyin.
Erişim jetonlarının ömürleri sınırlıdır. Uygulamanızın, tek bir erişim jetonunun geçerlilik süresi bittikten sonra da 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, Go, 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. Bu 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 yönetilir. Sonuç olarak, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.
Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye 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.
Ayrıntılar için Web Sunucusu Uygulamaları için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.
Yüklü uygulamalar
Google OAuth 2.0 uç noktası; bilgisayar, mobil cihaz ve tablet gibi cihazlara yüklenen uygulamaları destekler. Google API Console üzerinden istemci kimliği oluşturduğunuzda, bunun yüklü bir 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.
Bu işlem sonucunda bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştireceğiniz bir istemci sırrı elde edersiniz. (Bu bağlamda, istemci gizli anahtarı açık bir şekilde gizli anahtar olarak değerlendirilmez.)
Yetkilendirme dizisi, 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. Kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni Google tarafından yönetilir. Sonuç olarak, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodu elde edilir.
Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye 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.
Ayrıntılar 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ı, 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. Bu 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 yönetilir.
Sonuçta istemcinin, Google API isteğine eklemeden önce doğrulaması gereken bir erişim jetonu elde edilir. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.
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 bir yetkilendirme kodu için Google URL'sine web hizmeti isteği göndermesiyle başlar. Yanıt, uygulamanın kullanıcıya gösterdiği bir URL ve kod da dahil olmak üzere çeşitli parametreler içerir.
Kullanıcı, cihazdan URL'yi ve kodu 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, oturum açar ve kodu girer.
Bu sırada uygulama, belirli bir aralıkta bir Google URL'sini sorgulamaya devam eder. Kullanıcı erişimi onayladıktan sonra Google sunucusundan gelen yanıtta bir erişim jetonu ve yenileme jetonu bulunur. Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve bir Google API'ye 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.
Ayrıntılar için Cihazlar için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.
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 API'ye kendi kimliğini kanıtlaması gerekir ancak kullanıcı izni gerekmez. Benzer şekilde, kurumsal senaryolarda uygulamanız bazı kaynaklara atanmış erişim isteyebilir.
Bu tür sunucudan sunucuya etkileşimler için bir hizmet hesabına ihtiyacınız vardır. Bu hesap, bireysel bir son kullanıcıya değil, uygulamanıza aittir. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır. Kullanıcı izni gerekmez. (Hizmet hesabı olmayan senaryolarda, uygulamanız son kullanıcılar adına Google API'lerini çağırır ve bazen kullanıcı izni gerekir.)
Google API Console'den aldığınız hizmet hesabının kimlik bilgileri, benzersiz bir e-posta adresi, istemci kimliği ve en az bir herkese açık/özel anahtar çifti içerir. İmzalı bir JWT oluşturmak ve uygun biçimde bir erişim anahtarı isteği oluşturmak için müşteri 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 sunucu, erişim jetonu döndürür. Uygulama, bir Google API'sine erişmek için jetonu kullanır. Jetonun geçerlilik süresi dolduğunda uygulama işlemi tekrarlar.
Ayrıntılar için hizmet hesabı dokümanlarını inceleyin.
Jeton boyutu
Jetonların boyutu aşağıdaki sınırlara kadar değişiklik gösterebilir:
- Yetkilendirme kodları: 256 bayt
- Erişim belirteçleri: 2048 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 belgelerini inceleyin.
Google, jeton boyutunu 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 jetonunun son kullanma tarihi
Kodunuzu, verilen yenileme jetonunun artık çalışmayabileceği ihtimalini öngörecek şekilde yazmanız gerekir. Yenileme jetonunun çalışmamasının nedeni aşağıdakilerden biri olabilir:
- 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 maksimum (etkin) yenileme jetonu sayısını aştı.
- Bir yönetici,
uygulamanızın kapsamlarında istenen hizmetlerden herhangi birini Kısıtlanmış olarak ayarladıysa (
admin_policy_enforced
hatası). - Google Cloud Platform API'leri için yönetici tarafından belirlenen oturum süresi aşılmış olabilir.
Harici bir kullanıcı türü için yapılandırılmış bir OAuth kullanıcı rızası ekranına ve "Test Ediliyor" yayın durumu olan bir Google Cloud Platform projesine, istenen tek OAuth kapsamları ad, e-posta adresi ve kullanıcı profilinin alt kümesi (
userinfo.email, userinfo.profile, openid
kapsamları veya OpenID Connect eşdeğerleriyle) olmadığı sürece 7 gün içinde süresi dolan 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 anahtarı oluşturma işlemi en eski yenileme anahtarını 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ı hesabının veya hizmet hesabının tüm istemcilerde sahip olabileceği toplam yenileme jetonu sayısıyla ilgili 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, makine veya cihazı yetkilendirmeniz gerekiyorsa bir çözüm yolu, 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 bu kullanıcıları bazı müşterilere yetki vermek için kullanabilirsiniz.
Google Cloud Platform (GCP) kuruluşları için oturum denetimi politikalarıyla ilgili işlem yapma
GCP kuruluşlarının yöneticileri, Google Cloud oturum denetimi özelliğini kullanarak kullanıcıların GCP kaynaklarına erişirken sık sık yeniden kimlik doğrulaması yapmasını zorunlu tutabilir. Bu politika, Google Cloud Console'a, Google Cloud SDK'sına (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 denetimi politikası varsa oturum süresi sona erdiğinde API çağrılarınız, yenileme jetonu iptal edildiğinde ortaya çıkacak hataya benzer bir hata verir. Çağrı, invalid_grant
hata türüyle başarısız olur. error_subtype
alanı, iptal edilen jeton ile oturum denetimi politikasından (ör. "error_subtype": "invalid_rapt"
) kaynaklanan bir hatayı ayırt etmek için kullanılabilir. Oturum süreleri çok sınırlı olabileceğinden (1 ila 24 saat arasında) bu senaryo, kimlik doğrulama oturumu yeniden başlatılarak sorunsuz bir şekilde ele alınmalıdır.
Benzer şekilde, sunucudan sunucuya dağıtım için kullanıcı kimlik bilgilerini kullanmamalı veya bu bilgilerin kullanımını teşvik etmemelisiniz. Kullanıcı kimlik bilgileri, uzun süre çalışan işler veya işlemler için bir sunucuya dağıtılırsa ve bir müşteri bu tür kullanıcılara oturum denetimi politikaları uygularsa oturum süresi sona erdiğinde 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 kullanıma sunmasına nasıl yardımcı olabileceğiniz hakkında daha fazla bilgi için bu yöneticilere yönelik yardım makalesine göz atın.
İstemci kitaplıkları
Aşağıdaki istemci kitaplıkları popüler çerçevelerle entegre olduğundan OAuth 2.0'ı uygulamak daha kolaydır. Zaman içinde kitaplıklara daha fazla özellik eklenecektir.
- Java için Google API istemci kitaplığı
- Python için Google API İstemci Kitaplığı
- Go için Google API istemci kitaplığı
- .NET için Google API istemci kitaplığı
- Ruby için Google API istemci kitaplığı
- PHP için Google API istemci kitaplığı
- JavaScript için Google API İstemci Kitaplığı
- GTMAppAuth - Mac ve iOS için OAuth İstemci Kitaplığı