Vinculación de Cuentas de Google con OAuth

Las cuentas se vinculan con el flujo de código de autorización de OAuth 2.0 estándar de la industria.

OAuth 2.1 y PKCE para agentes

Para los agentes de IA sin estado y las canalizaciones multimodales, se recomienda aplicar OAuth 2.1.

• PKCE (Proof Key for Code Exchange): Se debe usar para proteger el flujo del código de autorización y evitar ataques de interceptación.
• No hay flujo implícito: El flujo implícito expone tokens de acceso en la URL, lo que representa un riesgo de seguridad para los entornos de agentes.

Tu servicio debe admitir extremos de autorización y de intercambio de tokens que cumplan con OAuth 2.0/2.1.

Crea el proyecto

Para crear tu proyecto y usar la vinculación de cuentas, haz lo siguiente:

1. Ve a la Consola de API de Google.
2. Haz clic en Crear proyecto.
3. Ingresa un nombre o acepta la sugerencia generada.
4. Confirma o edita los campos restantes.
5. Haz clic en Crear.

Para ver el ID del proyecto, haz lo siguiente:

1. Ve a la Consola de API de Google.
2. Busca tu proyecto en la tabla de la página de destino. El ID del proyecto aparece en la ID columna.

Configura la pantalla de consentimiento de OAuth

El proceso de vinculación de Cuentas de Google incluye una pantalla de consentimiento que les indica a los usuarios la aplicación que solicita acceso a sus datos, qué tipo de datos solicita y las condiciones que se aplican. Deberás configurar la pantalla de consentimiento de OAuth antes de generar un ID de cliente de la API de Google.

1. Abre la página de la pantalla de consentimiento de OAuth de la consola de APIs de Google.
2. Si se te solicita, selecciona el proyecto que acabas de crear.

3. En la página "Pantalla de consentimiento de OAuth", completa el formulario y haz clic en el botón "Guardar".

   Nombre de la aplicación: Es el nombre de la aplicación que solicita el consentimiento. El nombre debe reflejar con precisión tu aplicación y ser coherente con el nombre de la aplicación que los usuarios ven en otros lugares. El nombre de la aplicación se mostrará en la pantalla de consentimiento de vinculación de cuentas.

   Logotipo de la aplicación: Es una imagen en la pantalla de consentimiento que ayudará a los usuarios a reconocer tu app. El logotipo se muestra en la pantalla de consentimiento de vinculación de cuentas y en la configuración de la cuenta.

   Correo electrónico de asistencia: Es para que los usuarios se comuniquen contigo si tienen preguntas sobre su consentimiento.

   Permisos para las APIs de Google: Los permisos permiten que tu aplicación acceda a los datos privados de Google de tu usuario. Para el caso de uso de vinculación de Cuentas de Google, el permiso predeterminado (correo electrónico, perfil, openid) es suficiente, no es necesario agregar permisos sensibles. Por lo general, se recomienda solicitar permisos de forma incremental, en el momento en que se requiere el acceso, en lugar de hacerlo por adelantado. Obtén más información.

   Dominios autorizados: Para protegerlos a ti y a tus usuarios, Google solo permite que las aplicaciones que se autentican con OAuth usen dominios autorizados. Los vínculos de tus aplicaciones deben alojarse en dominios autorizados. Obtén más información.

   Vínculo a la página principal de la aplicación: Es la página principal de tu aplicación. Debe alojarse en un dominio autorizado.

   Vínculo a la Política de Privacidad de la aplicación: Se muestra en la pantalla de consentimiento de vinculación de Cuentas de Google. Debe alojarse en un dominio autorizado.

   Vínculo a las Condiciones del Servicio de la aplicación (opcional): Debe alojarse en un dominio autorizado.

   

   Figura 1. Pantalla de consentimiento de vinculación de Cuentas de Google para una aplicación ficticia, Tunery

4. Verifica el "Estado de verificación". Si tu aplicación necesita verificación, haz clic en el botón "Enviar para verificación" para enviarla. Consulta los requisitos de verificación de OAuth para obtener más detalles.

Implementa tu servidor de OAuth

Una implementación del servidor OAuth 2.0 del flujo de código de autorización consta de dos extremos que tu servicio pone a disposición a través de HTTPS. El primer extremo es el de autorización, que es responsable de encontrar o obtener el consentimiento de los usuarios para el acceso a los datos. El extremo de autorización presenta una IU de acceso a los usuarios que aún no accedieron y registra el consentimiento para el acceso solicitado. El segundo extremo es el de intercambio de tokens, que se usa para obtener cadenas encriptadas, llamadas tokens, que autorizan a un usuario a acceder a tu servicio.

Cuando una aplicación de Google necesita llamar a una de las APIs de tu servicio, Google usa estos extremos en conjunto para obtener permiso de tus usuarios para llamar a estas APIs en su nombre.

Vinculación de la Cuenta de Google: Flujo de código de autorización de OAuth

En el siguiente diagrama de secuencia, se detallan las interacciones entre el usuario, Google y los extremos de tu servicio.

Funciones y responsabilidades

En la siguiente tabla, se definen las funciones y responsabilidades de los actores en el flujo de OAuth de la vinculación de la Cuenta de Google (GAL). Ten en cuenta que, en GAL, Google actúa como el cliente de OAuth, mientras que tu servicio actúa como el proveedor de identidad o de servicios.

Una sesión de flujo de código de autorización de OAuth 2.0 iniciada por Google tiene el siguiente flujo:

1. Google abre tu extremo de autorización en el navegador del usuario. Si el flujo se inició en un dispositivo solo de voz para una acción, Google transfiere la ejecución a un teléfono.
2. El usuario accede, si aún no lo hizo, y otorga permiso a Google para acceder a sus datos con tu API, si aún no lo hizo.
3. Tu servicio crea un código de autorización y lo muestra a Google. Para ello, redirecciona el navegador del usuario a Google con el código de autorización adjunto a la solicitud.
4. Google envía el código de autorización a tu extremo de intercambio de tokens, que verifica la autenticidad del código y muestra un token de acceso y un token de actualización. El token de acceso es un token de corta duración que tu servicio acepta como credenciales para acceder a las APIs. El token de actualización es un token de larga duración que Google puede almacenar y usar para adquirir tokens de acceso nuevos cuando vencen.
5. Una vez que el usuario completa el flujo de vinculación de cuentas, cada solicitud posterior que se envía desde Google contiene un token de acceso.

Receta de implementación

Sigue estos pasos para implementar el flujo de código de autorización.

Paso 1: Administra las solicitudes de autorización

Cuando Google inicia la vinculación de cuentas, redirecciona al usuario a tu extremo de autorización. Para obtener información detallada sobre los contratos de protocolo y los requisitos de parámetros, consulta el extremo de autorización.

Para administrar la solicitud, realiza las siguientes acciones:

1. Valida la solicitud:

   • Confirma que el client_id coincida con el ID de cliente asignado a Google.
   • Confirma que el redirect_uri coincida con la URL de redireccionamiento de Google esperada: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
   • Verifica que response_type sea code.

2. Autentica al usuario:

   • Verifica si el usuario accedió a tu servicio.
   • Si el usuario no accedió, pídele que complete tu flujo de acceso o registro.

3. Genera un código de autorización:

   • Crea un código de autorización único y no adivinable asociado con el usuario y el cliente.
   • Configura el código para que venza en aproximadamente 10 minutos.

4. Redirecciona a Google:

   • Redirecciona el navegador a la URL proporcionada en redirect_uri.
   • Agrega los siguientes parámetros de consulta:
     • code: Es el código de autorización que generaste.
     • state: Es el valor de estado sin modificar que se recibió de Google.

Paso 2: Administra las solicitudes de intercambio de tokens

Tu extremo de intercambio de tokens procesa dos tipos de solicitudes: el intercambio de códigos por tokens y la actualización de tokens de acceso vencidos. Para obtener información detallada sobre los contratos de protocolo y los requisitos de parámetros, consulta el extremo de intercambio de tokens.

A. Intercambia códigos de autorización por tokens

Cuando Google recibe el código de autorización, llama a tu extremo de intercambio de tokens (POST) para recuperar tokens.

1. Valida la solicitud:

   • Verifica client_id y client_secret.
   • Verifica que el código de autorización sea válido y no haya vencido.
   • Confirma que redirect_uri coincida con el valor usado en el paso 1.
   • Si falla la validación, muestra un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

2. Emite tokens:

   • Genera un refresh_token de larga duración y un access_token de corta duración (por lo general, 1 hora).
   • Muestra un error HTTP 200 OK con la respuesta de token JSON estándar.

B. Actualiza los tokens de acceso

Cuando vence el token de acceso, Google solicita uno nuevo con el token de actualización.

1. Valida la solicitud:

   • Verifica client_id, client_secret y refresh_token.
   • Si falla la validación, muestra un error HTTP 400 Bad Request con {"error": "invalid_grant"}.

2. Emite un token de acceso nuevo:

   • Genera un access_token nuevo de corta duración.
   • Muestra un error HTTP 200 OK con la respuesta de token JSON (opcionalmente, incluye un token de actualización nuevo).

Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   userinfo endpoint response
   sub	A unique ID that identifies the user in your system.
   email	Email address of the user.
   given_name	Optional: First name of the user.
   family_name	Optional: Last name of the user.
   name	Optional: Full name of the user.
   picture	Optional: Profile picture of the user.

Cómo validar la implementación

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击配置 settings 以打开“OAuth 2.0 配置”窗口。
2. 在 OAuth flow（OAuth 流程）字段中，选择 Client-side（客户端）。
3. 在 OAuth Endpoints 字段中，选择 Custom。
4. 在相应字段中指定您的 OAuth 2.0 端点以及您分配给 Google 的客户端 ID。
5. 在第 1 步部分中，请勿选择任何 Google 范围。请将此字段留空，或输入适用于您服务器的范围（如果您不使用 OAuth 范围，则输入任意字符串）。完成后，点击 Authorize APIs。
6. 在第 2 步和第 3 步部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您将请求访问的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您可以同意或拒绝关联请求。
7. 确认您已重定向到相应平台。