API de Google Account Linking

En esta página de referencia, se documentan los extremos y las interfaces que ofrece Google y que tu app usa durante el proceso de vinculación de cuentas basada en OAuth.

Requisitos previos y estándares

Para interactuar correctamente con estos extremos de Google, tu integración debe cumplir con los siguientes estándares:

  • OAuth 2.0: Cumple con la RFC 6749.
  • Tokens web JSON (JWT): Cumplen con el RFC 7519 (para la vinculación simplificada y RISC).
  • Tokens de eventos de seguridad: Cumplen con el RFC 8417 (para RISC).
  • HTTPS: Todas las solicitudes deben realizarse a través de una conexión HTTPS segura.

URI de redireccionamiento de OAuth

Es el extremo al que tu servicio redirecciona el navegador del usuario después de una autenticación y un consentimiento exitosos. El parámetro de ruta de acceso YOUR_PROJECT_ID es el ID que configuras durante el registro.

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

  • URL de la zona de pruebas: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • Método: GET (con redireccionamiento del navegador)

Parámetros de la solicitud

Cuando redirecciones al usuario a Google, se deben agregar parámetros a la URL. Según el flujo de OAuth que se use, estos parámetros se formatean como una cadena de consulta (flujo de código de autorización) o como un fragmento de URL (flujo implícito).

Parámetro Descripción
code (Obligatorio para el flujo de código de autorización) Es el código de autorización que genera tu servicio.
state (Obligatorio) Es el valor de estado sin modificar que se recibió originalmente de Google.
access_token (Obligatorio para el flujo implícito) Es el token de acceso de larga duración que genera tu servicio.
token_type (Obligatorio para el flujo implícito) Debe ser bearer.

Respuestas de error

Si la solicitud al URI de redireccionamiento de OAuth no tiene el formato correcto, recibirás un error HTTP 400 Bad Request. El cuerpo de la respuesta contendrá un objeto JSON con la siguiente estructura:

Campo Descripción
sendPostBody Determina si el código JS debe redireccionar a redirectUri con POST. Por lo general, false en este caso.
errorMessage Es un mensaje de error que se muestra al cliente cuando no se puede completar el redireccionamiento. Para los fragmentos faltantes, es "A URI fragment or query string must be set.".

Respuestas de error de OAuth 2.0

Si el usuario rechaza el consentimiento o tu servicio encuentra un error, tu servicio debe redireccionar al usuario al URI de redireccionamiento de OAuth con parámetros de error de OAuth 2.0 estándar (como error=access_denied). Google procesará estos parámetros y mostrará una pantalla de error adecuada al usuario.

API de RISC (opcional)

Tu servicio lo usa para notificar de forma proactiva a Google cuando un usuario desvincula su cuenta en tu plataforma con el protocolo RISC, lo que garantiza que ambas plataformas permanezcan sincronizadas.

  • URL: https://risc.googleapis.com/v1/events:publish
  • Método: POST
  • Autenticación: Requiere un token de cuenta de servicio de Google con los permisos adecuados.
  • Content-Type: application/json

Declaraciones del token de evento de seguridad

Los tokens de eventos de seguridad que uses para notificar a Google sobre los eventos de revocación de tokens deben cumplir con los requisitos que se indican en la siguiente tabla:

Reclamar Descripción
iss Reclamo de la entidad emisora: Es una URL que alojas y que se comparte con Google durante el registro.
aud Reclamación de público: Identifica a Google como el destinatario del JWT. Debe establecerse en google_account_linking.
jti Reclamación de ID de JWT: Es un ID único que generas para cada token de evento de seguridad.
iat Issued At Claim: Es un valor NumericDate que representa la fecha y hora en que se creó este token de evento de seguridad.
toe Fecha y hora del reclamo del evento: Es un valor NumericDate opcional que representa la fecha y hora en que se revocó el token.
exp Declaración de hora de vencimiento: No incluyas este campo, ya que el evento que generó esta notificación ya ocurrió.
events Reclamo de eventos de seguridad: Es un objeto JSON y debe incluir solo un evento de revocación de token que contenga los siguientes campos:

  • subject_type: Se debe configurar como oauth_token.
  • token_type: Es el tipo de token que se revoca, ya sea access_token o refresh_token.
  • token_identifier_alg: Es el algoritmo que se usa para codificar el token y debe ser hash_SHA512_double.
  • token: Es el ID del token revocado.

Para obtener más información sobre los tipos y formatos de campos, consulta JSON Web Token (JWT).

Interfaz de "regreso" de Cambio de app

En el caso de App Flip, tu app para dispositivos móviles debe devolver el código de autorización o el token de acceso a la app de Google.

Android (resultado de Intent)

Tu app se abre con un Intent. Después de obtener el consentimiento, finaliza y devuelve un resultado a Google. Para obtener más información, consulta la guía de implementación de Android.

  • Acción: com.google.android.gms.auth.CODE_AVAILABLE
  • Extras: code, state, access_token, token_type.

Tu app abre Google con un esquema de URL personalizado o un vínculo universal HTTPS. Para obtener más información, consulta la guía de implementación para iOS.

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