API de vinculação de Conta do Google

Esta página de referência documenta os endpoints e interfaces oferecidos pelo Google que seu app usa durante o processo de vinculação de contas baseada em OAuth.

Pré-requisitos e padrões

Para interagir com esses endpoints do Google, sua integração precisa seguir estes padrões:

  • OAuth 2.0: em conformidade com a RFC 6749.
  • JSON Web Tokens (JWT): em conformidade com a RFC 7519 (para vinculação simplificada e RISC).
  • Tokens de eventos de segurança: em conformidade com a RFC 8417 (para RISC).
  • HTTPS: todas as solicitações precisam ser feitas por uma conexão HTTPS segura.

URI de redirecionamento do OAuth

O endpoint em que seu serviço redireciona o navegador do usuário após a autenticação e o consentimento bem-sucedidos. O parâmetro de caminho YOUR_PROJECT_ID é o ID que você configura durante o registro.

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

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

  • Método:GET (usando o redirecionamento do navegador)

Parâmetros de solicitação

Ao redirecionar o usuário de volta para o Google, os parâmetros precisam ser anexados ao URL. Dependendo do fluxo do OAuth usado, esses parâmetros são formatados como uma string de consulta (fluxo de código de autorização) ou como um fragmento do URL (fluxo implícito).

Parâmetro Descrição
code (Obrigatório para o fluxo de código de autorização) O código de autorização gerado pelo seu serviço.
state (Obrigatório) O valor do estado não modificado originalmente recebido do Google.
access_token (Obrigatório para o fluxo implícito) O token de acesso de longa duração gerado pelo seu serviço.
token_type (Obrigatório para o fluxo implícito) Precisa ser bearer.

Respostas de erro

Se a solicitação ao URI de redirecionamento do OAuth estiver malformada, você vai receber um erro HTTP 400 Bad Request. O corpo da resposta vai conter um objeto JSON com a seguinte estrutura:

Campo Descrição
sendPostBody Determina se o JS precisa redirecionar para o redirectUri com POST. Normalmente, false nesse cenário.
errorMessage Uma mensagem de erro a ser exibida ao cliente quando o redirecionamento não puder ser concluído. Para fragmentos ausentes, é "A URI fragment or query string must be set."

Respostas de erro do OAuth 2.0

Se o usuário negar o consentimento ou se o serviço encontrar um erro, ele precisará redirecionar o usuário de volta para o URI de redirecionamento do OAuth com parâmetros de erro do OAuth 2.0 padrão (como error=access_denied). O Google vai processar esses parâmetros e mostrar uma tela de erro adequada ao usuário.

API RISC (opcional)

Usado pelo seu serviço para notificar proativamente o Google quando um usuário desvincula a conta na sua plataforma usando o protocolo RISC, garantindo que as duas plataformas permaneçam sincronizadas.

  • URL:https://risc.googleapis.com/v1/events:publish
  • Método:POST
  • Autenticação:exige um token de conta de serviço do Google com as permissões adequadas.
  • Content-Type:application/json

Declarações de token de evento de segurança

Os tokens de eventos de segurança usados para notificar o Google sobre eventos de revogação de token precisam obedecer aos requisitos na tabela a seguir:

Reivindicar Descrição
iss Declaração do emissor:um URL hospedado por você e compartilhado com o Google durante o registro.
aud Declaração de público-alvo:identifica o Google como o destinatário do JWT. Ele precisa ser definido como google_account_linking.
jti Declaração de ID do JWT:um ID exclusivo gerado para cada ocorrência de segurança.
iat Declaração "Emitido em":é um valor NumericDate que representa o momento em que esta ocorrência de segurança foi criada.
toe Horário da reivindicação do evento:é um valor NumericDate opcional que representa o horário em que o token foi revogado.
exp Declaração de tempo de expiração:não inclua esse campo, porque o evento que resultou nesta notificação já ocorreu.
events Declaração de eventos de segurança:é um objeto JSON e precisa incluir apenas um evento de revogação de token com os seguintes campos:

  • subject_type: precisa ser definido como oauth_token.
  • token_type: o tipo de token que está sendo revogado, access_token ou refresh_token.
  • token_identifier_alg: o algoritmo usado para codificar o token, que precisa ser hash_SHA512_double.
  • token: o ID do token revogado.

Para mais informações sobre tipos e formatos de campo, consulte JSON Web Token (JWT)

Interface de vinculação no app "Flip-Back"

Para o App Flip, seu app móvel precisa retornar o código de autorização ou o token de acesso ao app Google.

Android (resultado da intent)

O app é aberto usando uma intent. Depois do consentimento, ele termina e retorna um resultado ao Google. Para mais informações, consulte o guia de implementação do Android.

  • Ação: com.google.android.gms.auth.CODE_AVAILABLE
  • Extras:code, state, access_token, token_type.

Seu app abre o Google usando um esquema de URL personalizado ou um link universal HTTPS. Para mais informações, consulte o guia de implementação do iOS.

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