Configurar el acceso con OAuth

Crear y verificar una cuenta real

La autenticación significa demostrar quién está usando la aplicación. Inicie Postgres y ejecute las migraciones utilizando primero la guía de la base de datos, luego deje el servidor web en ejecución. Abra http://localhost:3000/auth,, elija el registro de correo electrónico/contraseña, ingrese su nombre, correo electrónico y contraseña, y envíe. Conserve EMAIL_PROVIDER=local para esta primera prueba.

Cuando un flujo solicita un código de correo electrónico, abra http://localhost:3000/mail-preview en otra pestaña del navegador, busque el mensaje más reciente para esa dirección y copie su código nuevamente en el formulario de inicio de sesión. Solicite un código nuevo si caduca. Estos mensajes permanecen en la bandeja de salida local; Al revisar repetidamente una bandeja de entrada externa no los encontrará. Cierre sesión y luego inicie sesión nuevamente para confirmar que la cuenta respaldada por la base de datos funciona.

Si el registro informa una conexión a la base de datos o un error de tabla faltante, finalice la configuración de la base de datos en lugar de habilitar el inicio de sesión social. Los botones de Google, GitHub, Apple, X y Microsoft necesitan su propia aplicación de proveedor y configuración de devolución de llamada; habilite uno solo después de que se complete la guía del proveedor. Better Auth es el motor predeterminado que se envía y no necesita una cuenta de autenticación paga para iniciar sesión en el correo electrónico local.

• Inicie Postgres antes de crear una cuenta
• Usar y solucionar problemas de códigos de inicio de sesión de correo electrónico
• Configurar el inicio de sesión de Google
• Añadir el inicio de sesión con Google
• Añadir el inicio de sesión con GitHub
• Añadir el inicio de sesión con Apple

Elige los métodos de inicio de sesión habilitados

La base incluye correo electrónico y contraseña, OTP y autenticación social configurable. Better Auth gestiona la identidad y las sesiones, mientras que la aplicación compone la configuración del proveedor y la entrega transaccional de OTP.

Habilita solo los proveedores sociales que hayas configurado. Los secretos de cliente del proveedor y el secreto de autenticación se guardan únicamente en el servidor.

Conecta la identidad con un espacio de trabajo

Los controladores autenticados resuelven el estado de la sesión antes de acceder a los registros del espacio de trabajo. El aprovisionamiento del espacio debe ser idempotente para que repetir un hook del ciclo de vida no cree registros de propiedad duplicados.

Verifica el comportamiento de la sesión

Prueba el inicio de sesión, los OTP no válidos o caducados, el consumo de un solo uso, el cierre de sesión y el rechazo del acceso anónimo. Las pruebas con adaptador de memoria cubren la semántica de los controladores; la persistencia en la base de datos de producción y las devoluciones de llamada de proveedores reales requieren una aceptación independiente.

Configuración y ajustes

1. Define AUTH_SECRET con al menos 32 caracteres aleatorios — openssl rand -hex 32 sirve.

2. En la consola de desarrollador de cada proveedor, crea una app OAuth y registra la URL de callback: {APP_URL}/api/auth/callback/<provider> con Better Auth (el AUTH_PROVIDER por defecto). Usa apps separadas para local y producción donde el proveedor solo permita un callback — docs/github-auth-setup.md recorre el flujo de GitHub de extremo a extremo.

3. Activa la flag del proveedor y define su par de cliente — AUTH_GOOGLE_ENABLED más GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET, y el trío equivalente para Apple, GitHub, Microsoft o Twitter. Activar una flag sin sus credenciales hace fallar el arranque y nombra la variable que falta.

4. Microsoft es el único callback que difiere según el motor: /api/auth/callback/microsoft con Better Auth, /api/auth/callback/microsoft-entra-id con Auth.js.

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

Flujo de implementación

Las cuentas externas del workspace son una superficie distinta: los pares CONNECTED_X_*, CONNECTED_GOOGLE_* y CONNECTED_MICROSOFT_* alimentan Settings → Connections, y sus callbacks viven bajo {APP_URL}/api/accounts/{x|google|microsoft}/callback. Un client id vacío deja desactivado el flujo de conexión de ese proveedor — no reutilices ahí las credenciales de la app de acceso.

Los secretos de cliente de proveedor permanecen solo en el servidor, igual que AUTH_SECRET — nunca en variables NEXT_PUBLIC_ ni EXPO_PUBLIC_.

¿El acceso funciona? Continúa con «Configurar la IA».

Verificación y solución de problemas

Prueba un primer inicio de sesión, una sesión que vuelve, una pantalla de consentimiento cancelada y un proveedor desactivado. Un callback que no coincide es el fallo habitual — la URL registrada debe coincidir exactamente con APP_URL y el callback id del motor, y la app necesita reiniciarse tras cambios de entorno.