Sua API Account Linking

Esta página de referência documenta os endpoints da API que seu serviço precisa implementar para oferecer suporte à vinculação de contas com o Google. Isso inclui vinculação de contas baseada em OAuth, vinculação de contas simplificada e troca de apps.

Pré-requisitos e padrões

Para implementar esses endpoints, seu serviço precisa seguir os seguintes padrões:

  • OAuth 2.0: em conformidade com a RFC 6749.
  • Revogação de token: em conformidade com a RFC 7009.
  • JSON Web Tokens (JWT): em conformidade com a RFC 7519 (obrigatório para a vinculação simplificada).
  • HTTPS: todos os endpoints precisam ser veiculados por uma conexão HTTPS segura.

Endpoint de autorização

O endpoint de autorização é responsável por autenticar os usuários e obter o consentimento deles para vincular as contas ao Google.

  • URL:configurado no Console do Actions ou no console do Google Cloud.
  • Método:GET

Parâmetros de solicitação

Parâmetros Descrição
client_id O ID do cliente que você atribuiu ao Google.
redirect_uri O URL para onde você envia a resposta a esta solicitação.
state Um valor de monitoramento transmitido de volta ao Google sem alterações no URI de redirecionamento.
response_type Precisa ser code para o fluxo do código de autorização.
scope (Opcional) Lista separada por espaços de escopos para os dados que o Google está solicitando.
user_locale (Opcional) A configuração de idioma da Conta do Google, especificada usando uma tag de idioma BCP-47 (por exemplo, en-US).

Endpoint de troca de token

Esse endpoint é responsável por trocar códigos de autorização por tokens e atualizar tokens de acesso expirados.

  • URL:configurado no Console do Actions ou no console do Google Cloud.
  • Método:POST
  • Content-Type:application/x-www-form-urlencoded

Trocar código de autorização por tokens

Os parâmetros a seguir são usados na solicitação inicial de troca de token.

Parâmetros de solicitação

Parâmetros Descrição
client_id O ID do cliente que você atribuiu ao Google.
client_secret A chave secreta do cliente atribuída ao Google.
grant_type Precisa ser authorization_code.
code O código de autorização recebido do endpoint de autorização.
redirect_uri O mesmo URI de redirecionamento usado na solicitação inicial.

Trocar token de atualização por token de acesso

Os parâmetros a seguir são usados ao atualizar um token de acesso.

Parâmetros de solicitação

Parâmetros Descrição
client_id O ID do cliente que você atribuiu ao Google.
client_secret A chave secreta do cliente atribuída ao Google.
grant_type Precisa ser refresh_token.
refresh_token O token de atualização emitido anteriormente para o Google.

Resposta (JSON)

Retorne uma resposta bem-sucedida com um objeto JSON no corpo da resposta HTTPS.

  • Status HTTP:200 OK
  • Content-Type:application/json;charset=UTF-8
Campos Descrição
token_type Obrigatório. Precisa ser bearer.
access_token Obrigatório. Um token de curta duração usado para acessar as APIs do seu serviço.
refresh_token Obrigatório para authorization_code grant_type. Um token de longa duração usado para receber novos tokens de acesso.
expires_in Obrigatório. O tempo restante de vida útil do token de acesso em segundos.

Respostas de erro

Se uma solicitação ao endpoint de token falhar, retorne um erro HTTP 400 Solicitação inválida junto com uma resposta JSON contendo os seguintes campos:

  • Status HTTP:400 Bad Request
  • Content-Type:application/json;charset=UTF-8
Campos de erro (JSON) Descrição
error Obrigatório. Precisa ser invalid_grant.
error_description (Opcional) Texto legível por humanos que fornece mais informações.

Processar intents de vinculação simplificada

Se o serviço for compatível com a Vinculação de contas simplificada (OAuth com Login com o Google), o endpoint de troca de token também precisará oferecer suporte a declarações de JSON Web Token (JWT) e implementar as intents check, create e get.

Os seguintes parâmetros são usados nessas solicitações:

Parâmetros de solicitação

Parâmetros Descrição
intent A solicitação específica de vinculação simplificada: check, get ou create.
grant_type Para essas solicitações, esse parâmetro sempre tem o valor urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Um JSON Web Token (JWT) que fornece uma declaração assinada da identidade do usuário do Google. O JWT contém informações que incluem o ID, o nome e o endereço de e-mail da Conta do Google do usuário.

Seu servidor precisa validar esse JWT usando os critérios listados na seção Validação de JWT.
client_id O ID do cliente que você atribuiu ao Google.
client_secret A chave secreta do cliente atribuída ao Google.
scope Opcional:todos os escopos que você configurou para o Google solicitar aos usuários. Geralmente presente durante as intenções get e create.
response_type Obrigatório para a intent create:precisa ser definido como token.

Validação de JWT

Para garantir a segurança da vinculação simplificada, seu servidor precisa validar o assertion (JWT) usando os seguintes critérios:

  • Assinatura: verifique a assinatura com as chaves públicas do Google (disponíveis no endpoint JWK do Google).
  • Emissor (iss): precisa ser https://accounts.google.com.
  • Público-alvo (aud): precisa corresponder ao ID do cliente da API do Google atribuído à sua integração.
  • Validade (exp): precisa ser no futuro.

Resposta para a intent check

Uma solicitação com intent=check verifica se a Conta do Google (identificada pela declaração sub ou email na declaração JWT decodificada) existe no seu banco de dados de usuários.

  • Status HTTP:200 OK (conta encontrada) ou 404 Not Found (conta não encontrada)
  • Content-Type:application/json;charset=UTF-8
Campos Descrição
account_found Obrigatório. true se a conta existir, false caso contrário.

Resposta para a intent get

Uma solicitação com intent=get pede um token de acesso para uma Conta do Google existente.

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

O objeto JSON de resposta bem-sucedida usa exatamente a mesma estrutura de uma resposta padrão de troca de token bem-sucedida (retornando access_token, refresh_token etc.).

Se a conta não puder ser vinculada, um erro HTTP 401 será retornado.

  • Status HTTP:401 Unauthorized
  • Content-Type:application/json;charset=UTF-8
Campos de erro (JSON) Descrição
error Obrigatório. Precisa ser linking_error.
login_hint (Opcional) O endereço de e-mail do usuário a ser transmitido para o fluxo de vinculação de OAuth alternativo.

Resposta para a intent create

Uma solicitação com intent=create solicita a criação de uma nova conta de usuário com as informações fornecidas no JWT.

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

O objeto JSON de resposta bem-sucedida usa exatamente a mesma estrutura de uma resposta padrão de troca de token bem-sucedida (retornando access_token, refresh_token etc.).

Se o usuário já existir, um erro HTTP 401 será retornado para pedir que ele vincule a conta atual.

  • Status HTTP:401 Unauthorized
  • Content-Type:application/json;charset=UTF-8
Campos de erro (JSON) Descrição
error Obrigatório. Precisa ser linking_error.
login_hint O endereço de e-mail do usuário a ser transmitido para o fluxo de vinculação OAuth de substituição.

Endpoint UserInfo (opcional)

Usado para recuperar informações básicas de perfil sobre o usuário vinculado, conforme especificado na especificação do OpenID Connect Core 1.0. Isso é necessário para recursos como "Vinculação simplificada" ou "Login com um toque".

  • Método:GET
  • Autenticação:Authorization: Bearer ACCESS_TOKEN

Resposta (JSON)

Retorne uma resposta bem-sucedida com um objeto JSON no corpo da resposta HTTPS.

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

Campos de resposta

Campos Descrição
sub Obrigatório. Um ID exclusivo que identifica o usuário no seu sistema.
email Obrigatório. O endereço de e-mail do usuário.
email_verified Obrigatório. Um booleano que indica se o endereço de e-mail foi verificado.
given_name (Opcional) O nome do usuário.
family_name (Opcional) O sobrenome do usuário.
name (Opcional) O nome completo do usuário.
picture (Opcional) Um URL para a foto do perfil do usuário.

Respostas de erro

Se o token de acesso for inválido ou tiver expirado, retorne um erro HTTP 401 Não autorizado. Inclua também o cabeçalho de resposta WWW-Authenticate.

Qualquer resposta sem sucesso (4xx ou 5xx) retornada durante o processo de conexão é considerada irrecuperável. Nesses casos, o Google vai descartar todos os tokens recuperados, e o usuário precisará iniciar o processo de conexão de conta novamente.

Endpoint de revogação de token (opcional)

Permite que o Google notifique seu serviço quando um usuário desvincular a conta da plataforma do Google. Esse endpoint precisa atender aos requisitos descritos na RFC 7009.

  • Método:POST
  • Content-Type:application/x-www-form-urlencoded

Parâmetros de solicitação

Parâmetros Descrição
client_id Uma string que identifica a origem da solicitação como Google. Essa string precisa ser registrada no seu sistema como o identificador exclusivo do Google.
client_secret É uma string secreta registrada no Google para seu serviço.
token O token a ser revogado.
token_type_hint (Opcional) Uma dica sobre o tipo de token que está sendo revogado, access_token ou refresh_token. Se não for especificado, o padrão será access_token.

Respostas

Retorne uma resposta de sucesso quando o token for excluído ou se ele já estiver inválido.

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

Respostas de erro

Se o token não puder ser excluído por qualquer motivo (por exemplo, indisponibilidade do banco de dados), retorne um erro HTTP 503. O Google vai tentar de novo mais tarde ou conforme determinado pelo cabeçalho Retry-After.

  • Status HTTP:503 Service Unavailable
  • Content-Type:application/json;charset=UTF-8
  • Cabeçalhos: Retry-After: <HTTP-date / delay-seconds>