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 Konsolu'ndan 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 kullanımının etkileşimli bir gösterimi için (kendi istemci kimlik bilgilerinizi kullanma seçeneği dahil) 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ı verilmektedir. Kimlik doğrulama için OAuth 2.0'ı kullanma hakkında ayrıntılı bilgi edinmek istiyorsanız 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. Özetle beş adımı uygulamanız gerekir:
1. Google API Konsolu'ndan 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 Konsolu'nu ziyaret edin. Değerler kümesi, oluşturduğunuz uygulamanın türüne göre değişir. Örneğin, JavaScript uygulaması için gizli anahtar gerekmez ancak web sunucusu uygulaması için gerekir.
Uygulamanızın çalışacağı platforma uygun bir OAuth istemcisi oluşturmanız gerekir. Örneğin:
- Android uygulamaları için Android uygulama türünü kullanın.
-
iOS uygulamaları için iOS uygulama türünü kullanın.
- desktop_windows Masaüstü uygulamaları (ör. Windows, macOS veya Linux uygulamaları ya da CLI araçları) için Masaüstü uygulaması uygulama türünü kullanın.
- code Sunucu tarafı veya JavaScript web uygulamaları için Web uygulaması uygulama türünü kullanın. Bu uygulama türünü yerel veya mobil uygulamalar gibi başka uygulamalar için kullanmayın.
- chrome_extension Chrome uzantıları için Chrome Uzantısı uygulama 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ı uygulama türünü kullanın.
- host Sunucular arası etkileşimler için hizmet hesaplarını kullanın. OAuth istemci kimliği gerekmez.
2. Google Yetkilendirme Sunucusu'ndan bir erişim jetonu alın.
Uygulamanızın bir Google API'si kullanarak gizli verilere erişebilmesi için önce 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ı değişken parametre, 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 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 isteyebilir. Tarayıcısı olmayan bir cihaza yüklenen uygulama ise web hizmeti isteklerini kullanır. İsteğin nasıl yapılacağı hakkında daha fazla bilgi için Scenarios bölümüne ve her uygulama türü için ayrıntılı uygulama kılavuzlarına bakın.
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 işleme kullanıcı rızası adı verilir.
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 listesini gönderir. Kullanıcı izin vermezse sunucu bir hata döndürür.
Genel olarak en iyi uygulama, kapsamları önceden değil, erişim gerektiğinde kademeli olarak istemektir. Örneğin, bir etkinliğin takvime kaydedilmesini desteklemek isteyen bir 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ında yer alan kapsamları, uygulamanızın ilgili bir Google API'sine erişime bağlı özelliklerine ve işlevlerine erişmek için gereken kapsamlarla karşılaştırın. Uygulamanızın, ilgili API'ye erişim olmadan çalışamayan tüm özelliklerini devre dışı bırakın.
Kullanıcı istenen tüm kapsamları onaylamış 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 üzere her bir Google API'sinin belgelerini inceleyin. 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ürebilir.
Örnek: Google People API, bir uygulama kullanıcıdan https://www.google.com/m8/feeds/ kapsamını yetkilendirmesini istediğinde https://www.googleapis.com/auth/contacts kapsamını döndürebilir. Google People API yöntemi people.updateContact, https://www.googleapis.com/auth/contacts kapsamının verilmesini gerektirir.
4. Erişim jetonunu bir API'ye gönderme
Uygulama, erişim jetonunu aldıktan sonra HTTP yetkilendirme isteği başlığında Google API'ye 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 yer alabileceğinden bunu ö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 grubu 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 benzer işlemler için bu erişim jetonunu Google Takvim 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ın tek bir erişim jetonunun kullanım ömründen daha uzun süre 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
Bu senaryolarda, farklı uygulama türleri için yetkilendirme kodları istemek ve erişim ile yenileme jetonları almak amacıyla OAuth 2.0'ın nasıl kullanılacağı açıklanmaktadır.
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ı 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ını, oturum seçimini ve kullanıcı rızasını yönetir. Sonuç, uygulamanın bir erişim jetonu ve yenileme jetonu ile değiştirebileceği bir yetkilendirme kodudur.
Uygulama, yenileme jetonunu ileride kullanmak üzere saklamalı ve Google API'ye erişmek için erişim jetonunu 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 Web Sunucusu Uygulamaları için OAuth 2.0'ı Kullanma başlıklı makaleye bakın.
Yüklü uygulamalar
Google OAuth 2.0 uç noktası; bilgisayar, mobil cihaz ve tablet gibi cihazlara yüklenen uygulamaları destekler. Google API Konsolu üzerinden bir istemci kimliği oluşturduğunuzda bunun yüklü bir uygulama olduğunu belirtin, ardından uygulama türü olarak Android, Chrome Uzantısı, iOS veya Masaüstü uygulaması'nı seçin.
İşlem sonucunda bir istemci kimliği ve bazı durumlarda uygulamanızın kaynak koduna yerleştirdiğiniz bir istemci gizli anahtarı oluşturulur. (Bu bağlamda, istemci gizli anahtarı açıkça 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 parametreleri içerir. Google; kullanıcı kimlik doğrulama, oturum seçimi ve kullanıcı rızası işlemlerini gerçekleştirir. Sonuç, uygulamanın erişim jetonuyla değiştirebileceği bir yetkilendirme kodudur. Uygulama, erişim jetonunu bir Google API isteğine eklemeden önce doğrulamalıdır. Jetonun süresi dolduğunda uygulama işlemi tekrarlar.
İsteğe bağlı olarak, arka uç sunucusu yetkilendirme kodunu yenileme jetonuyla değiştirerek güvenli bir konumda saklayabilir. Erişim jetonunun süresi dolduğunda arka uç sunucusu, uygulama için yeni bir erişim jetonu almak üzere yenileme jetonunu kullanır.
Ayrıntılar için Android için Google kullanıcı verilerine erişimi yetkilendirme, iOS uygulamasında Google API'lerine erişme ve Masaüstü Uygulamaları için OAuth 2.0 başlıklı makaleleri 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ını, oturum seçimini ve kullanıcı rızasını yönetir.
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 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 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, giriş yapar ve kodu girer.
Bu sırada uygulama, belirli bir aralıkta bir Google URL'sini sorgular. 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 kullanmak üzere saklamalı ve Google API'ye erişmek için erişim jetonunu 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ı 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 yetki verilmiş erişim isteğinde bulunabilir.
Bu tür sunucular arası etkileşimler için bireysel bir son kullanıcıya değil, uygulamanıza ait bir hesap olan hizmet hesabına ihtiyacınız vardır. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır ve kullanıcı izni gerekmez. (Hizmet hesabı olmayan senaryolarda uygulamanız, Google API'lerini son kullanıcılar adına çağırır ve bazen kullanıcı izni gerekir.)
Google API Console'dan aldığınız hizmet hesabı kimlik bilgileri; oluşturulan benzersiz bir e-posta adresi, 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. Sunucu, bir erişim jetonu 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ı belgelerine bakın.
Jeton boyutu
Jetonlar, 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'leri 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 belgelerine bakın.
Google, bu sınırlar dahilinde jeton boyutunu değiştirme hakkını saklı tutar ve uygulamanızın değişken jeton boyutlarını buna göre desteklemesi gerekir.
Yenileme jetonunun süresinin dolması
Kodunuzu, verilen bir yenileme jetonunun artık çalışmayabileceği ihtimalini göz önünde bulundurarak yazmanız gerekir. Yenileme jetonunun çalışmayı durdurmasının nedeni aşağıdakilerden biri olabilir:
Harici kullanıcı türü için yapılandırılmış bir OAuth kullanıcı rızası ekranı ve "Test" yayınlama durumu olan bir Google Cloud Platform projesine, 7 gün içinde geçerliliğini yitiren bir yenileme jetonu verilir. Ancak istenen tek OAuth kapsamları ad, e-posta adresi ve kullanıcı profilinin bir alt kümesiyse (
userinfo.email, userinfo.profile, openid kapsamları veya OpenID Connect eşdeğerleri aracılığıyla) bu durum geçerli değildir.
Şu anda Google Hesabı ve OAuth 2.0 istemci kimliği başına 100 yenileme jetonu sınırı vardır. Bu sınıra ulaşıldığında, yeni 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.
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 uygulamanın test edilmesi için kullanılan geliştirici hesapları aşabilir.
Birden fazla program, makine veya cihaz için yetkilendirme yapmanız 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 kontrolü politikalarıyla ilgilenme
GCP kuruluşlarının yöneticileri, Google Cloud oturum kontrolü özelliğini kullanarak GCP kaynaklarına erişen kullanıcıların sık sık yeniden kimlik doğrulaması yapmasını zorunlu kılabilir. 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. Kullanıcı için bir oturum kontrolü politikası varsa oturum süresi sona erdiğinde API çağrılarınız, yenileme jetonunun iptal edilmesi durumunda olduğu gibi hata verir. Çağrı, invalid_grant hata türüyle başarısız olur. error_subtype alanı, iptal edilen bir jeton ile oturum kontrolü politikasından kaynaklanan bir hata (ör. "error_subtype": "invalid_rapt") 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 senaryo, bir kimlik doğrulama oturumu yeniden başlatılarak düzgün 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 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ğrulamanın bir yolu olmayacağından sunucu uygulaması başarısız olur.
Müşterilerinizin bu özelliği dağıtmasına nasıl yardımcı olacağınız 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 olur ve OAuth 2.0'ın uygulanmasını kolaylaştırır. Zaman içinde kitaplıklara daha fazla özellik eklenecektir.
- Java için Google Auth Kitaplığı
- Python için Google API istemci kitaplığı
- Dart 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 istemci kitaplığı
- JavaScript için Google API istemci kitaplığı
- GTMAppAuth - Mac ve iOS için OAuth İstemci Kitaplığı