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

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 adımlı 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.)

Daha fazla bilgi için Hizmet hesaplarıyla ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

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.

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 adı 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.

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 Consoleadresinden 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:

Öncelikle bir hizmet hesabı oluşturun:

  1. Service accounts pageuygulamasını açın.
  2. If prompted, select a project, or create a new one.
  3.  Hizmet hesabı oluştur'u tıklayın.
  4. Hizmet hesabı ayrıntıları bölümünde hizmet hesabı için bir ad, kimlik ve açıklama girip Oluştur ve devam et'i tıklayın.
  5. İsteğe bağlı: Bu hizmet hesabına projeye erişim izni ver bölümünde, hizmet hesabına verilecek IAM rollerini seçin.
  6. Devam'ı tıklayın.
  7. İsteğe bağlı: Kullanıcıların bu hizmet hesabına erişmelerine izin ver bölümünde, 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 adresini tıklayın.
  2. Anahtarlar sekmesini tıklayın.
  3. Anahtar ekle açılır listesinde Yeni anahtar oluştur'u seçin.
  4. Oluştur'u tıklayın.

Daha fazla bilgi edinmek için Hizmet hesabı anahtarlarını yönetmeyle ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

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 dilediğ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 bilgilere ihtiyacı vardır.

Hizmet hesabına alan genelinde yetki verme

Google Workspace hesabı 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 uygulamaya yetki verebilir. Ö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 bir hizmet hesabı kullanır. Bir hizmet hesabını, alandaki kullanıcılar adına verilere erişmesi için yetkilendirmeye bazen hizmet hesabına "alan genelinde yetki verme" adı verilir.

Alan genelinde yetkiyi bir hizmet hesabına devretmek 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 pageiçinde 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 yetkisine sahip (kullanıcıların "kimliğine bürünme"). Bu yetkilendirilmiş API çağrılarını yapmaya hazırlanırken kimliğine bürünülecek kullanıcıyı açıkça belirtirsiniz.

Yetkilendirilmiş API çağrısı yapma

Aşağıdaki bölümlerde, Google API'leri istemci kitaplığı kullanarak veya HTTP ile doğrudan OAuth 2.0 sistemiyle etkileşim kurarak yetkilendirilmiş bir API çağrısı yapma yöntemleri gösterilmektedir.

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("ServiceAccountKey.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Google Cloud'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 GoogleCredentials nesnesinin createDelegated yöntemiyle kullanıcı hesabının e-posta adresini belirtin. Örneğin:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("ServiceAccountKey.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

GoogleCredentials nesnesi, createDelegated() yöntemini çağırmak için kullanılı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/ServiceAccountKey.json'

credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    Google Cloud'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 mevcut bir with_subject nesnesinin ServiceAccountCredentials yöntemini kullanın. Örneğin:

    delegated_credentials = credentials.with_subject('user@example.org')

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

HTTP/REST

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.

Sunucu uygulamanız, Google yetkilendirme sunucusundan jeton istemek için JWT kullanır, ardından bir Google API uç noktasını çağırmak için jetonu kullanır. Son kullanıcı dahil değildir.
Şekil 1. Sunucu uygulamanız, Google yetkilendirme sunucusundan jeton istemek için JWT kullanır, ardından bir Google API uç noktasını çağırmak için jetonu kullanır. Son kullanıcı dahil değildir.

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 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 gibi oluşturulur:

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

İmza için temel dize şu şekildedir:

{Base64url encoded header}.{Base64url encoded claim set}
JWT üstbilgisini oluşturma

Üstbilgi, iki zorunlu alandan (imza algoritması ve onay biçimi) ve isteğe bağlı bir anahtar kimliğinden oluşur:

  • Algoritma zorunludur ve yalnızca tek bir değeri vardır: "alg": "RS256".
  • Biçim zorunludur ve yalnızca bir değeri vardır: "typ": "JWT".
  • Anahtar kimliği isteğe bağlıdır ve JWT'yi imzalamak için kullanılan hizmet hesabı anahtarının kimliğidir. Yanlış bir anahtar kimliği belirtilirse hizmet hesabıyla ilişkili tüm anahtarlar denenir. Geçerli bir anahtar bulunamazsa jeton reddedilir. Google, 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 talep kümesi de bir JSON nesnesidir ve imzanın hesaplanmasında kullanılır.

Gerekli hak talepleri

JWT talebi kümesindeki gerekli talepler, talep kümesinde herhangi bir sırada görünebilir.

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 bitimi 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.

Bu, JWT talep kümesindeki gerekli alanların JSON gösterimi örneğidir:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "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.

Bu, sub alanını içeren bir JWT talebi kümesi örneğidir:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
JWT talebi grubunu kodlama

JWT başlığı gibi, JWT talebi kümesi de UTF-8'e serileştirilmeli ve Base64url güvenli olarak kodlanmalıdır. Bu, JWT Claim Set'in JSON gösterimi örneğidir:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
İmzayı hesaplayın

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 imzalama 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 Console'dan 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}

Bu, Base64url kodlaması öncesindeki bir JWT örneğidir:

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

Bu, imzalanmış ve iletime hazır bir JWT örneğidir:

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. Örneğin:

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.

Bu, erişim jetonu isteğinde kullanılan HTTPS POST isteğinin ham dökümüdür:

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

curl kullanılarak yapılan aynı istek:

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 işleme

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.

Güvenlikle İlgili Önemli Husus: Kimliğe Bürünmeyi Anlama

Alan genelinde yetki verdiğinizde hizmet hesabına tüm kullanıcı verilerine doğrudan erişim izni vermezsiniz. Bunun yerine, API çağrıları yaparken belirli kullanıcıların kimliğine bürünmesine izin veriyorsunuz.
  • Kullanıcı Adına Erişim: Uygulamanız, her API isteği için hangi kullanıcının kimliğine bürüneceğini belirtmelidir. Uygulama daha sonra, yükseltilmiş veya alan genelinde ayrıcalıklar olmadan, söz konusu kullanıcının izinleriyle hareket eder.
  • İzinler Sınırlıdır: Hizmet hesabının erişimi iki faktörle sınırlanır: kimliğine bürünülen kullanıcının izinleri ve Yönetici Konsolu'nda yetkilendirdiğiniz OAuth kapsamları. Bu hizmet, kimliğine bürünülen kullanıcının erişemediği verilere erişemez.
  • En Az Ayrıcalık İlkesi: Bu özellik, kullanıcı verilerine doğrudan izinleri olmadan erişilmesine olanak tanıdığından güvenlik alanındaki en iyi uygulamalara uymak kritik önem taşır. Yalnızca gerekli OAuth kapsamlarını verin ve güvenlik üzerindeki etkilerini anladığınızdan emin olun.
Ayrıntılı güvenlik yönergeleri için Alan genelinde yetki verme ile ilgili en iyi uygulamalar başlıklı makaleyi inceleyin.

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 veritabanlarının ö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 veritabanlarının ö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 access_token sorgu parametresi veya Authorization HTTP üstbilgisi Bearer değeri ekleyerek erişim jetonunu API'ye yapılan bir isteğe dahil edin. 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 sub talebi (alanı) içindeki kullanıcı için Alan genelinde yetki sayfasında 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 veya yetkilendirme için bir Google Grubu kullanıldı. Yönetici Konsolu'ndaki Alan genelinde yetki sayfasında istemciyi kaldırın ve sayısal kimlikle yeniden ekleyin veya Google Grubu'nu kaldırıp tek tek hizmet ya da kullanıcı hesabı ile değiştirin.
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.

Tek tek denetlenemeyen hizmetlere erişimi yönetme başlıklı makaleyi inceleyerek Google hizmetlerine erişimin kısıtlanmadığını doğrulayın.

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 kapsamlar veya hassas ve kısıtlanmış kapsamlar için erişimi nasıl kısıtlayabileceği hakkında daha fazla bilgi edinmek için Google Workspace Yönetici Yardım Merkezi'ndeki Google Workspace verilerine hangi üçüncü taraf uygulamalar 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 olarak veya otomatik olarak gerçekleşebilir. 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 veya Invalid email or User ID. 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şkilendirilmeyen 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 kodunu çö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 veya 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ışı bırakılmış.

Google API Consolebölümüne gidin ve IAM & Admin > Service Accounts 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ğrulama 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, 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. 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": "123456-compute@developer.gserviceaccount.com",
  "sub": "123456-compute@developer.gserviceaccount.com",
  "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. Bu değer, istemciyi benzersiz şekilde tanımlar ve işlevsel olarak istemci kimliğidir.
    • aud alanı için API uç noktasını belirtin. Örneğin: https://SERVICE.googleapis.com/.
    • iat alanı için mevcut Unix sıfır zamanını, exp alanı için ise JWT'nin geçerliliğinin sona ereceği, tam 3.600 saniye sonraki zamanı 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 kullanma:

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("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .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': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           '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ı Korumayı 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.