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

veya Cloud Platform ile ilgili olan veya kullandığınız bir Cloud belgesini açık bir şekilde yönetmediğiniz takdirde bu belgeyi Cloud'da açıkça kullanıyorsanız Cloud'da bulunan bir belgeyi yürütüyorsanız

Google OAuth 2.0 sistemi, bir web uygulaması ile Google hizmeti arasındaki etkileşimler gibi sunucular arası etkileşimleri destekler. Bu senaryoda hizmet hesabına ihtiyacınız vardır. Bu hesap, bireysel son kullanıcı yerine uygulamanıza ait bir hesaptır. Uygulamanız, hizmet hesabı adına Google API'lerini çağırdığından kullanıcılar doğrudan dahil olmaz. Bu senaryo bazen "iki aşamalı OAuth" veya "2LO" olarak adlandırılır. (İlgili "üç aşamalı OAuth" terimi, uygulamanızın son kullanıcılar adına Google API'lerini çağırdığı ve bazen kullanıcı izninin gerekli olduğu senaryoları ifade eder.)

Uygulama, kullanıcının verileri yerine kendi verileriyle çalışmak için Google API'lerini kullandığında genellikle uygulamalar hizmet hesabı kullanır. Örneğin, veri kalıcılığı 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ından yararlanır.

Google Workspace alan yöneticileri, hizmet hesaplarına alan genelinde yetki vererek, alandaki kullanıcılar adına kullanıcı verilerine erişme yetkisi verebilir.

Bu dokümanda, 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 amacıyla öncelikle API Consoleüzerinde 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.

Hizmet hesabı oluşturma

Bir hizmet hesabının kimlik bilgileri, benzersiz ve en az bir ortak/özel anahtar çifti oluşturarak oluşturulmuş bir e-posta adresini içerir. Alan genelinde yetki etkinleştirilmişse hizmet hesabının kimlik bilgilerine istemci kimliği de eklenir.

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

Uygulamanız Google Compute Engine'de çalışıyorsa projenizi oluşturduğunuzda otomatik olarak bir hizmet hesabı da ayarlanır. 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 için bir örneği hazırlama bölümüne bakın.

Uygulamanız Google App Engine veya Google Compute Engine'de çalışmıyorsa bu kimlik bilgilerini Google API Consoleüzerinden 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 uygulamasına dönebilirsiniz. API Consolehizmetindeki hizmet hesabı kimlik bilgileri hakkında daha fazla bilgiyi API Consoleyardım dosyasındaki Hizmet hesapları bölümünde bulabilirsiniz.

Hizmet hesabının e-posta adresini not edin ve hizmet hesabının özel anahtar dosyasını, uygulamanızın erişebildiği bir konumda saklayın. Yetkilendirilmiş API çağrıları yapmak için uygulamanızın bu bilgilere ihtiyacı vardır.

Hizmet hesabına alan genelinde yetki verme

Kuruluşun Workspace yöneticisi, Google Workspace hesabı kullanarak bir uygulamayı Google Workspace alanındaki kullanıcılar adına Workspace kullanıcı verilerine erişmesi için yetkilendirebilir. Örneğin, bir Google Workspace alanındaki tüm kullanıcıların takvimlerine etkinlik eklemek için Google Calendar API'yi kullanan bir uygulama, kullanıcılar adına Google Calendar API'ye erişmek için bir hizmet hesabı kullanır. Bir hizmet hesabının, bir alandaki kullanıcılar adına verilere erişmesi için yetkilendirilmesi, bazen "alan genelinde yetki verme" olarak da ifade edilir.

Bir hizmet hesabına alan genelinde yetki vermek için Google Workspace alanının süper yöneticisinin aşağıdaki adımları tamamlaması gerekir:

  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önet'i seçin.
  3. Yeni ekle'yi tıklayın.
  4. İstemci Kimliği alanına hizmet hesabının İstemci Kimliği'ni 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'ye ve Google Calendar API'ye alan genelinde tam erişime ihtiyacı varsa şunu 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ızda kullanıcılar olarak ("kullanıcıların kimliğine bürünmek" amacıyla) API çağrıları yapma yetkisine sahiptir. Yetki verilmiş bu API çağrılarını gerçekleştirmeye hazırlanırken, kimliğine bürünülecek kullanıcıyı açıkça belirtirsiniz.

Yetki verilmiş bir API çağrısı yapmaya hazırlanma

Java

API Consoleüzerinden istemci e-posta adresini ve özel anahtarı aldıktan sonra, Java için Google API'leri İstemci Kitaplığı'nı kullanarak hizmet hesabının kimlik bilgilerinden ve uygulamanızın erişmesi gereken kapsamlardan bir GoogleCredential nesnesi oluşturun. Örneğin:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.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 da süreci kolaylaştırabilir.

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 GoogleCredential nesnesinin createDelegated yöntemini kullanarak kullanıcı hesabının e-posta adresini belirtin. Örneğin:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

Yukarıdaki kod, createDelegated() yöntemini çağırmak için GoogleCredential nesnesini kullanır. createDelegated() yönteminin bağımsız değişkeni, 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 Consoleüzerinden istemci e-posta adresini ve özel anahtarı aldıktan sonra, Python için Google API'leri İstemci Kitaplığı'nı kullanarak aşağıdaki adımları tamamlayın:

  1. Hizmet hesabının kimlik bilgilerinden ve uygulamanızın erişmesi gereken kapsamlardan 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 da süreci kolaylaştırabilir.

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

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

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

HTTP/REST

İstemci kimliğini ve özel anahtarı API Consoleüzerinden aldıktan sonra uygulamanızın aşağıdaki adımları tamamlaması gerekir:

  1. Başlık, hak talebi grubu ve imza içeren bir JSON Web Jetonu (JWT, "jot" şeklinde telaffuz edilir) oluşturun.
  2. Google OAuth 2.0 Yetkilendirme Sunucusu'ndan erişim jetonu isteyin.
  3. Yetkilendirme Sunucusu'nun 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ıtta erişim jetonu varsa Google API'si çağırmak için erişim jetonunu kullanabilirsiniz. (Yanıtta erişim jetonu yoksa JWT ve jeton isteğiniz düzgün şekilde biçimlendirilmemiş olabilir veya hizmet hesabının istenen kapsamlara erişim 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 Sunucusu'ndan jeton istemek için bir JWT kullanır, daha sonra bu jetonu bir Google API uç noktası çağırmak için kullanır. Bu sürece 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ı ele alma konuları ele alınmaktadır.

JWT oluşturma

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

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

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

İmzanın temel dizesi aşağıdaki gibidir:

{Base64url encoded header}.{Base64url encoded claim set}
JWT başlığını oluşturma

Başlık; imzalama algoritmasını, onaylamanın 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) gösteren üç alandan oluşur. Algoritma ve biçim zorunludur ve her alanda yalnızca bir değer bulunur. Yeni algoritmalar ve biçimler kullanıma sunuldukça bu başlık da uygun şekilde değişir. Anahtar kimliği isteğe bağlıdır. 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 jetonu biçimini kullanır. Sonuç olarak, başlığın JSON gösterimi aşağıdaki gibi olur:

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

Bunun Base64url gösterimi aşağıdaki gibidir:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
JWT talebi grubunu oluşturma

JWT hak talebi grubu; istenen izinler (kapsamlar), jetonun hedefi, kartı veren, jetonun verildiği zaman ve jetonun kullanım ömrü dahil olmak üzere JWT hakkında bilgiler içerir. Alanların çoğu zorunludur. JWT başlığı gibi JWT hak talebi grubu da bir JSON nesnesidir ve imzanın hesaplanmasında kullanılır.

Gerekli hak talepleri

JWT hak talebi grubundaki gerekli hak talepleri aşağıda gösterilmektedir. Bu hak talebi kümesindeki 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 sınırlandırı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 süresi, 1 Ocak 1970 tarihinde 00:00:00 (UTC) itibarıyla saniye olarak belirtilir. Bu değer, yayınlanan zamandan en fazla 1 saat sonra olabilir.
iat Onayın verildiği zaman. 1 Ocak 1970, 00:00:00 (UTC) itibarıyla saniye olarak belirtilir.

Bir JWT talebi grubundaki gerekli alanların JSON gösterimi aşağıda gösterilmiştir:

{
  "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 uygulama, kuruluştaki belirli bir kullanıcı adına hareket etmek için alan genelinde yetkiyi kullanabilir. Bir uygulamanın bir kullanıcının kimliğine bürünebilmesi için önce bu tür kimliğe bürünme izni verilmelidir. Bu izin genellikle 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 bir erişim jetonu almak için kullanıcının e-posta adresini, sub alanının değeri olarak ayarlanan JWT talebine ekleyin.

Ad Açıklama
sub Uygulamanın yetki verilmiş erişim istediği kullanıcının e-posta adresi.

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

sub alanını içeren bir JWT talep grubu örneği aşağıda gösterilmiştir:

{
  "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 hak talebi grubunu kodlama

JWT üstbilgisi gibi, JWT hak talebi grubu da UTF-8 olarak serileştirilip Base64url olarak güvenli şekilde kodlanmalıdır. Aşağıda, bir JWT Hak Talebi grubunun JSON gösterimi örneği verilmiştir:

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

JSON Web Signature (JWS), JWT için imza oluşturma mekanizmasına rehberlik eden bir spesifikasyondur. İmzanın girdisi, aşağıdaki içeriğin bayt dizisidir:

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

İmza hesaplanırken JWT başlığındaki imzalama algoritması kullanılmalıdır. Google OAuth 2.0 Yetkilendirme Sunucusu tarafından desteklenen tek imzalama algoritması, SHA-256 karma oluşturma algoritmasını kullanan RSA'dır. JWT başlığındaki alg alanında RS256 olarak ifade edilir.

SHA256 ileRSA (SHA-256 karma işleviyle RSASSA-PKCS1-V1_5-SIGN olarak da bilinir) kullanarak girişin UTF-8 gösterimini, Google API Console'den alınan özel anahtarla imzalayın. Çıktı bir bayt dizisi olur.

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

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

Aşağıda Base64url kodlamasından önceki bir JWT örneği verilmiştir:

{"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]

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

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

Erişim jetonu isteğinde bulunma

İmzalanmış JWT'yi oluşturduktan sonra, bir uygulama bu JWT'yi kullanarak bir erişim jetonu isteyebilir. Bu erişim jetonu isteği bir HTTPS POST isteğidir ve gövde URL kodlamalıdır. 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 Aşağıdaki dizeyi kullanın (gerektiği şekilde URL kodlamalı): 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ü yer almaktadı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

Aynı istek, curl kullanılarak aşağıdaki gibidir:

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 biçimlendirilmişse ve hizmet hesabının işlemi gerçekleştirme izni varsa Yetkilendirme Sunucusu'ndan 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 aralığı boyunca yeniden kullanılabilir.

Google API'lerini çağırma

Java

Aşağıdaki adımları tamamlayarak GoogleCredential nesnesini kullanarak Google API'lerini çağırın:

  1. GoogleCredential nesnesini kullanarak çağırmak istediğiniz API için bir hizmet nesnesi oluşturun. Örneğin:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Hizmet nesnesinin sağladığı arayüzü kullanarak API hizmetine istek gönderin. Örneğin, heyecan verici-örnek-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 derlersiniz. Ö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 nesnesinin sağladığı arayüzü kullanarak API hizmetine istek gönderin. Örneğin, heyecan verici-örnek-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 bu jetonu belirli bir hizmet hesabı veya kullanıcı hesabı adına çağrı yapmak için kullanabilirsiniz. Bunu yapmak için access_token sorgu parametresi veya Authorization HTTP üst bilgisi Bearer değeri ekleyerek API'ye yapılan bir isteğe erişim jetonunu dahil edin. Sorgu dizeleri sunucu günlüklerinde görünür olduğundan mümkün olduğunda HTTP üst bilgisi tercih edilir. Çoğu durumda, Google API'lerine yönelik çağrılarınızı ayarlamak için bir istemci kitaplığı kullanabilirsiniz (örneğin, Drive Files API'yi çağırırken).

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

HTTP GET örnekleri

Authorization: Bearer HTTP üst bilgisini kullanan 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

Burada, access_token sorgu dizesi parametresi kullanılarak kimliği doğrulanmış kullanıcı için aynı API'ye yapılan bir çağrı gösterilmektedir:

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

curl örnekleri

Bu komutları, curl komut satırı uygulamasıyla test edebilirsiniz. HTTP başlığı seçeneğinin kullanıldığı bir örneği burada bulabilirsiniz (tercih edilen):

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

Alternatif olarak, sorgu dizesi parametresi seçeneği:

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ğeri ile sağlanan süre sonunda dolar. Bir 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 kullanmaya çalışıyorsanız hizmet hesabı, kullanıcının alanının Yönetici konsolunda yetkilendirilmemiş demektir.

Hizmet hesabının, Yönetici Konsolu'nun sub hak talebinde (alan) 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. Bir hizmet hesabı, Yönetici Konsolu'nda istemci kimliği (sayısal) yerine istemci e-posta adresi kullanılarak yetkilendirilmiştir. 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 kapsamlardan biri veya daha fazlası Yönetici Konsolu'nda yetkilendirilmemiştir.

Hizmet hesabının, Yönetici Konsolu'nun sub hak talebinde (alanında) bulunan kullanıcı için Alan genelinde yetki sayfasında yetkilendirildiğinden ve JWT ile ilgili 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.

Bir 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 verilerine hangi üçüncü taraf uygulamalar ve dahili uygulamaların erişebileceğini yönetme başlıklı Google Workspace Yöneticisi yardım makalesine göz atın.

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 hak taleplerini içerdiğinden emin olun.

OAuth istemcisi ve hizmet hesabının doğru yapılandırıldığından ve doğru e-posta adresini kullandığınızdan emin olun.

JWT jetonunun doğru olduğundan ve istekteki istemci kimliği için verilip verilmediğini kontrol edin.

invalid_grant Not a valid email. Kullanıcı mevcut değil. sub talebinde (alandaki) 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.

Genellikle bu, yerel sistem saatinin doğru olmadığı anlamına gelir. exp değeri iat değerinden sonra 65 dakikadan fazlaysa veya exp değeri iat değerinden düşükse de bu durum görülebilir.

JWT'nin oluşturulduğu sistemdeki saatin doğru olduğundan emin olun. Gerekirse zamanınızı Google NTP ile senkronize edin.

invalid_grant Invalid JWT Signature.

JWT onayı, istemci e-postası tarafından tanımlanan hizmet hesabıyla ilişkili olmayan bir özel anahtarla imzalandı veya kullanılan anahtar silinmiş, devre dışı bırakılmış veya süresi dolmuş.

Alternatif olarak, JWT onayı yanlış kodlanmış olabilir. Yeni satır veya dolgu eşit işareti olmadan Base64 olarak kodlanmış olmalıdır.

JWT hak talebi grubunun kodunu çözün ve onayı 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 OAuth kitaplığını kullanmayı deneyin.

invalid_scope Invalid OAuth scope or ID token audience provided. Hiçbir kapsam istenmedi (boş kapsam listesi) veya istenen kapsamlardan biri yok (yani geçersiz).

JWT'nin scope talebinin (alanı) doldurulduğundan emin olun ve içerdiği kapsamları, kullanmak istediğiniz API'lerin belgelenen kapsamlarıyla karşılaştırarak hata veya yazım hatası olmadığından emin olun.

scope talebindeki kapsamlar listesinin virgülle değil, boşlukla 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 Consoleöğesine gidin ve IAM ve Yönetici > Hizmet Hesapları altında, onayı 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şu'ndaki Google Hesaplarına erişimi sınırlayan bir projenin parçasıdır.

Kimlik doğrulama için kuruluşa ait bir hizmet hesabını kullanın. OAuth uygulamanızın kullanıcı türü yapılandırmasını onaylayın.

Ek: OAuth olmadan hizmet hesabı yetkilendirmesi

Bazı Google API'lerinde, OAuth 2.0 erişim jetonu yerine doğrudan hamiline ait jeton olarak imzalanmış bir JWT kullanarak yetkili API çağrıları yapabilirsiniz. Bu mümkün olduğunda, API çağrısı yapmadan önce Google'ın yetkilendirme sunucusuna bir ağ isteği göndermekten kaçınabilirsiniz.

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

  1. Yukarıda açıklanan şekilde bir hizmet hesabı oluşturun. Hesabı oluştururken aldığınız JSON dosyasını sakladığınızdan emin olun.
  2. jwt.io adresindeki gibi standart bir JWT kitaplığını kullanarak başlık ve yük ile aşağıdaki örnekteki gibi 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ında hizmet hesabınızın özel anahtar kimliğini belirtin. Bu değeri, hizmet hesabı JSON dosyanızın private_key_id alanında bulabilirsiniz.
    • iss ve sub alanları için hizmet hesabınızın e-posta adresini belirtin. Bu değeri, hizmet hesabı JSON dosyanızın client_email alanında bulabilirsiniz.
    • aud alanında API uç noktasını belirtin. Örneğin: https://SERVICE.googleapis.com/.
    • iat alanı için mevcut Unix saatini, exp alanında ise JWT'nin süresinin tam olarak 3.600 saniye sonra dolacağı zamanı belirtin.

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

Örneğin:

Java

google-api-java-client ve java-jwt kullanarak:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

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

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. İmzalanmış JWT'yi hamiline ait 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