Configurar autenticación OAuth de Gmail

Esta guía te guiará para crear una aplicación de Google Cloud para autenticación OAuth con Gmail. OAuth proporciona una forma más segura de acceder a tu cuenta de Gmail comparada con la autenticación tradicional por contraseña.

Requisitos previos

• Una cuenta de Google (personal o Google Workspace)
• Acceso a Google Cloud Console
• La URL de tu instalación de Perfex CRM (para configurar el URI de redirección)

Configuración paso a paso

Paso 1: Crear un proyecto de Google Cloud

1. Ve a Google Cloud Console
2. Haz clic en el desplegable de proyecto en la parte superior de la página
3. Haz clic en "New Project"
4. Introduce un nombre de proyecto (por ejemplo, "Perfex Mailbox OAuth")
5. Haz clic en "Create"
6. Espera a que se cree el proyecto y selecciónalo

Paso 2: Habilitar Gmail API

1. En Google Cloud Console, navega a "APIs & Services" > "Library"
2. Busca "Gmail API"
3. Haz clic en "Gmail API" en los resultados
4. Haz clic en "Enable"
5. Espera a que se habilite la API

Paso 3: Configurar la pantalla de consentimiento OAuth

1. Navega a "APIs & Services" > "OAuth consent screen"
2. Selecciona "External" como tipo de usuario (a menos que tengas cuenta Google Workspace, entonces puedes elegir "Internal")
3. Haz clic en "Create"
4. Completa la información requerida:
   • App name: Introduce el nombre de tu aplicación (por ejemplo, "Perfex CRM Mailbox")
   • User support email: Tu dirección de correo
   • Developer contact information: Tu dirección de correo
5. Haz clic en "Save and Continue"
6. En la página "Scopes", haz clic en "Add or Remove Scopes"
7. Añade los siguientes permisos:
   • https://www.googleapis.com/auth/gmail.readonly
   • https://www.googleapis.com/auth/gmail.send
   • https://www.googleapis.com/auth/gmail.modify
8. Haz clic en "Update", luego "Save and Continue"
9. En la página "Test users" (si usas tipo de app External):
   • Añade tu dirección de Gmail como usuario de prueba
   • Haz clic en "Save and Continue"
10. Revisa y haz clic en "Back to Dashboard"

Paso 4: Crear credenciales OAuth 2.0

1. Navega a "APIs & Services" > "Credentials"
2. Haz clic en "Create Credentials" > "OAuth client ID"
3. Selecciona "Web application" como tipo de aplicación
4. Introduce un nombre para tu cliente OAuth (por ejemplo, "Perfex Mailbox Client")
5. En "Authorized redirect URIs", haz clic en "Add URI"
6. Añade tu URI de redirección en el formato:

https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail

Reemplaza your-domain.com con tu dominio real de Perfex CRM.

7. Haz clic en "Create"
8. IMPORTANTE: Copia y guarda ambos:
   • Client ID (lo necesitarás)
   • Client Secret (lo necesitarás; haz clic en "Show" para mostrarlo)

Paso 5: Configurar en Perfex CRM

1. Ve al área de administración de Perfex CRM
2. Navega a Mailbox > Configuration
3. Selecciona "OAuth2" como método de autenticación
4. Selecciona "Gmail" como proveedor
5. Introduce tu Client ID en el campo "Gmail Client ID"
6. Introduce tu Client Secret en el campo "Gmail Client Secret"
7. Haz clic en "Save Configuration"
8. Haz clic en el botón "Connect Gmail"
9. Autoriza la aplicación en la ventana emergente de Google
10. Deberías ver un mensaje de éxito confirmando la conexión

Limitaciones y consideraciones importantes

Limitaciones de las apps de prueba de Google

Estas limitaciones las impone Google, no nuestro software.

1. Caducidad del token (7 días) - Las apps no verificadas (apps en modo de prueba) tienen tokens OAuth que caducan a los 7 días. Después de 7 días, los usuarios deben volver a autorizar la conexión. Esta es una política de seguridad de Google para aplicaciones no verificadas.

2. Restricciones de usuarios de prueba - Solo los usuarios añadidos a la lista "Test users" pueden usar la app OAuth. Máximo 100 usuarios de prueba permitidos. Esta restricción aplica hasta que la app se verifique y publique.

3. Proceso de verificación de la app - Para eliminar la caducidad del token a los 7 días, debes enviar tu app para verificación de Google. La verificación puede tardar varias semanas (normalmente 4-8 semanas). Google revisa tu app en cuanto a seguridad y cumplimiento.

Verificación y publicación de la app

Para eliminar las limitaciones:

1. Enviar para verificación

   • Ve a "OAuth consent screen" en Google Cloud Console
   • Haz clic en el botón "PUBLISH APP"
   • Completa el formulario de verificación con:
     • Propósito y funcionalidad de la app
     • URL de política de privacidad
     • URL de términos de servicio
     • Demostración en vídeo (opcional pero recomendada)
   • Envía para revisión

2. Plazos de verificación

   • Revisión inicial: 1-2 semanas
   • Solicitudes de información adicional: variable (si Google necesita aclaraciones)
   • Aprobación final: 4-8 semanas en total (típico)

3. Después de la verificación

   • Los tokens ya no caducan a los 7 días
   • Sin restricciones de usuarios de prueba
   • Cualquier usuario de Gmail puede usar la app

Producción vs prueba

• Modo prueba: Configuración rápida, pero los tokens caducan cada 7 días
• Modo producción: Requiere verificación, pero los tokens no caducan
• La elección es tuya - nuestro software funciona en ambos modos

Actualización del token

Nuestro módulo gestiona automáticamente la actualización del token cuando es posible. Sin embargo:

• Apps no verificadas: Los tokens caducan a los 7 días y requieren reautorización manual
• Apps verificadas: Los tokens se actualizan automáticamente sin intervención del usuario

Notas

• El URI de redirección debe coincidir exactamente con lo configurado en Google Cloud Console
• Mantén tu Client Secret seguro; nunca lo compartas públicamente
• Si cambias tu dominio, actualiza el URI de redirección en Google Cloud Console
• El flujo OAuth lo gestiona totalmente Google; nuestro módulo solo inicia y recibe el callback

Solución de problemas

Error "Redirect URI mismatch":

• Asegúrate de que el URI de redirección en Google Cloud Console coincida exactamente: https://your-domain.com/admin/mailbox/oauth/callback?provider=gmail
• Comprueba si hay barras diagonales al final o diferencias entre HTTP y HTTPS

"Token expired" después de 7 días:

• Es normal para apps no verificadas (política de Google)
• Vuelve a autorizar haciendo clic en "Connect Gmail" de nuevo
• Para evitarlo, envía tu app para verificación de Google

Error "Access blocked":

• Asegúrate de que tu correo esté añadido a la lista "Test users" (para apps no verificadas)
• Comprueba que Gmail API esté habilitada en tu proyecto de Google Cloud

No encuentras Gmail API:

• Asegúrate de estar en el proyecto correcto de Google Cloud
• Intenta buscar "Gmail" en la biblioteca de APIs

Recursos adicionales

• Documentación de OAuth 2.0 de Google
• Documentación de Gmail API
• Google Cloud Console

info

La caducidad del token a los 7 días y las restricciones de usuarios de prueba son políticas de seguridad de Google para aplicaciones no verificadas. Estas limitaciones no las impone nuestro software. Una vez que Google verifique tu app, se eliminan estas restricciones.