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. Buna OAuth tabanlı hesap bağlama, basitleştirilmiş hesap bağlama ve uygulama geçişi dahildir.

Ö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 İptali: RFC 7009 ile uyumludur.
  • JSON Web Jetonları (JWT): RFC 7519 ile uyumlu olmalıdır (Basitleştirilmiş 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önderdiğ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 boşlukla ayrılmış kapsam listesi.
user_locale (İsteğe bağlı) BCP-47 dil etiketi (ör. en-US) kullanılarak belirtilen Google Hesabı dil ayarı.

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 iç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.

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.

  • 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 oturum açma özelliğini içeren OAuth) destekliyorsa jeton değişimi uç noktanızın JSON Web Token (JWT) onaylarını da desteklemesi ve check, create ve get amaçları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 create.
grant_type Bu istekler için 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 gösterilir.
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 sunucunuz, aşağıdaki ölçütleri kullanarak assertion (JWT) doğrulamalıdır:

  • İmza: İmzayı Google'ın herkese açık anahtarlarıyla (Google'ın JWK uç noktasında bulunur) doğrulayın.
  • Kart Sağlayıcı (iss): https://accounts.google.com olmalıdır.
  • Kitle (aud): Entegrasyonunuza atanmış 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

intent=create ile yapılan bir istek, JWT'de sağlanan bilgilerle yeni bir kullanıcı hesabı oluşturulmasını ister.

  • 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 kullanıcıdan mevcut hesabını bağlamasını isteyen 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 "One Tap ile 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 bir 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 süreci 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ğlantı oluşturma 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 bir 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 silinemezse (ör. veritabanı kullanılamıyorsa) 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
  • Headers: Retry-After: <HTTP-date / delay-seconds>