Google Account Linking API

Na tej stronie referencyjnej znajdziesz dokumentację punktów końcowych i interfejsów oferowanych przez Google, z których korzysta Twoja aplikacja podczas procesu łączenia kont opartego na OAuth.

Wymagania wstępne i standardy

Aby skutecznie korzystać z tych punktów końcowych Google, integracja musi być zgodna z tymi standardami:

  • OAuth 2.0: zgodny z RFC 6749.
  • Tokeny internetowe JSON (JWT): zgodne z RFC 7519 (w przypadku uproszczonego łączenia kont i RISC).
  • Tokeny zdarzeń związanych z bezpieczeństwem: zgodne ze specyfikacją RFC 8417 (w przypadku RISC).
  • HTTPS wszystkie żądania muszą być wysyłane przez bezpieczne połączenie HTTPS.

Identyfikator URI przekierowania OAuth

Punkt końcowy, do którego usługa przekierowuje przeglądarkę użytkownika po pomyślnym uwierzytelnieniu i uzyskaniu zgody. Parametr YOUR_PARTNER_ID path to identyfikator partnera łączenia z kontem Google (lub identyfikator projektu) skonfigurowany podczas rejestracji.

  • URL: https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID

  • URL w piaskownicy: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_ID

  • Metoda: GET (za pomocą przekierowania w przeglądarce)

Parametry żądania

Podczas przekierowywania użytkownika z powrotem do Google do adresu URL muszą być dołączone parametry. W zależności od użytego przepływu OAuth parametry te są formatowane jako ciąg zapytania (przepływ kodu autoryzacji) lub fragment adresu URL (przepływ niejawny).

Parametr Opis
code (Wymagany w przypadku procedury kodu autoryzacji) Kod autoryzacji wygenerowany przez Twoją usługę.
state (Wymagane) Niezmodyfikowana wartość stanu otrzymana pierwotnie od Google.
access_token (Wymagany w przypadku przepływu niejawnego) Długotrwały token dostępu wygenerowany przez Twoją usługę.
token_type (Wymagane w przypadku przepływu niejawnego) Musi być równe bearer.

Odpowiedzi z błędem

Jeśli żądanie przekierowania do adresu URI OAuth ma nieprawidłowy format, otrzymasz błąd HTTP 400 Bad Request. Treść odpowiedzi będzie zawierać obiekt JSON o tej strukturze:

Pole Opis
sendPostBody Określa, czy JS ma przekierowywać do redirectUri za pomocą POST. W tym przypadku zwykle jest to false.
errorMessage Komunikat o błędzie, który ma być wyświetlany klientowi, gdy nie można dokończyć przekierowania. W przypadku brakujących fragmentów jest to "A URI fragment or query string must be set."

Odpowiedzi o błędach OAuth 2.0

Jeśli użytkownik odmówi wyrażenia zgody lub w usłudze wystąpi błąd, musi ona przekierować użytkownika z powrotem do identyfikatora URI przekierowania OAuth ze standardowymi parametrami błędu OAuth 2.0 (np. error=access_denied). Google przetworzy te parametry i wyświetli użytkownikowi odpowiedni ekran błędu.

Interfejs RISC API (opcjonalny)

Używany przez usługę do proaktywnego powiadamiania Google, gdy użytkownik odłączy konto na Twojej platformie za pomocą protokołu RISC. Dzięki temu obie platformy pozostają zsynchronizowane.

  • URL: https://risc.googleapis.com/v1/events:publish
  • Metoda: POST
  • Uwierzytelnianie: wymaga tokena konta usługi Google z odpowiednimi uprawnieniami.
  • Content-Type: application/json

Deklaracje tokenów zdarzeń związanych z bezpieczeństwem

Tokeny zdarzeń związanych z bezpieczeństwem, których używasz do powiadamiania Google o zdarzeniach odwołania tokena, muszą spełniać wymagania podane w tabeli poniżej:

Roszczenie Opis
iss Issuer Claim (Deklaracja wystawcy): to adres URL hostowany przez Ciebie, który jest udostępniany Google podczas rejestracji.
aud Oświadczenie dotyczące odbiorców: identyfikuje Google jako odbiorcę tokena JWT. Musi mieć wartość google_account_linking.
jti Roszczenie dotyczące identyfikatora JWT: jest to unikalny identyfikator generowany przez Ciebie dla każdego tokena zdarzenia związanego z bezpieczeństwem.
iat Issued At Claim: jest to wartość NumericDate, która reprezentuje czas utworzenia tego tokena zdarzenia związanego z bezpieczeństwem.
toe Time of Event Claim: to opcjonalna NumericDate wartość, która reprezentuje czas unieważnienia tokena.
exp Roszczenie dotyczące czasu wygaśnięcia: nie uwzględniaj tego pola, ponieważ zdarzenie, które spowodowało to powiadomienie, już się odbyło.
events Security Events Claim: to obiekt JSON, który musi zawierać tylko jedno zdarzenie unieważnienia tokena z tymi polami:

  • subject_type: musi mieć wartość oauth_token.
  • token_type: to typ unieważnianego tokena: access_token lub refresh_token.
  • token_identifier_alg: jest to algorytm używany do kodowania tokena. Musi to być hash_SHA512_double.
  • token: jest to identyfikator unieważnionego tokena.

Więcej informacji o typach i formatach pól znajdziesz w artykule Token internetowy JSON (JWT).

Interfejs „przejścia do aplikacji”

W przypadku przełączania aplikacji aplikacja mobilna musi zwrócić kod autoryzacji lub token dostępu do aplikacji Google.

Android (wynik intencji)

Aplikacja jest otwierana za pomocą intencji. Po uzyskaniu zgody kończy działanie i zwraca wynik do Google. Więcej informacji znajdziesz w przewodniku po implementacji na Androida.

  • Działanie: com.google.android.gms.auth.CODE_AVAILABLE
  • Dodatki: code, state, access_token, token_type.

Aplikacja otwiera Google za pomocą niestandardowego schematu URI adresu URL lub uniwersalnego linku HTTPS. Więcej informacji znajdziesz w przewodniku wdrażania na iOS.

  • Format: <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING