Using OAuth 2.0 for Server to Server Applications (Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma)

<0x0 Daha fazla bilgi için Google Cloud Platform belgelerindeki Kimliğe Doğrulama Genel Bakış başlıklı makaleyi inceleyin.

Google OAuth 2.0 sistemi, bir web uygulaması ile bir Google hizmeti arasındaki etkileşimler gibi sunucudan sunucuya etkileşimleri destekler. Bu senaryo için hizmet hesabı gerekir. Hizmet hesabı, bireysel bir son kullanıcıya değil, uygulamanıza ait olan bir hesaptır. Uygulamanız, hizmet hesabı adına Google API'lerini çağırır. Dolayısıyla kullanıcılar doğrudan dahil olmaz. Bu senaryoya bazen "iki ayaklı OAuth" veya "2LO" denir. (İlgili terim olan "üç aşamalı OAuth", uygulamanızın son kullanıcılar adına Google API'lerini çağırdığı ve bazen kullanıcı izninin gerektiği senaryoları ifade eder.)

Genellikle bir uygulama, kullanıcı verileri yerine kendi verileriyle çalışmak için Google API'lerini kullandığında hizmet hesabı kullanır. Örneğin, verilerin kalıcı olması için Google Cloud Datastore'u kullanan bir uygulama, Google Cloud Datastore API'ye yaptığı çağrıların kimliğini doğrulamak için bir hizmet hesabı kullanır.

Google Workspace alan yöneticileri, alan genelinde yetkilendirme yaparak hizmet hesaplarının alandaki kullanıcılar adına kullanıcı verilerine erişmesine de izin verebilir.

Bu belgede, bir uygulamanın Google API'leri istemci kitaplığı (önerilir) veya HTTP kullanarak sunucudan sunucuya OAuth 2.0 akışını nasıl tamamlayabileceği açıklanmaktadır.

Bazı Google API'lerinde, OAuth 2.0 kullanmak yerine imzalı bir JWT kullanarak yetkilendirilmiş API çağrıları yapabilirsiniz. Bu sayede bir ağ isteğinden tasarruf edebilirsiniz. Ek: OAuth olmadan hizmet hesabı yetkilendirme başlıklı bölümü inceleyin.

Genel Bakış

Sunucular arası etkileşimleri desteklemek için öncelikle API Consoleiçinde projeniz için bir hizmet hesabı oluşturun. Google Workspace hesabınızdaki kullanıcıların kullanıcı verilerine erişmek istiyorsanız hizmet hesabına alan genelinde erişim yetkisi verin.

Ardından, uygulamanız OAuth 2.0 kimlik doğrulama sunucusundan erişim jetonu istemek için hizmet hesabının kimlik bilgilerini kullanarak yetkili API çağrıları yapmaya hazırlanır.

Son olarak, uygulamanız Google API'lerini çağırmak için erişim jetonunu kullanabilir.

Öneri: Uygulamanız bu görevleri diliniz için Google API'leri istemci kitaplığını kullanarak veya HTTP aracılığıyla doğrudan OAuth 2.0 sistemiyle etkileşimde bulunarak tamamlayabilir. Ancak sunucudan sunucuya kimlik doğrulama etkileşimlerinin mekanizması, uygulamaların JSON Web Jetonları (JWT'ler) oluşturup kriptografik olarak imzalamasını gerektirir. Bu nedenle, uygulamanızın güvenliğini ciddi şekilde etkileyebilecek ciddi hatalar yapmak kolaydır.

Bu nedenle, şifrelemeyi uygulama kodunuzdan uzaklaştıran Google API'leri istemci kitaplıkları gibi kitaplıkları kullanmanızı önemle tavsiye ederiz.

Hizmet hesabı oluşturma

Hizmet hesabının kimlik bilgileri, benzersiz olan ve en az bir genel/özel anahtar çifti içeren oluşturulmuş bir e-posta adresini içerir. Alan genelinde yetki etkinleştirilmişse istemci kimliği de hizmet hesabının kimlik bilgilerinin bir parçasıdır.

Uygulamanız Google App Engine'de çalışıyorsa projenizi oluşturduğunuzda hizmet hesabı otomatik olarak ayarlanır.

Uygulamanız Google Compute Engine'de çalışıyorsa projenizi oluşturduğunuzda otomatik olarak bir hizmet hesabı da oluşturulur ancak Google Compute Engine örneği oluştururken uygulamanızın erişmesi gereken kapsamları belirtmeniz gerekir. Daha fazla bilgi için Hizmet hesaplarını kullanmak üzere örnek hazırlama başlıklı makaleyi inceleyin.

Uygulamanız Google App Engine veya Google Compute Engine'de çalışmıyorsa bu kimlik bilgilerini Google API Console'den almanız gerekir. Hizmet hesabı kimlik bilgileri oluşturmak veya daha önce oluşturduğunuz herkese açık kimlik bilgilerini görüntülemek için aşağıdakileri yapın:

tutucu2 l10n-yer

Öncelikle bir hizmet hesabı oluşturun:

1. Service accounts pageaçın.
2. If prompted, select a project, or create a new one.
3. Hizmet hesabı oluştur'u .
4. Hizmet hesabı ayrıntıları altında, hizmet hesabı için bir ad, kimlik ve açıklama yazın, ardından Oluştur ve devam et seçeneğine tıklayın.
5. İsteğe bağlı: Bu hizmet hesabına projeye erişim izni ver altında, hizmet hesabına verilecek IAM rollerini seçin.
6. Devam'ı tıklayın.
7. İsteğe bağlı: Kullanıcılara bu hizmet hesabına erişim izni ver altında, hizmet hesabını kullanmasına ve yönetmesine izin verilen kullanıcıları veya grupları ekleyin.
8. Bitti'yi tıklayın.

Ardından, bir hizmet hesabı anahtarı oluşturun:

1. Oluşturduğunuz hizmet hesabının e-posta adresine tıklayın.
2. Anahtarlar sekmesini tıklayın.
3. Anahtar ekle açılır listesinde Yeni anahtar oluştur öğesini seçin.
4. Oluştur'u tıklayın.

Yeni genel/özel anahtar çiftiniz oluşturulur ve makinenize indirilir; özel anahtarın tek kopyası olarak hizmet eder. Güvenli bir şekilde saklamaktan siz sorumlusunuz. Bu anahtar çiftini kaybederseniz, yeni bir tane oluşturmanız gerekecektir.

E-posta adresini, ortak anahtar parmak izlerini ve diğer bilgileri görüntülemek ya da ek ortak/özel anahtar çiftleri oluşturmak için istediğiniz zaman API Console bölümüne dönebilirsiniz. API Console'daki hizmet hesabı kimlik bilgileri hakkında daha fazla bilgi için API Consoleyardım dosyasındaki Hizmet hesapları bölümüne bakın.

Hizmet hesabının e-posta adresini not edin ve hizmet hesabının özel anahtar dosyasını uygulamanızın erişebileceği bir konuma kaydedin. Uygulamanızın yetkilendirilmiş API çağrıları yapması için bu kimlik bilgilerine ihtiyacı vardır.

Not: Özel anahtarları hem geliştirme hem de üretim ortamlarında güvenli bir şekilde saklamanız ve yönetmeniz gerekir. Google, özel anahtarlarınızın bir kopyasını tutmaz, yalnızca ortak anahtarlarınızı tutar. Daha fazla bilgi için OAuth 2.0 Politikaları'nın İstemci Kimlik Bilgilerini Güvenli Bir Şekilde İşleme bölümüne bakın.

Hizmet hesabına alan genelinde yetki verme

Google Workspace hesabını kullanan bir kuruluşun Workspace yöneticisi, Google Workspace alanındaki kullanıcılar adına Workspace kullanıcı verilerine erişmek için bir uygulamayı yetkilendirebilir. Örneğin, bir Google Workspace alanındaki tüm kullanıcıların takvimlerine etkinlik eklemek için Google Takvim API'sini kullanan bir uygulama, kullanıcılar adına Google Takvim API'sine erişmek için hizmet hesabı kullanır. Bir hizmet hesabını, alandaki kullanıcılar adına verilere erişmesi için yetkilendirmeye bazen "bir hizmet hesabına alan genelinde yetki verme" adı verilir.

Not: Alanınıza bir uygulama yüklemek için Google Workspace Marketplace'i kullandığınızda, yükleme sırasında gerekli izinler uygulamaya otomatik olarak verilir. Uygulamanın kullandığı hizmet hesaplarını manuel olarak yetkilendirmeniz gerekmez.

Not: Google Workspace alanından çalışan uygulamalarda hizmet hesaplarını kullanabilseniz de hizmet hesapları, Google Workspace hesabınızın üyesi değildir ve Google Workspace yöneticileri tarafından belirlenen alan politikalarına tabi değildir. Örneğin, Google Workspace yöneticisi tarafından Google Workspace Yönetici Konsolu'nda Google Workspace son kullanıcılarının alan dışındaki dokümanları paylaşma özelliğini kısıtlamak için belirlenen bir politika, hizmet hesapları için geçerli olmaz.

Bir hizmet hesabına alan genelinde yetki vermek için Google Workspace alanının süper yöneticisi aşağıdaki adımları tamamlamalıdır:

1. Google Workspace alanınızın Yönetici Konsolu'nda Ana menü > Güvenlik > Erişim ve veri denetimi > API Denetimleri'ne gidin.
2. Alan genelinde yetki bölmesinde Alan Genelinde Yetkiyi Yönetme'yi seçin.
3. Yeni ekle'yi tıklayın.
4. İstemci Kimliği alanına hizmet hesabının istemci kimliğini girin. Hizmet hesabınızın istemci kimliğini Service accounts pagebölümünde bulabilirsiniz.
5. OAuth kapsamları (virgülle ayrılmış) alanına, uygulamanıza erişim izni verilmesi gereken kapsamların listesini girin. Örneğin, uygulamanızın Google Drive API'sine ve Google Calendar API'sine alan genelinde tam erişmesi gerekiyorsa şunları girin: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Yetkilendir'i tıklayın.

Uygulamanız artık Workspace alanınızdaki kullanıcılar olarak API çağrıları yapma (kullanıcıların kimliğine "bürünme") yetkisine sahip. Bu yetkilendirilmiş API çağrılarını yapmaya hazırlanırken kimliğine bürünülecek kullanıcıyı açıkça belirtirsiniz.

Not: Müşteri kimliği eklendikten sonra kimliğe bürünme erişiminin verilmesi genellikle birkaç dakika sürer ancak bazı durumlarda Google Hesabınızın tüm kullanıcılarına yansıtılması 24 saati bulabilir.

Yetkilendirilmiş API çağrısı yapmaya hazırlanma

Java

API Console'dan istemci e-posta adresini ve özel anahtarı aldıktan sonra, hizmet hesabının kimlik bilgilerinden ve uygulamanızın erişmesi gereken kapsamlar arasından bir GoogleCredentials nesnesi oluşturmak için Java için Google Auth Kitaplığı'nı kullanın. Örneğin:

import com.google.auth.oauth2.GoogleCredentials;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Google Cloud Platform'da bir uygulama geliştiriyorsanız bunun yerine uygulama varsayılan kimlik bilgilerini kullanabilirsiniz. Bu, süreci basitleştirebilir.

Alan genelinde yetki verme

Hizmet hesabına alan genelinde erişim yetkisi verdiyseniz ve bir kullanıcı hesabının kimliğine bürünmek istiyorsanız createDelegated nesnesinin GoogleCredentials yöntemiyle kullanıcı hesabının e-posta adresini belirtin. Örneğin:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

Yukarıdaki kod, GoogleCredentials nesnesini kullanarak createDelegated() yöntemini çağırır. createDelegated() yöntemi için bağımsız değişken, Workspace hesabınıza ait bir kullanıcı olmalıdır. İsteği yapan kodunuz, hizmet hesabınızı kullanarak Google API'lerini çağırmak için bu kimlik bilgisini kullanır.

Python

API Consoleadresinden istemci e-posta adresini ve özel anahtarı aldıktan sonra aşağıdaki adımları tamamlamak için Python için Google API'leri İstemci Kitaplığı'nı kullanın:

1. Hizmet hesabının kimlik bilgilerinden ve uygulamanızın erişmesi gereken kapsamlar için bir Credentials nesnesi oluşturun. Örneğin:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Google Cloud Platform'da bir uygulama geliştiriyorsanız bunun yerine uygulama varsayılan kimlik bilgilerini kullanabilirsiniz. Bu, süreci basitleştirebilir.

2. Alan genelinde yetki verme

   Hizmet hesabına alan genelinde erişim yetkisi verdiyseniz ve bir kullanıcı hesabının kimliğine bürünmek istiyorsanız with_subject yöntemini kullanın.ServiceAccountCredentials Örneğin:

   delegated_credentials = credentials.with_subject('[e-mail]')

Uygulamanızda Google API'lerini çağırmak için Credentials nesnesini kullanın.

HTTP/REST

Öneri: Uygulamanız bu görevleri HTTP kullanarak doğrudan OAuth 2.0 sistemiyle etkileşim kurarak tamamlayabilse de sunucudan sunucuya kimlik doğrulama etkileşimlerinin mekanizması, uygulamaların JSON Web Token'ları (JWT'ler) oluşturmasını ve kriptografik olarak imzalamasını gerektirir. Bu nedenle, uygulamanızın güvenliğini ciddi şekilde etkileyebilecek ciddi hatalar yapmak kolaydır.

Bu nedenle, şifrelemeyi uygulama kodunuzdan uzaklaştıran Google API'leri istemci kitaplıkları gibi kitaplıkları kullanmanızı önemle tavsiye ederiz.

API Consolehizmetinden istemci kimliğini ve özel anahtarı aldıktan sonra uygulamanızın aşağıdaki adımları tamamlaması gerekir:

1. Başlık, talep kümesi ve imza içeren bir JSON Web Jetonu (JWT, "jot" olarak telaffuz edilir) oluşturun.
2. Google OAuth 2.0 yetkilendirme sunucusundan erişim jetonu isteyin.
3. Yetkilendirme sunucusunun döndürdüğü JSON yanıtını işleyin.

Aşağıdaki bölümlerde bu adımların nasıl tamamlanacağı açıklanmaktadır.

Yanıt bir erişim jetonu içeriyorsa Google API'sini çağırmak için erişim jetonunu kullanabilirsiniz. (Yanıt erişim jetonu içermiyorsa JWT'niz ve jeton isteğiniz doğru şekilde oluşturulmamış olabilir veya hizmet hesabının istenen kapsamlara erişme izni olmayabilir.)

Erişim jetonunun süresi dolduğunda uygulamanız başka bir JWT oluşturur, bunu imzalar ve başka bir erişim jetonu ister.

Bu bölümün geri kalanında JWT oluşturma, JWT'yi imzalama, erişim jetonu isteğini oluşturma ve yanıtı işleme ile ilgili ayrıntılar açıklanmaktadır.

JWT oluşturma

JWT üç bölümden oluşur: başlık, talep grubu ve imza. Başlık ve talep kümesi JSON nesneleridir. Bu JSON nesneleri UTF-8 baytlarına serileştirilir ve ardından Base64url kodlaması kullanılarak kodlanır. Bu kodlama, tekrarlanan kodlama işlemleri nedeniyle kodlama değişikliklerine karşı dayanıklılık sağlar. Başlık, hak talebi grubu ve imza, nokta (.) karakteriyle birleştirilir.

JWT aşağıdaki şekilde oluşturulur:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

İmza için temel dize aşağıdaki gibidir:

{Base64url encoded header}.{Base64url encoded claim set}

JWT üstbilgisini oluşturma

Başlık, imzalama algoritmasını, onay biçimini ve JWT'yi imzalamak için kullanılan [hizmet hesabı anahtarının anahtar kimliğini](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) belirten üç alandan oluşur. Algoritma ve biçim zorunludur ve her alanın yalnızca bir değeri vardır. Ek algoritmalar ve biçimler kullanıma sunuldukça bu başlık da buna göre değişecektir. Anahtar kimliği isteğe bağlıdır ve yanlış bir anahtar kimliği belirtilirse GCP, jetonu doğrulamak için hizmet hesabıyla ilişkili tüm anahtarları dener ve geçerli bir anahtar bulunamazsa jetonu reddeder. Google, gelecekte yanlış anahtar kimliklerine sahip jetonları reddetme hakkını saklı tutar.

Hizmet hesapları, RSA SHA-256 algoritmasını ve JWT jeton biçimini kullanır. Sonuç olarak, başlığın JSON gösterimi aşağıdaki gibidir:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

Bunun Base64url gösterimi şu şekildedir:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

JWT hak talebi kümesini oluşturma

JWT talebi kümesi, istenen izinler (kapsamlar), jetonun hedefi, veren, jetonun verildiği zaman ve jetonun geçerlilik süresi dahil olmak üzere JWT hakkında bilgiler içerir. Alanların çoğu zorunludur. JWT başlığı gibi, JWT talebi kümesi de bir JSON nesnesidir ve imzanın hesaplanmasında kullanılır.

Gerekli hak talepleri

JWT talebi kümesinde gerekli olan talepler aşağıda gösterilmektedir. Hak talebi grubunda herhangi bir sırada görünebilirler.

Ad	Açıklama
iss	Hizmet hesabının e-posta adresi.
scope	Uygulamanın istediği izinlerin boşlukla ayrılmış listesi.
aud	Onayın amaçlanan hedefinin tanımlayıcısı. Erişim jetonu isteğinde bulunurken bu değer her zaman https://oauth2.googleapis.com/token olur.
exp	Onayın geçerlilik bitiş zamanı, 1 Ocak 1970 00:00:00 UTC'den itibaren saniye cinsinden belirtilir. Bu değer, yayınlanma zamanından sonra en fazla 1 saat geçerlidir.
iat	Onaylamanın yayınlandığı zaman, 1 Ocak 1970 00:00:00 UTC'den itibaren saniye olarak belirtilir.

JWT talep kümesindeki zorunlu alanların JSON gösterimi aşağıda verilmiştir:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Ek hak talepleri

Bazı kurumsal durumlarda, bir uygulama kuruluşta belirli bir kullanıcı adına işlem yapmak için alan genelinde yetki kullanabilir. Bir uygulamanın kullanıcı kimliğine bürünebilmesi için bu tür bir kimliğe bürünme izni verilmesi gerekir. Bu izin genellikle bir süper yönetici tarafından verilir. Daha fazla bilgi için Alan genelinde yetkiyle API erişimini kontrol etme başlıklı makaleyi inceleyin.

Bir uygulamaya bir kaynağa yetki verilmiş erişim izni veren erişim jetonu almak için JWT talebi kümesine kullanıcının e-posta adresini sub alanının değeri olarak ekleyin.

Ad	Açıklama
sub	Uygulamanın, adına yetkilendirilmiş erişim isteğinde bulunduğu kullanıcının e-posta adresi.

Bir uygulamanın kullanıcı kimliğine bürünme izni yoksa sub alanını içeren bir erişim jetonu isteğine verilen yanıt hata olur.

sub alanını içeren bir JWT talebi kümesi örneği aşağıda gösterilmektedir:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

JWT talebi grubunu kodlama

JWT üstbilgisi gibi, JWT talebi kümesi de UTF-8'e serileştirilmeli ve Base64url güvenli olarak kodlanmalıdır. Aşağıda, JWT Claim Set'in JSON gösterimi örneği verilmiştir:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

İmzayı hesaplama

JSON Web Signature (JWS), JWT için imza oluşturma mekanizmalarını yönlendiren spesifikasyondur. İmza için giriş, aşağıdaki içeriğin bayt dizisidir:

{Base64url encoded header}.{Base64url encoded claim set}

İmza hesaplanırken JWT üstbilgisindeki imzalama algoritması kullanılmalıdır. Google OAuth 2.0 yetkilendirme sunucusu tarafından desteklenen tek imza algoritması, SHA-256 karma oluşturma algoritması kullanan RSA'dır. Bu, JWT üstbilgisindeki alg alanında RS256 olarak ifade edilir.

Girişin UTF-8 gösterimini, Google API Consoleadresinden alınan özel anahtarla SHA256withRSA (SHA-256 karma işleviyle RSASSA-PKCS1-V1_5-SIGN olarak da bilinir) kullanarak imzalayın. Çıkış, bir bayt dizisi olur.

İmza daha sonra Base64url kodlu olmalıdır. Başlık, hak talebi grubu ve imza, nokta (.) karakteriyle birleştirilir. Sonuç, JWT'dir. Aşağıdaki gibi olmalıdır (daha net olması için satır sonları eklenmiştir):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Aşağıda, Base64url kodlaması yapılmamış bir JWT örneği verilmiştir:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Aşağıda, imzalanmış ve iletilmeye hazır bir JWT örneği verilmiştir:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Erişim jetonu isteğinde bulunma

İmzalı JWT oluşturulduktan sonra bir uygulama, erişim jetonu istemek için bunu kullanabilir. Bu erişim jetonu isteği bir HTTPS POST isteğidir ve gövde URL kodludur. URL aşağıda gösterilmiştir:

https://oauth2.googleapis.com/token

HTTPS POST isteğinde aşağıdaki parametreler gereklidir:

Ad	Açıklama
grant_type	Gerekirse URL kodlaması yapılmış aşağıdaki dizeyi kullanın: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	İmza dahil JWT.

Aşağıda, erişim jetonu isteğinde kullanılan HTTPS POST isteğinin ham dökümü verilmiştir:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Aşağıda, curl kullanılarak yapılan aynı istek yer almaktadır:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Yanıtı ele alma

JWT ve erişim jetonu isteği düzgün şekilde oluşturulmuşsa ve hizmet hesabının işlemi gerçekleştirme izni varsa yetkilendirme sunucusundan gelen JSON yanıtı bir erişim jetonu içerir. Aşağıda örnek bir yanıt verilmiştir:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Erişim jetonları, expires_in değeriyle belirtilen süre boyunca yeniden kullanılabilir.

Google API'lerini çağırma

Java

Aşağıdaki adımları tamamlayarak Google API'lerini çağırmak için GoogleCredentials nesnesini kullanın:

1. GoogleCredentials nesnesini kullanarak çağırmak istediğiniz API için bir hizmet nesnesi oluşturun. Örneğin:

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();

2. Hizmet nesnesi tarafından sağlanan arayüzü kullanarak API hizmetine istekte bulunun. Örneğin, exciting-example-123 projesindeki Cloud SQL veritabanı örneklerini listelemek için:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Aşağıdaki adımları tamamlayarak Google API'lerini çağırmak için yetkili Credentials nesnesini kullanın:

1. Çağırmak istediğiniz API için bir hizmet nesnesi oluşturun. API'nin adı ve sürümü ile yetkili Credentials nesnesiyle build işlevini çağırarak bir hizmet nesnesi oluşturursunuz. Örneğin, Cloud SQL Administration API'nin 1beta3 sürümünü çağırmak için:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Hizmet nesnesi tarafından sağlanan arayüzü kullanarak API hizmetine istekte bulunun. Örneğin, exciting-example-123 projesindeki Cloud SQL veritabanı örneklerini listelemek için:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Uygulamanız bir erişim jetonu aldıktan sonra, API'nin gerektirdiği erişim kapsamları verilmişse jetonu belirli bir hizmet hesabı veya kullanıcı hesabı adına Google API'sine çağrı yapmak için kullanabilirsiniz. Bunu yapmak için API'ye yapılan bir isteğe erişim jetonunu ekleyin. Bunun için access_token sorgu parametresini veya Authorization HTTP üstbilgisi Bearer değerini ekleyebilirsiniz. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üstbilgisi tercih edilir. Çoğu durumda, Google API'lerine yaptığınız çağrıları ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, Drive Files API'yi çağırırken).

Tüm Google API'lerini deneyebilir ve kapsamlarını OAuth 2.0 Playground'da görüntüleyebilirsiniz.

HTTP GET örnekleri

Authorization: Bearer HTTP üstbilgisi kullanılarak drive.files uç noktasına (Drive Files API) yapılan bir çağrı aşağıdaki gibi görünebilir. Kendi erişim jetonunuzu belirtmeniz gerektiğini unutmayın:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Aşağıda, access_token sorgu dizesi parametresi kullanılarak kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı verilmiştir:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl örnek

Bu komutları curl komut satırı uygulamasıyla test edebilirsiniz. HTTP üstbilgisi seçeneğinin (tercih edilen) kullanıldığı bir örneği aşağıda bulabilirsiniz:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Alternatif olarak sorgu dizesi parametresi seçeneğini de kullanabilirsiniz:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Erişim jetonlarının süresi dolduğunda

Google OAuth 2.0 yetkilendirme sunucusu tarafından verilen erişim jetonlarının süresi, expires_in değeriyle sağlanan süre sonunda dolar. Erişim jetonunun süresi dolduğunda uygulama başka bir JWT oluşturmalı, bunu imzalamalı ve başka bir erişim jetonu istemelidir.

JWT hata kodları

error alanı	error_description alanı	Anlamı	Çözüm
unauthorized_client	Unauthorized client or scope in request.	Alan genelinde yetki vermeyi kullanmaya çalışıyorsanız hizmet hesabı, kullanıcının alanının Yönetici Konsolu'nda yetkilendirilmemiştir.	Hizmet hesabının, Yönetici Konsolu'nun Alan genelinde yetki sayfasında sub talebindeki (alan) kullanıcı için yetkilendirildiğinden emin olun. Bu işlem genellikle birkaç dakika sürse de yetkilendirmenin Google Hesabınızdaki tüm kullanıcılara uygulanması 24 saati bulabilir.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Yönetici Konsolu'nda istemci kimliği (sayısal) yerine istemci e-posta adresi kullanılarak bir hizmet hesabı yetkilendirildi.	Yönetici Konsolu'ndaki Alan genelinde yetki sayfasında istemciyi kaldırın ve sayısal kimlikle yeniden ekleyin.
access_denied	(herhangi bir değer)	Alan genelinde yetki kullanıyorsanız istenen bir veya daha fazla kapsam Yönetici Konsolu'nda yetkilendirilmemiştir.	Hizmet hesabının, Yönetici Konsolu'nun Alan genelinde yetki sayfasında sub talebindeki (alan) kullanıcı için yetkilendirildiğinden ve JWT'nizin scope talebinde istediğiniz tüm kapsamları içerdiğinden emin olun. Bu işlem genellikle birkaç dakika sürse de yetkilendirmenin Google Hesabınızdaki tüm kullanıcılara uygulanması 24 saati bulabilir.
admin_policy_enforced	(herhangi bir değer)	Google Hesabı, Google Workspace yöneticisinin politikaları nedeniyle istenen bir veya daha fazla kapsamı yetkilendiremiyor.	Yöneticinin, OAuth istemci kimliğinize açıkça erişim izni verilene kadar tüm kapsamlara veya hassas ve kısıtlanmış kapsamlara erişimi nasıl kısıtlayabileceği hakkında daha fazla bilgi için Google Workspace Yönetici Yardım Merkezi'ndeki Google Workspace verilerine hangi üçüncü taraf ve dahili uygulamaların erişebileceğini yönetme başlıklı makaleyi inceleyin.
invalid_client	(herhangi bir değer)	OAuth istemcisi veya JWT jetonu geçersiz ya da yanlış yapılandırılmış. Ayrıntılar için hata açıklamasına bakın.	JWT jetonunun geçerli olduğundan ve doğru talepleri içerdiğinden emin olun. OAuth istemcisinin ve hizmet hesabının doğru şekilde yapılandırıldığını ve doğru e-posta adresini kullandığınızı kontrol edin. JWT jetonunun doğru olduğundan ve istekteki istemci kimliği için verildiğinden emin olun.
deleted_client	(herhangi bir değer)	İsteği göndermek için kullanılan OAuth istemcisi silinmiştir. Silme işlemi, kullanılmayan istemciler için manuel veya otomatik olarak yapılabilir. Silinen müşteriler, silme işleminden sonraki 30 gün içinde geri yüklenebilir. Daha fazla bilgi edinin.	Hâlâ etkin olan bir istemci kimliği kullanın.
invalid_grant	Not a valid email.	Kullanıcı mevcut değil.	sub talebindeki (alan) e-posta adresinin doğru olup olmadığını kontrol edin.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Bu genellikle yerel sistem saatinin doğru olmadığı anlamına gelir. Ayrıca, exp değeri, iat değerinden 65 dakika daha ileri bir zamanda veya exp değeri, iat değerinden düşükse de bu durum oluşabilir.	JWT'nin oluşturulduğu sistemdeki saatin doğru olduğundan emin olun. Gerekirse saatinizi Google NTP ile senkronize edin.
invalid_grant	Invalid JWT Signature.	JWT onayının, istemci e-postasıyla tanımlanan hizmet hesabıyla ilişkilendirilmemiş bir özel anahtarla imzalanması veya kullanılan anahtarın silinmesi, devre dışı bırakılması ya da süresinin dolması. Alternatif olarak, JWT onayının kodlaması yanlış olabilir. Yeni satırlar veya dolgu eşittir işaretleri olmadan Base64 olarak kodlanmalıdır.	JWT talebi kümesini kod çözün ve onaylamayı imzalayan anahtarın hizmet hesabıyla ilişkili olduğunu doğrulayın. JWT'nin doğru şekilde oluşturulduğundan emin olmak için Google tarafından sağlanan bir OAuth kitaplığı kullanmayı deneyin.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Kapsam istenmedi (boş kapsam listesi) veya istenen kapsamlar arasında mevcut olmayan (yani geçersiz) bir kapsam var.	JWT'nin scope talebinin (alan) doldurulduğundan emin olun ve hata ya da yazım hatası olmadığından emin olmak için içerdiği kapsamları, kullanmak istediğiniz API'lerin belgelenmiş kapsamlarıyla karşılaştırın. scope talebindeki kapsam listesinin virgülle değil boşluklarla ayrılması gerektiğini unutmayın.
disabled_client	The OAuth client was disabled.	JWT onayını imzalamak için kullanılan anahtar devre dışı.	Google API Consolebölümüne gidin ve IAM ve Yönetici > Hizmet Hesapları altında, onaylama işlemini imzalamak için kullanılan "Anahtar Kimliği"ni içeren hizmet hesabını etkinleştirin.
org_internal	This client is restricted to users within its organization.	İstekteki OAuth istemci kimliği, belirli bir Google Cloud kuruluşunda Google Hesaplarına erişimi sınırlayan bir projenin parçasıdır.	Kimlik doğrulamak için kuruluştan bir hizmet hesabı kullanın. OAuth uygulamanız için kullanıcı türü yapılandırmasını onaylayın.

Ek: OAuth olmadan hizmet hesabı yetkilendirme

Bazı Google API'lerinde, OAuth 2.0 erişim jetonu yerine doğrudan taşıyıcı jeton olarak imzalı bir JWT kullanarak yetkilendirilmiş API çağrıları yapabilirsiniz. Bu mümkün olduğunda, bir API çağrısı yapmadan önce Google'ın yetkilendirme sunucusuna ağ isteği göndermeniz gerekmez.

Çağırmak istediğiniz API'nin Google API'leri GitHub deposunda yayınlanmış bir hizmet tanımı varsa erişim jetonu yerine JWT kullanarak yetkilendirilmiş API çağrıları yapabilirsiniz. Bunu yapmak için:

1. Yukarıda açıklandığı şekilde hizmet hesabı oluşturun. Hesabı oluşturduğunuzda aldığınız JSON dosyasını sakladığınızdan emin olun.
2. jwt.io adresinde bulunanlar gibi standart bir JWT kitaplığı kullanarak aşağıdaki örnekteki gibi bir başlık ve yük içeren bir JWT oluşturun:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• Başlıktaki kid alanı için hizmet hesabınızın özel anahtar kimliğini belirtin. Bu değeri, hizmet hesabınızın JSON dosyasındaki private_key_id alanında bulabilirsiniz.
• iss ve sub alanlarında hizmet hesabınızın e-posta adresini belirtin. Bu değeri, hizmet hesabınızın JSON dosyasının client_email alanında bulabilirsiniz.
• aud alanı için API uç noktasını belirtin. Örneğin: https://SERVICE.googleapis.com/.
• iat alanı için geçerli Unix saatini, exp alanı için ise JWT'nin süresinin dolacağı, tam 3.600 saniye sonraki saati belirtin.

Hizmet hesabı JSON dosyanızda bulunan özel anahtarı kullanarak JWT'yi RSA-256 ile imzalayın.

Örneğin:

Java

google-auth-library-java ve java-jwt'yi kullanarak:

import com.google.auth.oauth2.ServiceAccountCredentials;
...
GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey();
String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

PyJWT kullanılarak:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. İmzalı JWT'yi taşıyıcı jeton olarak kullanarak API'yi çağırın:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com

Hesaplar Arası Koruma'yı uygulama

Kullanıcılarınızın hesaplarını korumak için atmanız gereken ek bir adım da Google'ın hesaplar arası koruma hizmetinden yararlanarak hesaplar arası korumayı uygulamaktır. Bu hizmet, kullanıcı hesabında yapılan önemli değişiklikler hakkında uygulamanıza bilgi sağlayan güvenlik etkinliği bildirimlerine abone olmanıza olanak tanır. Ardından, etkinliklere nasıl yanıt vereceğinize bağlı olarak işlem yapmak için bu bilgileri kullanabilirsiniz.

Google'ın hesaplar arası koruma hizmeti tarafından uygulamanıza gönderilen etkinlik türlerine ilişkin bazı örnekler:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Hesaplar Arası Koruma'yı uygulama ve kullanılabilir etkinliklerin tam listesi hakkında daha fazla bilgi için Hesaplar Arası Koruma ile kullanıcı hesaplarını koruma sayfasını inceleyin.