Interfejs API do łączenia kont

Na tej stronie znajdziesz dokumentację punktów końcowych interfejsu API, które Twoja usługa musi wdrożyć, aby obsługiwać łączenie kont z Google. Obejmuje to połączenie konta przez OAuth, uproszczone połączenie konta i przełączanie aplikacji.

Wymagania wstępne i standardy

Aby prawidłowo zaimplementować te punkty końcowe, usługa musi spełniać te standardy:

  • OAuth 2.0: zgodny ze standardem RFC 6749.
  • Unieważnianie tokena: zgodne z RFC 7009.
  • Tokeny sieciowe JSON (JWT): zgodne z RFC 7519 (wymagane w przypadku uproszczonego łączenia).
  • HTTPS wszystkie punkty końcowe muszą być udostępniane przez bezpieczne połączenie HTTPS.

Authorization Endpoint (Punkt końcowy autoryzacji)

Punkt końcowy autoryzacji odpowiada za uwierzytelnianie użytkowników i uzyskiwanie ich zgody na połączenie kont z Google.

  • Adres URL: skonfigurowany w Konsoli Actions lub konsoli Google Cloud.
  • Metoda: GET

Parametry żądania

Parametry Opis
client_id Identyfikator klienta przypisany przez Ciebie do Google.
redirect_uri Adres URL, na który wysyłasz odpowiedź na to żądanie.
state Wartość księgowa przekazywana z powrotem do Google bez zmian w identyfikatorze URI przekierowania.
response_type W przypadku przepływu kodu autoryzacji musi to być code.
scope (Opcjonalnie) Lista zakresów oddzielonych spacjami, których Google żąda w przypadku danych.
user_locale (Opcjonalnie) Ustawienie języka konta Google określone za pomocą tagu języka BCP-47 (np. en-US).

Punkt końcowy wymiany tokenów

Ten punkt końcowy odpowiada za wymianę kodów autoryzacji na tokeny i odświeżanie wygasłych tokenów dostępu.

  • Adres URL: skonfigurowany w Konsoli Actions lub konsoli Google Cloud.
  • Metoda: POST
  • Content-Type: application/x-www-form-urlencoded

Wymiana kodu autoryzacji na tokeny

W początkowym żądaniu wymiany tokena używane są te parametry.

Parametry żądania

Parametry Opis
client_id Identyfikator klienta przypisany przez Ciebie do Google.
client_secret Tajny klucz klienta przypisany do Google.
grant_type Musi to być authorization_code.
code Kod autoryzacji otrzymany z punktu końcowego autoryzacji.
redirect_uri Ten sam identyfikator URI przekierowania, który został użyty w pierwotnym żądaniu.

Wymiana tokena odświeżania na token dostępu

Podczas odświeżania tokena dostępu używane są te parametry.

Parametry żądania

Parametry Opis
client_id Identyfikator klienta przypisany przez Ciebie do Google.
client_secret Tajny klucz klienta przypisany do Google.
grant_type Musi to być refresh_token.
refresh_token Token odświeżania wydany wcześniej Google.

Odpowiedź (JSON)

Zwróć odpowiedź o sukcesie z obiektem JSON w treści odpowiedzi HTTPS.

  • Stan HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
Pola Opis
token_type Wymagane. Musi to być bearer.
access_token Wymagane. Krótkotrwały token używany do uzyskiwania dostępu do interfejsów API usługi.
refresh_token Wymagany w przypadku authorization_code grant_type. Token o długim okresie ważności, który służy do uzyskiwania nowych tokenów dostępu.
expires_in Wymagane. Pozostały czas ważności tokena dostępu w sekundach.

Odpowiedzi z błędem

Jeśli żądanie do punktu końcowego tokena zakończy się niepowodzeniem, zwróć błąd HTTP 400 Bad Request wraz z odpowiedzią JSON zawierającą te pola:

  • Stan HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Pola błędów (JSON) Opis
error Wymagane. Musi to być invalid_grant.
error_description (Opcjonalnie) Tekst zrozumiały dla człowieka zawierający dodatkowe informacje.

Obsługa intencji uproszczonego łączenia

Jeśli Twoja usługa obsługuje uproszczone łączenie kont (protokół OAuth z Zaloguj się przez Google), punkt końcowy wymiany tokenów musi dodatkowo obsługiwać asercje tokena internetowego JSON (JWT) i wdrażać intencje check, create i get.

W tych żądaniach używane są te parametry:

Parametry żądania

Parametry Opis
intent Konkretna intencja uproszczonego linkowania: check, get lub create.
grant_type W przypadku tych żądań ten parametr ma zawsze wartość urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Token sieciowy JSON (JWT), który zawiera podpisaną deklarację tożsamości użytkownika Google. JWT zawiera informacje, w tym identyfikator konta Google użytkownika, jego imię i nazwisko oraz adres e-mail.

 Serwer musi zweryfikować ten token JWT zgodnie z kryteriami wymienionymi w sekcji Weryfikacja tokena JWT.
client_id Identyfikator klienta przypisany przez Ciebie do Google.
client_secret Tajny klucz klienta przypisany do Google.
scope Opcjonalnie: wszystkie zakresy, które zostały skonfigurowane tak, aby Google prosiło o nie użytkowników. Zwykle występuje w przypadku intencji get i create.
response_type Wymagane w przypadku intencji create: musi mieć wartość token.

Weryfikacja JWT

Aby zapewnić bezpieczeństwo uproszczonego łączenia, serwer musi zweryfikować token assertion (JWT) na podstawie tych kryteriów:

  • Podpis: sprawdź podpis za pomocą kluczy publicznych Google (dostępnych w punkcie końcowym JWK Google).
  • Wystawca (iss): musi być wartością https://accounts.google.com.
  • Odbiorcy (aud): musi być zgodny z identyfikatorem klienta Google API przypisanym do Twojej integracji.
  • Data wygaśnięcia (exp): musi być w przyszłości.

Odpowiedź na intencję check

Żądanie z parametrem intent=check sprawdza, czy konto Google (zidentyfikowane przez deklarację sub lub email w zdekodowanym potwierdzeniu JWT) istnieje w Twojej bazie danych użytkowników.

  • Stan HTTP: 200 OK (Konto znalezione) lub 404 Not Found (Konto nie zostało znalezione)
  • Content-Type: application/json;charset=UTF-8
Pola Opis
account_found Wymagane. true – jeśli konto istnieje, false – w przeciwnym razie.

Odpowiedź na intencję get

Żądanie z parametrem intent=get prosi o token dostępu do istniejącego konta Google.

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

Obiekt JSON z odpowiedzią w przypadku powodzenia ma dokładnie taką samą strukturę jak standardowa odpowiedź Token Exchange (zwraca access_token, refresh_token itp.).

Jeśli nie można połączyć konta, zwracany jest błąd HTTP 401.

  • Stan HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Pola błędów (JSON) Opis
error Wymagane. Musi to być linking_error.
login_hint (Opcjonalnie) Adres e-mail użytkownika, który ma zostać przekazany do rezerwowego procesu łączenia protokołu OAuth.

Odpowiedź na intencję create

Żądanie z parametrem intent=create powoduje utworzenie nowego konta użytkownika na podstawie informacji podanych w JWT.

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

Obiekt JSON z odpowiedzią w przypadku powodzenia ma dokładnie taką samą strukturę jak standardowa odpowiedź Token Exchange (zwraca access_token, refresh_token itp.).

Jeśli użytkownik już istnieje, zwracany jest błąd HTTP 401, aby poprosić użytkownika o połączenie istniejącego konta.

  • Stan HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Pola błędów (JSON) Opis
error Wymagane. Musi to być linking_error.
login_hint Adres e-mail użytkownika, który ma zostać przekazany do rezerwowego procesu łączenia OAuth.

Punkt końcowy UserInfo (opcjonalnie)

Służy do pobierania podstawowych informacji o profilu połączonego użytkownika zgodnie ze specyfikacją OpenID Connect Core 1.0. Jest to wymagane w przypadku funkcji takich jak „Uproszczone łączenie” czy „Logowanie jednym kliknięciem”.

  • Metoda: GET
  • Uwierzytelnianie: Authorization: Bearer ACCESS_TOKEN

Odpowiedź (JSON)

Zwróć odpowiedź o sukcesie z obiektem JSON w treści odpowiedzi HTTPS.

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

Pola odpowiedzi

Pola Opis
sub Wymagane. Unikalny identyfikator, który identyfikuje użytkownika w Twoim systemie.
email Wymagane. Adres e-mail użytkownika.
email_verified Wymagane. Wartość logiczna wskazująca, czy adres e-mail został zweryfikowany.
given_name (Opcjonalnie) Imię użytkownika.
family_name (Opcjonalnie) Nazwisko użytkownika.
name (Opcjonalnie) Pełne imię i nazwisko użytkownika.
picture (Opcjonalnie) Adres URL zdjęcia profilowego użytkownika.

Odpowiedzi z błędem

Jeśli token dostępu jest nieprawidłowy lub wygasł, zwróć błąd HTTP 401 Unauthorized. Należy też dodać nagłówek odpowiedzi WWW-Authenticate.

Każda nieudana odpowiedź (4xx lub 5xx) zwrócona podczas procesu łączenia jest uważana za nieodwracalną. W takich przypadkach Google odrzuci pobrane tokeny, a użytkownik będzie musiał ponownie rozpocząć proces łączenia kont.

Punkt końcowy cofnięcia tokena (opcjonalnie)

Umożliwia Google powiadamianie Twojej usługi, gdy użytkownik odłączy swoje konto od platformy Google. Ten punkt końcowy musi spełniać wymagania opisane w RFC 7009.

  • Metoda: POST
  • Content-Type: application/x-www-form-urlencoded

Parametry żądania

Parametry Opis
client_id Ciąg znaków, który identyfikuje źródło żądania jako Google. Ten ciąg znaków musi być zarejestrowany w Twoim systemie jako unikalny identyfikator Google.
client_secret Tajny ciąg znaków zarejestrowany w Google w przypadku Twojej usługi.
token Token do unieważnienia.
token_type_hint (Opcjonalnie) Wskazówka dotycząca typu unieważnianego tokena: access_token lub refresh_token. Jeśli nie podasz tu żadnej wartości, zostanie użyta wartość domyślna access_token.

Odpowiedzi

Zwróć odpowiedź o powodzeniu, gdy token zostanie usunięty lub gdy jest już nieprawidłowy.

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

Odpowiedzi z błędem

Jeśli z jakiegokolwiek powodu nie można usunąć tokena (np. z powodu niedostępności bazy danych), zwróć błąd HTTP 503. Google ponowi próbę później lub zgodnie z informacjami w nagłówku Retry-After.

  • Stan HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • Headers: Retry-After: <HTTP-date / delay-seconds>