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 com base no OAuth.

Pré-requisitos e padrões

Para interagir com esses endpoints do Google, sua integração precisa obedecer aos seguintes padrões:

  • OAuth 2.0: compatível com a RFC 6749.
  • JSON Web Tokens (JWT): compatível com a RFC 7519 (para vinculação simplificada e RISC).
  • Security Event Tokens: compatível 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. O parâmetro de caminho YOUR_PROJECT_ID é o ID configurado 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 do código de autorização) ou como um fragmento do URL (fluxo implícito).

Parâmetro Descrição
code (Obrigatório para o fluxo do código de autorização) O código de autorização gerado pelo seu serviço.
state (Obrigatório) O valor de estado não modificado recebido originalmente 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 para o URI de redirecionamento do OAuth estiver malformada, você vai receber um erro HTTP 400 Solicitação inválida. 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 padrão do OAuth 2.0 (como error=access_denied). O Google vai processar esses parâmetros e mostrar uma tela de erro adequada ao usuário.

API RISC (opcional)

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

  • URL:https://risc.googleapis.com/v1/events:publish
  • Método:POST
  • Autenticação:requer 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 evento de segurança usados para notificar o Google sobre eventos de revogação de token precisam obedecer aos requisitos da tabela a seguir:

Declaração 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. Precisa ser definido como google_account_linking.
jti Declaração do ID do JWT:é um ID exclusivo gerado para cada token de ocorrência de segurança.
iat Declaração de emitido em:é um valor NumericDate que representa o horário em que essa ocorrência de segurança foi criada.
toe Declaração de horário do evento:é um valor NumericDate opcional que representa o horário em que o token foi revogado.
exp Declaração de horário de validade:não inclua esse campo, porque o evento que resultou nessa 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 que contenha 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 e 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 "Flip-Back" de vinculação no app

Para a vinculação no app, o app para dispositivos móveis precisa retornar o código de autorização ou o token de acesso ao app Google.

Android (resultado da intent)

Seu app é aberto usando uma intent. Após o consentimento, ele é finalizado 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