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ş 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 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 kullanımının etkileşimli bir gösterimi (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) için OAuth 2.0 Playground ile deneme yapın.
Bu sayfada, Google'ın desteklediği OAuth 2.0 yetkilendirme senaryolarına genel bir bakış sunulmakta ve daha ayrıntılı içeriklere bağlantılar verilmektedir. 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
Tüm uygulamalar, OAuth 2.0 kullanarak bir Google API'sine erişirken temel bir kalıbı izler. Özet olarak beş adımı uygulamanız gerekir:
1. Google API Consoleadresinden OAuth 2.0 kimlik bilgilerini alın.
Google ve 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ğerler kümesi, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, JavaScript uygulamasında gizli anahtar gerekmez ancak web sunucusu uygulamasında gerekir.
Uygulamanızın çalışacağı platforma uygun bir OAuth istemcisi oluşturmanız gerekir. Örneğin:
- code Sunucu tarafı veya JavaScript web uygulamaları için "web" istemci türünü kullanın. Bu istemci türünü yerel veya mobil uygulamalar gibi başka uygulamalar 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 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.
- host Sunucudan sunucuya etkileşimler için hizmet hesaplarını kullanın.
2. Google yetkilendirme sunucusundan erişim jetonu alın.
Uygulamanızın bir Google API'si kullanarak gizli verilere erişebilmesi için öncelikle söz konusu API'ye erişim izni veren bir erişim jetonu alması gerekir. Tek bir erişim jetonu, birden fazla API'ye farklı düzeylerde erişim izni verebilir. scope adlı bir değişken parametre, erişim jetonunun izin verdiği kaynak ve işlemler 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 bu yollar, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, bir JavaScript uygulaması, Google'a tarayıcı yönlendirmesi kullanarak erişim jetonu isteyebilir. Tarayıcısı olmayan bir cihaza yüklenen 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. Oturum açtıktan sonra kullanıcıya, uygulamanızın istediği bir veya daha fazla izni vermeye istekli olup olmadığı 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ı izni vermezse sunucu hata döndürür.
Genel olarak, kapsamları önceden değil, erişim gerektiğinde artımlı 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 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şim olmadan çalışamayan uygulama ö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 hakkında bilgi edinmek üzere her bir Google API'sinin dokümanlarına bakın. Bir API, birden fazla 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: Bir uygulama, 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ını döndürebilir. Google People API yöntemi people.updateContact için https://www.googleapis.com/auth/contacts kapsamının verilmesi gerekir.
4. Erişim jetonunu bir API'ye gönderin.
Bir uygulama erişim jetonu aldıktan sonra jetonu HTTP yetkilendirme isteği üstbilgisinde bir Google API'sine gönderir. Jetonsuz istekler URI sorgu dizesi parametreleri olarak gönderilebilir ancak URI parametreleri tamamen güvenli olmayan günlük dosyalarında yer alabileceğinden bu yöntemi ö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şlemler ve kaynaklar için geçerlidir. Örneğin, Google Takvim API'si için verilen bir erişim jetonu, Google Kişiler API'sine erişim izni vermez. Ancak bu erişim jetonunu benzer işlemler için Google Takvim API'sine 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ın 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ı almasına olanak tanır.
Senaryolar
Web sunucusu uygulamaları
Google OAuth 2.0 uç noktası, PHP, Java, Go, Python, Ruby 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ü belirten sorgu parametreleri içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni işlemlerini gerçekleştirir. Sonuç, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodudur.
Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve 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 aracılığıyla bir istemci kimliği oluşturduğunuzda bunun yüklü bir uygulama olduğunu belirtin, ardından uygulama türü olarak Android, Chrome uygulaması, iOS, Universal Windows Platformu (UWP) veya Masaüstü uygulaması'nı seçin.
Bu işlem sonucunda bir istemci kimliği ve bazı durumlarda bir istemci gizli anahtarı elde edilir. Bu anahtarı uygulamanızın kaynak koduna yerleştirirsiniz. (Bu bağlamda, istemci gizli anahtarı gizli 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ü belirten sorgu parametreleri içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni işlemlerini gerçekleştirir. Sonuç, uygulamanın erişim jetonu ve yenileme jetonuyla değiştirebileceği bir yetkilendirme kodudur.
Uygulama, yenileme jetonunu gelecekte kullanmak üzere saklamalı ve 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ı Google URL'sine yönlendirdiğinde başlar. URL, istenen erişim türünü belirten sorgu parametreleri içerir. Google, kullanıcı kimlik doğrulaması, oturum seçimi ve kullanıcı izni işlemlerini gerçekleştirir.
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.
Ayrıntılar için İstemci Tarafı Uygulamaları için OAuth 2.0'ı Kullanma başlıklı makaleye bakın.
Sınırlı giriş cihazlarındaki uygulamalar
Google OAuth 2.0 uç noktası, oyun konsolları, video kameralar ve yazıcılar gibi sınırlı giriş cihazlarında ç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ıt, bir URL ve uygulamanın kullanıcıya gösterdiği bir kod da dahil olmak üzere çeşitli parametreler içerir.
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, oturum açar ve kodu girer.
Bu sırada uygulama, belirtilen aralıklarla bir Google URL'sini yoklar. 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'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.
Ayrıntılar için Cihazlar için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.
Hizmet hesapları
Tahmin API'si 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 temsilci erişimi isteyebilir.
Bu tür sunucudan sunucuya etkileşimler için bireysel bir son kullanıcıya değil, uygulamanıza ait olan bir hizmet hesabı gerekir. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır ve kullanıcı izni gerekmez. (Hizmet hesabı kullanılmayan senaryolarda uygulamanız, son kullanıcılar adına Google API'lerini çağırır ve bazen kullanıcı izni gerekir.)
Google API Consolearacından aldığınız hizmet hesabı kimlik bilgileri; benzersiz bir şekilde oluşturulmuş e-posta adresi, istemci kimliği ve en az bir genel/ö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. Sunucu, erişim jetonunu döndürür. Uygulama, bir Google API'sine erişmek için jetonu kullanır. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.
Ayrıntılar için hizmet hesabı dokümanlarını inceleyin.
Jeton boyutu
Jetonsuz ödeme işlemleri, aşağıdaki sınırlara kadar farklı boyutlarda olabilir:
Google Cloud'un Security Token Service 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 belgelerini inceleyin.
Google, bu sınırlar içinde jeton boyutunu değiştirme hakkını saklı tutar ve uygulamanız buna göre değişken jeton boyutlarını desteklemelidir.
Yenileme jetonunun son kullanma tarihi
Verilen yenileme jetonunun artık çalışmayabileceği ihtimalini göz önünde bulundurarak kodunuzu yazmanız gerekir. Yenileme jetonunun çalışmayı durdurmasının nedenleri:
Harici kullanıcı türü için yapılandırılmış bir OAuth izin ekranı ve "Test ediliyor" yayınlama durumuna sahip bir Google Cloud Platform projesine, istenen tek OAuth kapsamları 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ığı sürece 7 gün içinde sona erecek 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 jetonu oluşturma işlemi 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ı hesabının veya hizmet hesabının tüm istemcilerde sahip olabileceği toplam yenileme jetonu sayısı için daha yüksek 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ı bu sınırı aşabilir.
Birden fazla program, makine veya cihazı yetkilendirmeniz gerekiyorsa Google Hesabı başına yetkilendirdiğiniz istemci sayısını 15 veya 20 ile sınırlayabilirsiniz. Google Workspace yöneticisiyseniz, yönetici ayrıcalıklarına sahip ek kullanıcılar oluşturabilir ve bu kullanıcıları 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 kontrolü özelliğini kullanarak kullanıcıların GCP kaynaklarına erişirken sık sık yeniden kimlik doğrulaması yapmasını isteyebilir. 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üresi sona erdiğinde API çağrılarınız, yenileme jetonu iptal edilmiş gibi hata verir. Çağrı, invalid_grant hata türüyle başarısız olur. error_subtype alanı, iptal edilmiş bir jeton ile oturum kontrolü politikası nedeniyle oluşan bir hata arasında ayrım yapmak için kullanılabilir (örneğin, "error_subtype": "invalid_rapt"). Oturum süreleri çok sınırlı olabileceğinden (1 saat ile 24 saat arasında) bu senaryo, kimlik doğrulama oturumu yeniden başlatılarak sorunsuz bir şekilde ele alınmalıdır.
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üren 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 yeniden kimliği doğrulanmayacağından sunucu uygulaması başarısız olur.
Müşterilerinizin bu özelliği kullanmaya başlamasına yardımcı olma hakkında daha fazla bilgi için yöneticilere yönelik bu yardım makalesini inceleyin.
İstemci kitaplıkları
Aşağıdaki istemci kitaplıkları, popüler çerçevelerle entegre olarak OAuth 2.0'ın uygulanmasını kolaylaştırır. Zaman içinde kitaplıklara daha fazla özellik eklenecektir.
- Java için Google API istemci kitaplığı
- Python için Google API istemci 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 İstemci Kitaplığı
- JavaScript için Google API istemci kitaplığı
- GTMAppAuth - Mac ve iOS için OAuth istemci kitaplığı