Google Account Linking API

Ta strona referencyjna zawiera dokumentację punktów końcowych i interfejsów oferowanych przez Google, z których korzysta Twoja aplikacja podczas procesu łączenia kont na podstawie OAuth.

Wymagania wstępne i standardy

Aby korzystać z tych punktów końcowych Google, integracja musi spełniać te standardy:

  • OAuth 2.0: zgodny ze standardem RFC 6749.
  • Tokeny internetowe JSON (JWT): zgodne z RFC 7519 (w przypadku uproszczonego łączenia 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 ścieżki YOUR_PROJECT_ID to identyfikator skonfigurowany podczas rejestracji.

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

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

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

Parametry żądania

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

Parametr Opis
code (Wymagany w przypadku przepływu 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 mieć wartość bearer.

Odpowiedzi z błędem

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

Pole Opis
sendPostBody Określa, czy JavaScript ma przekierowywać do redirectUri za pomocą metody 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 Twoja usługa napotka błąd, musi przekierować użytkownika z powrotem do identyfikatora URI przekierowania OAuth z użyciem standardowych parametrów 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 Twoją usługę do proaktywnego powiadamiania Google, gdy użytkownik odłączy konto na Twojej platformie za pomocą protokołu RISC, co zapewnia synchronizację obu platform.

  • 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 tokena zdarzenia zagrażającego bezpieczeństwu

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, który hostujesz i który jest udostępniany Google podczas rejestracji.
aud Deklaracja 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 Expiration Time Claim: nie uwzględniaj tego pola, ponieważ zdarzenie, które spowodowało to powiadomienie, już się odbyło.
events Roszczenie dotyczące zdarzeń związanych z bezpieczeństwem: jest 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 sekcji Token sieciowy 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 Androidzie.

  • 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