Runbook: Google OAuth — Setup pre-producción

Este runbook cubre la configuración inicial de las dos OAuth apps de Google (Gmail y Workspace) necesarias para activar los providers Google en cualquier entorno de DaraMex.

Prioridad: este runbook NO bloquea el merge de código. Con el entorno en modo "Testing" de Google, hasta 100 emails de test users pueden conectar sus cuentas sin iniciar el proceso formal de verificación.

1. Estructura recomendada en Google Cloud

Un único proyecto de Google Cloud con dos OAuth 2.0 Clients.

OAuth Client	Provider DaraMex	Scopes a declarar
DaraMex Gmail	`google_gmail`	`gmail.send`, `gmail.modify`
DaraMex Workspace	`google_workspace`	`spreadsheets`, `drive.file`, `calendar`, `calendar.events`

Un proyecto único simplifica billing, IAM y el consent screen. El aislamiento de scopes se logra mediante dos clients separados: Gmail queda aislado del proceso de verificación restringido, Workspace agrupa Sheets + Calendar con scopes sensitive pero no restricted.

2. Crear el proyecto y los OAuth clients

Ir a Google Cloud Console → crear un proyecto (ej. daramex-integrations).
Habilitar las APIs necesarias:
- Gmail API → para el client Gmail
- Google Sheets API + Google Drive API → para el client Workspace (capability sheets)
- Google Calendar API → para el client Workspace (capability calendar)
Para cada app: APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID.
- Application type: Web application
- Names: DaraMex Gmail, DaraMex Workspace
Guardar CLIENT_ID y CLIENT_SECRET de cada client.

Una sola vez por proyecto en APIs & Services → OAuth consent screen:

Campo	Valor
App name	`DaraMex`
User support email	email del equipo de soporte
App logo	logo corporativo (opcional, recomendado)
App domain	dominio de producción
Authorized domains	dominio de producción
Developer contact	email del equipo de plataforma

Scopes: declarar por cada client sólo los que realmente se usan (ver tabla del paso 1). Los scopes de Gmail (gmail.send, gmail.modify) son restricted y requieren verificación para uso con cuentas externas.

Modo de publicación: mantener en Testing mientras no haya usuarios externos. Límite: 100 test users.

4. Configurar los Redirect URIs

La redirect URI la deriva el API en runtime a partir de APP_URL:

${APP_URL}/api/connections/oauth/${provider}/callback

No hay variables de entorno GOOGLE_*_REDIRECT_URI — fueron eliminadas. Esto garantiza que APP_URL y la redirect URI nunca divergen entre entornos.

Registrar en cada OAuth client exactamente estos URIs:

# Desarrollo local (APP_URL=http://localhost:3000)
http://localhost:3000/api/connections/oauth/google_gmail/callback
http://localhost:3000/api/connections/oauth/google_workspace/callback

# Staging (APP_URL=https://api.staging.daramex.com)
https://api.staging.daramex.com/api/connections/oauth/google_gmail/callback
https://api.staging.daramex.com/api/connections/oauth/google_workspace/callback

# Producción (APP_URL=https://api.daramex.com)
https://api.daramex.com/api/connections/oauth/google_gmail/callback
https://api.daramex.com/api/connections/oauth/google_workspace/callback

Google valida match exacto — cualquier discrepancia (incluso trailing slash) rompe el flujo.

Verificar que APP_URL apunte al host público donde Google puede llegar. Si se cambia APP_URL, actualizar los redirect URIs en Google Cloud Console en el mismo deploy.

5. Variables de entorno a configurar

Cada entorno (dev / staging / prod) requiere sólo estas variables relacionadas con Google OAuth:

env

# OAuth app Gmail (provider=google_gmail, capability=gmail)
GOOGLE_GMAIL_CLIENT_ID=<client-id-gmail>
GOOGLE_GMAIL_CLIENT_SECRET=<client-secret-gmail>

# OAuth app Workspace (provider=google_workspace, capability=sheets|calendar)
GOOGLE_WORKSPACE_CLIENT_ID=<client-id-workspace>
GOOGLE_WORKSPACE_CLIENT_SECRET=<client-secret-workspace>

# Ventana de refresco proactivo (ms, default 300000 = 5 min)
GOOGLE_TOKEN_REFRESH_SAFETY_WINDOW_MS=300000

# Redirecciones del frontend al terminar el OAuth
CONNECTIONS_OAUTH_SUCCESS_URL=https://app.<entorno>.daramex.com/connections/success
CONNECTIONS_OAUTH_ERROR_URL=https://app.<entorno>.daramex.com/connections/error

# APP_URL debe estar seteado (ya es global) — se usa para derivar la redirect URI
APP_URL=https://api.<entorno>.daramex.com

Si falta CLIENT_ID o CLIENT_SECRET de una app, esa app queda deshabilitada y cualquier POST /connections/oauth/<provider>/start devuelve 400 PROVIDER_NOT_CONFIGURED. El resto de la API no se ve afectada — la validación es lazy.

Variables eliminadas respecto a la versión anterior del módulo (no deben aparecer en ningún entorno): GOOGLE_SHEETS_CLIENT_ID, GOOGLE_SHEETS_CLIENT_SECRET, GOOGLE_SHEETS_REDIRECT_URI, GOOGLE_SHEETS_SCOPES, GOOGLE_CALENDAR_CLIENT_ID, GOOGLE_CALENDAR_CLIENT_SECRET, GOOGLE_CALENDAR_REDIRECT_URI, GOOGLE_CALENDAR_SCOPES, GOOGLE_GMAIL_REDIRECT_URI, GOOGLE_GMAIL_SCOPES.

6. Test users (modo Testing)

Mientras el consent screen esté en Testing:

APIs & Services → OAuth consent screen → Test users → Add users.
Agregar los emails del equipo.
Límite: 100 test users por proyecto.

7. Proceso de verificación de Google

Para onboarding de usuarios externos con scopes restringidos (Gmail):

Publicar la app (salir de Testing).
APIs & Services → OAuth consent screen → Submit for verification.
Google puede requerir video demostrativo, política de privacidad pública y revisión de seguridad.
Duración típica: 1 a 6 semanas.

Referencia oficial: Google OAuth verification.

spreadsheets, drive.file, calendar y calendar.events son sensitive (no restricted) y el proceso es más rápido.

8. Rotación de `CLIENT_SECRET` sin downtime

Crear un nuevo secret en Google Cloud Console para el client (un client acepta múltiples secrets activos simultáneamente).
Actualizar la variable GOOGLE_GMAIL_CLIENT_SECRET o GOOGLE_WORKSPACE_CLIENT_SECRET en el gestor de secretos del entorno.
Rolling deploy de la API. Durante el deploy, los pods viejos usan el secret anterior — ambos son válidos en Google hasta que se revoque el viejo.
Una vez que todos los pods estén en la nueva versión, revocar el secret anterior en Google Cloud Console.

Downtime cero si el rolling deploy se completa antes de revocar.

9. Verificación post-setup

Con las variables configuradas y la API desplegada:

bash

# Iniciar flujo para Gmail (provider=google_gmail, capability=gmail)
curl -X POST https://api.<entorno>.daramex.com/api/connections/oauth/google_gmail/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "test gmail", "capability": "gmail", "visibility": "private"}'

# Respuesta esperada
# { "authUrl": "https://accounts.google.com/...", "state": "..." }

# Iniciar flujo para Workspace con capability Sheets
curl -X POST https://api.<entorno>.daramex.com/api/connections/oauth/google_workspace/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "test sheets", "capability": "sheets"}'

# Verificar coupling: debe fallar con CONNECTION.PROVIDER_CAPABILITY_MISMATCH
curl -X POST https://api.<entorno>.daramex.com/api/connections/oauth/google_gmail/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "bad", "capability": "sheets"}'

# Provider no configurado (omitir GOOGLE_WORKSPACE_* en el env y llamar a workspace)
# Respuesta esperada: 400 PROVIDER_NOT_CONFIGURED

Runbook: Google OAuth — Setup pre-producción ​

1. Estructura recomendada en Google Cloud ​

2. Crear el proyecto y los OAuth clients ​

3. Configurar el consent screen ​

4. Configurar los Redirect URIs ​

5. Variables de entorno a configurar ​

6. Test users (modo Testing) ​

7. Proceso de verificación de Google ​

8. Rotación de CLIENT_SECRET sin downtime ​

9. Verificación post-setup ​