Hesap Bağlama API'niz

Bu referans sayfasında, hizmetinizin Google ile hesap bağlama özelliğini desteklemek için uygulaması gereken API uç noktaları açıklanmaktadır. OAuth bağlama, Basitleştirilmiş Hesap Bağlama ve Uygulama Geçişi bu özellikler arasındadır.

Ön koşullar ve standartlar

Bu uç noktaları başarıyla uygulamak için hizmetinizin aşağıdaki standartlara uyması gerekir:

  • OAuth 2.0: RFC 6749 ile uyumludur.
  • Jeton iptali: RFC 7009 ile uyumludur.
  • JSON Web Jetonları (JWT): RFC 7519 ile uyumludur (Kolaylaştırılmış Bağlantı için gereklidir).
  • HTTPS: Tüm uç noktalar güvenli bir HTTPS bağlantısı üzerinden sunulmalıdır.

Yetkilendirme Uç Noktası

Yetkilendirme uç noktası, kullanıcıların kimliğini doğrulamaktan ve hesaplarını Google'a bağlamaları için kullanıcı iznini almaktan sorumludur.

  • URL: Actions Console veya Google Cloud Console'da yapılandırılır.
  • Yöntem: GET

İstek Parametreleri

Parametreler Açıklama
client_id Google'a atadığınız istemci kimliği.
redirect_uri Bu isteğe verilen yanıtı göndereceğiniz URL.
state Yönlendirme URI'sinde Google'a değiştirilmeden geri iletilen bir muhasebe değeri.
response_type Yetkilendirme kodu akışı için code olmalıdır.
scope (İsteğe bağlı) Google'ın istediği veriler için kapsamların boşlukla ayrılmış listesi.
user_locale (İsteğe bağlı) BCP-47 dil etiketi (ör. en-US) kullanılarak belirtilen Google Hesabı dil ayarı.
code_challenge (OAuth 2.1 için zorunlu) Kod doğrulayıcıdan türetilen sorgu.
code_challenge_method (İsteğe bağlı) Meydan okumayı türetmek için kullanılan yöntem (ör. S256).

Jeton Değişimi Uç Noktası

Bu uç nokta, yetkilendirme kodlarını jetonlarla değiştirmekten ve süresi dolmuş erişim jetonlarını yenilemekten sorumludur.

  • URL: Actions Console veya Google Cloud Console'da yapılandırılır.
  • Yöntem: POST
  • Content-Type: application/x-www-form-urlencoded

Jetonlar İçin Yetkilendirme Kodu Değiş Tokuşu Yapma

İlk jeton değişimi isteğinde aşağıdaki parametreler kullanılır.

İstek Parametreleri

Parametreler Açıklama
client_id Google'a atadığınız istemci kimliği.
client_secret Google'a atadığınız istemci gizli anahtarı.
grant_type authorization_code olmalıdır.
code Yetkilendirme uç noktasından alınan yetkilendirme kodu.
redirect_uri İlk istekte kullanılan yönlendirme URI'si.
code_verifier (PKCE için gereklidir) Orijinal şifreleme rastgele dizesi.

Yenileme jetonunu erişim jetonuyla değiştirme

Erişim jetonu yenilenirken aşağıdaki parametreler kullanılır.

İstek Parametreleri

Parametreler Açıklama
client_id Google'a atadığınız istemci kimliği.
client_secret Google'a atadığınız istemci gizli anahtarı.
grant_type refresh_token olmalıdır.
refresh_token Google'a daha önce verilmiş olan yenileme jetonu.

Yanıt (JSON)

HTTPS yanıtının gövdesinde bir JSON nesnesiyle başarılı bir yanıt döndürün.

OpenAPI 3.1 Şeması

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • HTTP Durumu: 200 OK
  • Content-Type: application/json;charset=UTF-8
Alanlar Açıklama
token_type Zorunlu. bearer olmalıdır.
access_token Zorunlu. Hizmetinizin API'lerine erişmek için kullanılan kısa ömürlü bir jeton.
refresh_token authorization_code grant_type için gereklidir. Yeni erişim jetonları almak için kullanılan uzun ömürlü bir jeton.
expires_in Zorunlu. Erişim jetonunun kalan kullanım ömrü (saniye cinsinden).

Hata Yanıtları

Jeton uç noktasına yapılan istek başarısız olursa aşağıdaki alanları içeren bir JSON yanıtıyla birlikte HTTP 400 Bad Request hatasını döndürün:

  • HTTP Durumu: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Hata alanları (JSON) Açıklama
error Zorunlu. invalid_grant olmalıdır.
error_description (İsteğe bağlı) Ek bilgi sağlayan, insanlar tarafından okunabilir metin.

Kolaylaştırılmış Bağlantı Oluşturma Amaçlarını İşleme

Hizmetiniz Basitleştirilmiş Hesap Bağlama'yı (Google ile Giriş özelliğiyle OAuth) destekliyorsa jeton değişimi uç noktanızın ek olarak JSON Web Token (JWT) onaylarını desteklemesi, gerekli check ve get amaçlarını ve isteğe bağlı olarak create amacını uygulaması gerekir.

Bu isteklerde aşağıdaki parametreler kullanılır:

İstek Parametreleri

Parametreler Açıklama
intent İstenen belirli basitleştirilmiş bağlantı oluşturma amacı: check, get veya isteğe bağlı create.
grant_type Bu isteklerde, bu parametre her zaman urn:ietf:params:oauth:grant-type:jwt-bearer değerine sahiptir.
assertion Google kullanıcısının kimliğinin imzalı onayını sağlayan bir JSON Web Token (JWT). JWT, kullanıcının Google Hesabı kimliği, adı ve e-posta adresi gibi bilgileri içerir.

Sunucunuz, bu JWT'yi JWT Doğrulaması bölümünde listelenen ölçütleri kullanarak doğrulamalıdır.
client_id Google'a atadığınız istemci kimliği.
client_secret Google'a atadığınız istemci gizli anahtarı.
scope İsteğe bağlı: Google'ın kullanıcılardan istemesi için yapılandırdığınız tüm kapsamlar. Genellikle get ve create amaçlarında bulunur.
response_type create amacı için zorunlu: token olarak ayarlanmalıdır.

JWT Doğrulaması

Basitleştirilmiş bağlantının güvenliğini sağlamak için sunucunuzun aşağıdaki ölçütleri kullanarak assertion (JWT) doğrulaması gerekir:

  • İmza: İmzayı Google'ın herkese açık anahtarlarıyla (Google'ın JWK uç noktasında bulunur) doğrulayın.
  • Veren (iss): https://accounts.google.com olmalıdır.
  • Kitle (aud): Entegrasyonunuza atanan Google API istemci kimliğiyle eşleşmelidir.
  • Geçerlilik bitiş tarihi (exp): Gelecekte olmalıdır.

check amacı için yanıt

intent=check içeren bir istek, Google Hesabı'nın (kod çözülmüş JWT onayındaki sub veya email talebiyle tanımlanır) kullanıcı veritabanınızda olup olmadığını doğrular.

  • HTTP Durumu: 200 OK (Hesap bulundu) veya 404 Not Found (Hesap bulunamadı)
  • Content-Type: application/json;charset=UTF-8
Alanlar Açıklama
account_found Zorunlu. Hesap varsa true, yoksa false.

get amacı için yanıt

intent=get ile yapılan bir istek, mevcut bir Google Hesabı için erişim jetonu istiyor.

  • HTTP Durumu: 200 OK
  • Content-Type: application/json;charset=UTF-8

Başarılı yanıt JSON nesnesi, başarılı bir standart jeton değişimi yanıtıyla (access_token, refresh_token vb. döndüren) aynı yapıyı kullanır.

Hesap bağlanamazsa HTTP 401 hatası döndürülür.

  • HTTP Durumu: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Hata alanları (JSON) Açıklama
error Zorunlu. linking_error olmalıdır.
login_hint (İsteğe bağlı) Yedek OAuth bağlantı akışına iletilecek kullanıcının e-posta adresi.

create amacı için yanıt (isteğe bağlı)

create amacı isteğe bağlıdır. Hizmetiniz, Basitleştirilmiş Bağlantı kullanılarak hesap oluşturmayı destekliyorsa intent=create içeren bir istek, JWT'de sağlanan bilgilerle yeni bir kullanıcı hesabı oluşturma işlemini başlatır.

  • HTTP Durumu: 200 OK
  • Content-Type: application/json;charset=UTF-8

Başarılı yanıt JSON nesnesi, başarılı bir standart jeton değişimi yanıtıyla (access_token, refresh_token vb. döndüren) aynı yapıyı kullanır.

Kullanıcı zaten varsa veya hizmetiniz hesap oluşturmayı desteklemiyorsa Google'ın standart OAuth bağlantı akışına geri dönmesini istemek için bir HTTP 401 hatası döndürülür.

  • HTTP Durumu: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Hata alanları (JSON) Açıklama
error Zorunlu. linking_error olmalıdır.
login_hint Yedek OAuth bağlantı akışına iletilecek kullanıcının e-posta adresi.

UserInfo uç noktası (isteğe bağlı)

OpenID Connect Core 1.0 spesifikasyonunda belirtildiği gibi, bağlı kullanıcıyla ilgili temel profil bilgilerini almak için kullanılır. Bu, "Basitleştirilmiş Bağlantı" veya "Tek Dokunuşla Oturum Açma" gibi özellikler için gereklidir.

  • Yöntem: GET
  • Kimlik doğrulama: Authorization: Bearer ACCESS_TOKEN

Yanıt (JSON)

HTTPS yanıtının gövdesinde bir JSON nesnesiyle başarılı bir yanıt döndürün.

  • HTTP Durumu: 200 OK
  • Content-Type: application/json;charset=UTF-8

Yanıt Alanları

Alanlar Açıklama
sub Zorunlu. Sisteminizde kullanıcıyı tanımlayan benzersiz kimlik.
email Zorunlu. Kullanıcının e-posta adresi.
email_verified Zorunlu. E-posta adresinin doğrulanıp doğrulanmadığını belirten bir boole değeri.
given_name (İsteğe bağlı) Kullanıcının adı.
family_name (İsteğe bağlı) Kullanıcının soyadı.
name (İsteğe bağlı) Kullanıcının tam adı.
picture (İsteğe bağlı) Kullanıcının profil resminin URL'si.

Hata Yanıtları

Erişim jetonu geçersizse veya süresi dolmuşsa HTTP 401 Unauthorized hatası döndürün. WWW-Authenticate yanıt başlığını da eklemeniz gerekir.

Bağlantı oluşturma işlemi sırasında döndürülen başarısız yanıtlar (4xx veya 5xx) kurtarılamaz olarak kabul edilir. Bu durumlarda Google, alınan tüm jetonları siler ve kullanıcının hesap bağlama sürecini tekrar başlatması gerekir.

Jeton İptali Uç Noktası (İsteğe Bağlı)

Kullanıcının hesabının Google yüzeyinden bağlantısını kaldırması durumunda Google'ın hizmetinize bildirim göndermesine olanak tanır. Bu uç nokta, RFC 7009'da açıklanan koşulları karşılamalıdır.

  • Yöntem: POST
  • Content-Type: application/x-www-form-urlencoded

İstek Parametreleri

Parametreler Açıklama
client_id İstek kaynağını Google olarak tanımlayan bir dize. Bu dize, sisteminizde Google'ın benzersiz tanımlayıcısı olarak kaydedilmelidir.
client_secret Hizmetiniz için Google'a kaydettirdiğiniz gizli dize.
token İptal edilecek jeton.
token_type_hint (İsteğe bağlı) İptal edilen jetonun türüyle ilgili ipucu (access_token veya refresh_token). Belirtilmezse varsayılan olarak access_token olur.

Yanıtlar

Jeton başarıyla silindiğinde veya jeton zaten geçersizse başarılı bir yanıt döndürün.

  • HTTP Durumu: 200 OK
  • Content-Type: application/json;charset=UTF-8

Hata Yanıtları

Jeton herhangi bir nedenle (ör. veritabanı kullanılamaması) silinemiyorsa HTTP 503 hatası döndürün. Google, isteği daha sonra veya Retry-After üstbilgisinde belirtildiği şekilde yeniden dener.

  • HTTP Durumu: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • Başlıklar: Retry-After: <HTTP-date / delay-seconds>