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 OAuth, vinculação de conta 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 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 Actions Console 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).
code_challenge (Obrigatório para OAuth 2.1) O desafio derivado do verificador de código.
code_challenge_method (Opcional) O método usado para derivar o desafio (por exemplo, S256).

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 Actions Console 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.
code_verifier (Obrigatório para PKCE) A string aleatória criptográfica original.

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.

Esquema OpenAPI 3.1

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • 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 com 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 do Google), o endpoint de troca de token também precisará aceitar declarações de JSON Web Token (JWT) e implementar as intents check e get obrigatórias, e, opcionalmente, a intent create.

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

Parâmetros de solicitação

Parâmetros Descrição
intent A intenção de vinculação simplificada específica que está sendo solicitada: check, get ou create opcional.
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 asserçã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 (opcional)

A intent create é opcional. Se o serviço permitir a criação de contas usando a vinculação simplificada, uma solicitação com intent=create vai iniciar 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 ou se o serviço não oferecer suporte à criação de contas, um erro HTTP 401 será retornado para solicitar que o Google volte ao fluxo de vinculação OAuth padrão.

  • 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 alternativo de vinculação do OAuth.

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 vinculação é considerada irrecuperável. Nesses casos, o Google vai descartar todos os tokens recuperados, e o usuário precisará iniciar o processo de vinculaçã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 dele 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 fazer a solicitação de novo mais tarde ou conforme indicado 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>