Tu API de Account Linking

En esta página de referencia, se documentan los extremos de la API que tu servicio debe implementar para admitir la vinculación de cuentas con Google. Esto incluye la vinculación de cuentas basada en OAuth, la vinculación de cuentas optimizada y el cambio de app.

Requisitos previos y estándares

Para implementar correctamente estos extremos, tu servicio debe cumplir con los siguientes estándares:

  • OAuth 2.0: Cumple con la RFC 6749.
  • Revocación de tokens: Cumple con la RFC 7009.
  • Tokens web JSON (JWT): Cumplen con el RFC 7519 (obligatorio para la vinculación optimizada).
  • HTTPS: Todos los extremos deben publicarse a través de una conexión HTTPS segura.

Extremo de autorización

El extremo de autorización es responsable de autenticar a los usuarios y obtener su consentimiento para vincular sus cuentas con Google.

  • URL: Se configura en Actions Console o en Google Cloud Console.
  • Método: GET

Parámetros de la solicitud

Parámetros Descripción
client_id Es el ID de cliente que le asignaste a Google.
redirect_uri Es la URL a la que envías la respuesta a esta solicitud.
state Es un valor de contabilidad que se devuelve a Google sin cambios en el URI de redireccionamiento.
response_type Debe ser code para el flujo del código de autorización.
scope (Opcional) Lista de permisos separados por espacios para los datos que solicita Google.
user_locale (Opcional) Es el parámetro de configuración de idioma de la Cuenta de Google, especificado con una etiqueta de idioma BCP-47 (p.ej., en-US).

Extremo de intercambio de tokens

Este extremo es responsable de intercambiar códigos de autorización por tokens y de actualizar los tokens de acceso vencidos.

  • URL: Se configura en Actions Console o en Google Cloud Console.
  • Método: POST
  • Content-Type: application/x-www-form-urlencoded

Intercambia el código de autorización por tokens

En la solicitud inicial de intercambio de tokens, se usan los siguientes parámetros.

Parámetros de la solicitud

Parámetros Descripción
client_id Es el ID de cliente que le asignaste a Google.
client_secret Es el secreto de cliente que le asignaste a Google.
grant_type Debe ser authorization_code.
code Es el código de autorización que se recibe del extremo de autorización.
redirect_uri Es el mismo URI de redireccionamiento que se usó en la solicitud inicial.

Intercambia el token de actualización por un token de acceso

Los siguientes parámetros se usan cuando se actualiza un token de acceso.

Parámetros de la solicitud

Parámetros Descripción
client_id Es el ID de cliente que le asignaste a Google.
client_secret Es el secreto de cliente que le asignaste a Google.
grant_type Debe ser refresh_token.
refresh_token Es el token de actualización que se emitió anteriormente a Google.

Respuesta (JSON)

Devuelve una respuesta exitosa con un objeto JSON en el cuerpo de la respuesta HTTPS.

  • Estado HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
Campos Descripción
token_type Obligatorio. Debe ser bearer.
access_token Obligatorio. Es un token de corta duración que se usa para acceder a las APIs de tu servicio.
refresh_token Obligatorio para authorization_code grant_type. Es un token de larga duración que se usa para obtener tokens de acceso nuevos.
expires_in Obligatorio. Es la vida útil restante del token de acceso en segundos.

Respuestas de error

Si falla una solicitud al extremo del token, devuelve un error HTTP 400 Bad Request junto con una respuesta JSON que contenga los siguientes campos:

  • Estado HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Campos de error (JSON) Descripción
error Obligatorio. Debe ser invalid_grant.
error_description (Opcional) Texto legible por humanos que proporciona información adicional.

Cómo controlar intents de vinculación optimizada

Si tu servicio admite la Vinculación de cuentas optimizada (OAuth con Acceder con Google), tu extremo de intercambio de tokens también debe admitir aserciones de tokens web JSON (JWT) y, además, implementar los intents check, create y get.

En estas solicitudes, se usan los siguientes parámetros:

Parámetros de la solicitud

Parámetros Descripción
intent Es la intención específica de vinculación optimizada que se solicita: check, get o create.
grant_type En estas solicitudes, este parámetro siempre tiene el valor urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Es un token web JSON (JWT) que proporciona una aserción firmada de la identidad del usuario de Google. El JWT contiene información que incluye el ID, el nombre y la dirección de correo electrónico de la Cuenta de Google del usuario.

Tu servidor debe validar este JWT con los criterios que se indican en la sección Validación de JWT.
client_id Es el ID de cliente que le asignaste a Google.
client_secret Es el secreto de cliente que le asignaste a Google.
scope Opcional: Cualquier permiso que hayas configurado para que Google solicite a los usuarios. Suele estar presente durante las intenciones get y create.
response_type Obligatorio para la intención create: Se debe establecer en token.

Validación de JWT

Para garantizar la seguridad de la vinculación optimizada, tu servidor debe validar el assertion (JWT) según los siguientes criterios:

  • Firma: Verifica la firma con las claves públicas de Google (disponibles en el extremo de JWK de Google).
  • Emisor (iss): Debe ser https://accounts.google.com.
  • Público (aud): Debe coincidir con el ID de cliente de la API de Google asignado a tu integración.
  • Vencimiento (exp): Debe ser en el futuro.

Respuesta para el intent check

Una solicitud con intent=check verifica si la Cuenta de Google (identificada por el reclamo sub o email en la aserción de JWT decodificada) existe en tu base de datos de usuarios.

  • Estado HTTP: 200 OK (se encontró la cuenta) o 404 Not Found (no se encontró la cuenta)
  • Content-Type: application/json;charset=UTF-8
Campos Descripción
account_found Obligatorio. true si la cuenta existe; de lo contrario, false.

Respuesta para el intent get

Una solicitud con intent=get solicita un token de acceso para una Cuenta de Google existente.

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

El objeto JSON de respuesta correcta usa exactamente la misma estructura que una respuesta estándar de Token Exchange correcta (devuelve access_token, refresh_token, etcétera).

Si no se puede vincular la cuenta, se muestra un error HTTP 401.

  • Estado HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Campos de error (JSON) Descripción
error Obligatorio. Debe ser linking_error.
login_hint (Opcional) Es la dirección de correo electrónico del usuario que se pasará al flujo de vinculación de OAuth de resguardo.

Respuesta para el intent create

Una solicitud con intent=create solicita la creación de una nueva cuenta de usuario con la información proporcionada en el JWT.

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

El objeto JSON de respuesta correcta usa exactamente la misma estructura que una respuesta estándar de Token Exchange correcta (devuelve access_token, refresh_token, etcétera).

Si el usuario ya existe, se muestra un error HTTP 401 para solicitarle que vincule su cuenta existente.

  • Estado HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Campos de error (JSON) Descripción
error Obligatorio. Debe ser linking_error.
login_hint Es la dirección de correo electrónico del usuario que se pasará al flujo de vinculación de OAuth de resguardo.

Extremo UserInfo (opcional)

Se usa para recuperar información básica del perfil sobre el usuario vinculado, como se especifica en la especificación de OpenID Connect Core 1.0. Esto es obligatorio para funciones como "Vinculación optimizada" o "Acceso con un toque".

  • Método: GET
  • Autenticación: Authorization: Bearer ACCESS_TOKEN

Respuesta (JSON)

Devuelve una respuesta exitosa con un objeto JSON en el cuerpo de la respuesta HTTPS.

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

Campos de respuesta

Campos Descripción
sub Obligatorio. Es un ID único que identifica al usuario en tu sistema.
email Obligatorio. La dirección de correo electrónico del usuario.
email_verified Obligatorio. Es un valor booleano que indica si se verificó la dirección de correo electrónico.
given_name (Opcional) Nombre del usuario.
family_name (Opcional) Apellido del usuario.
name (Opcional) Nombre completo del usuario.
picture (Opcional) URL de la foto de perfil del usuario.

Respuestas de error

Si el token de acceso no es válido o caducó, devuelve un error HTTP 401 Unauthorized. También debes incluir el encabezado de respuesta WWW-Authenticate.

Cualquier respuesta sin éxito (4xx o 5xx) que se muestre durante el proceso de vinculación se considera irrecuperable. En estos casos, Google descartará los tokens recuperados, y el usuario deberá iniciar el proceso de vinculación de la cuenta nuevamente.

Extremo de revocación de token (opcional)

Permite que Google notifique a tu servicio cuando un usuario desvincule su cuenta de la plataforma de Google. Este extremo debe cumplir con los requisitos que se describen en RFC 7009.

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

Parámetros de la solicitud

Parámetros Descripción
client_id Cadena que identifica el origen de la solicitud como Google. Esta cadena debe registrarse en tu sistema como el identificador único de Google.
client_secret Es una cadena secreta que registraste en Google para tu servicio.
token Es el token que se revocará.
token_type_hint (Opcional) Es una sugerencia sobre el tipo de token que se revoca, ya sea access_token o refresh_token. Si no se especifica, el valor predeterminado es access_token.

Respuestas

Devuelve una respuesta correcta cuando el token se borra correctamente o si el token ya no es válido.

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

Respuestas de error

Si el token no se puede borrar por algún motivo (p.ej., no hay disponibilidad de la base de datos), devuelve un error HTTP 503. Google volverá a intentar la solicitud más tarde o según lo indique el encabezado Retry-After.

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