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 łączenie przez OAuth, uproszczone łączenie kont 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 z 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.

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 Google Cloud Console.
  • 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 danych, o które prosi Google, rozdzielona spacjami.
user_locale (Opcjonalnie) Ustawienie języka konta Google określone za pomocą tagu języka BCP-47 (np. en-US).
code_challenge (Wymagane w przypadku OAuth 2.1) Wartość challenge pochodząca z weryfikatora kodu.
code_challenge_method (Opcjonalnie) Metoda użyta do wygenerowania testu (np. S256).

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 Google Cloud Console.
  • 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.
code_verifier (Wymagany w przypadku PKCE) Oryginalny kryptograficzny ciąg losowy.

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.

Schemat OpenAPI 3.1

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
  • 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 okres 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 czytelny dla człowieka zawierający dodatkowe informacje.

Obsługa intencji uproszczonego łączenia

Jeśli Twoja usługa obsługuje uproszczone łączenie kont (OAuth z logowaniem za pomocą Google), punkt końcowy wymiany tokenów musi dodatkowo obsługiwać asercje tokenów sieciowych JSON (JWT) i implementować wymagane intencje check i get oraz opcjonalnie intencję create.

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

Parametry żądania

Parametry Opis
intent Konkretna intencja uproszczonego łączenia, o którą prosisz: check, get lub opcjonalnie 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, o które Google ma prosić 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 JWT assertion 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.
  • Audience (aud): musi być zgodny z identyfikatorem klienta Google API przypisanym do Twojej integracji.
  • Data ważności (exp): musi być w przyszłości.

Odpowiedź na intencję check

Żądanie z parametrem intent=check sprawdza, czy konto Google (zidentyfikowane przez roszczenie 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 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 OAuth.

Odpowiedź na intencję create (opcjonalnie)

Intencja create jest opcjonalna. Jeśli Twoja usługa obsługuje tworzenie konta za pomocą uproszczonego łączenia, żądanie z parametrem intent=create inicjuje utworzenie nowego konta użytkownika z informacjami podanymi w tokenie JWT.

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

Obiekt JSON 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 lub Twoja usługa nie obsługuje tworzenia kont, zwracany jest błąd HTTP 401, aby nakłonić Google do powrotu do standardowej procedury łączenia OAuth.

  • 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) 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. Musisz 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. baza danych jest niedostępna), zwróć błąd HTTP 503. Google spróbuje ponownie później lub zgodnie z informacjami w nagłówku Retry-After.

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