MOTOKO BASE

Documentación

Configuración OAuth

Configuración paso a paso de OAuth de Google y GitHub para Motoko Base — crea apps de proveedor, configura callback URLs y completa el .env.

Abrir enChatGPT (se abre en una pestaña nueva)Claude (se abre en una pestaña nueva)Cursor (se abre en una pestaña nueva)Configuración paso a paso de OAuth de Google y GitHub para Motoko Base — crea apps de proveedor, configura callback URLs y completa el .env.

El inicio de sesión con Google y GitHub es opcional. Deja las variables OAuth sin definir y la app arranca con normalidad — los botones sociales en /sign-in y /sign-up permanecen deshabilitados.

Una vez configurado, Better Auth gestiona el flujo OAuth y almacena las cuentas vinculadas en la tabla account. Las callback URLs deben coincidir exactamente con tu BETTER_AUTH_URL.

Antes de empezar

Asegúrate de que estas variables de auth ya estén definidas:

# .env or .env.local
DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=your-generated-secret
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Para desarrollo local, usa http://localhost:3000 para ambas variables de URL. En producción, defínelas con tu origen HTTPS público (p. ej. https://app.example.com).

Genera BETTER_AUTH_SECRET si aún no lo has hecho:

openssl rand -base64 32

Reinicia el servidor de desarrollo tras cambiar cualquier variable de entorno:

pnpm dev

Google OAuth

Paso 1 — Crear un proyecto en Google Cloud

  1. Abre Google Cloud Console
  2. Crea un proyecto nuevo (o selecciona uno existente)
  3. Ve a APIs & Services → OAuth consent screen
  4. Elige External (o Internal para apps solo de Workspace)
  5. Completa el nombre de la app, el email de soporte y el contacto del desarrollador
  6. Añade scopes: email, profile y openid (los defaults suelen bastar)
  7. Añade usuarios de prueba si la app está en modo Testing

Paso 2 — Crear credenciales OAuth

  1. Ve a APIs & Services → Credentials
  2. Haz clic en Create Credentials → OAuth client ID
  3. Tipo de aplicación: Web application
  4. Nómbrala (p. ej. Motoko Base local)

Paso 3 — Definir el redirect URI

En Authorized redirect URIs, añade:

{BETTER_AUTH_URL}/api/auth/callback/google

Ejemplos:

EnvironmentRedirect URI
Localhttp://localhost:3000/api/auth/callback/google
Productionhttps://app.example.com/api/auth/callback/google

La ruta debe ser exactamente /api/auth/callback/google — Better Auth registra esta ruta automáticamente.

Opcionalmente añade Authorized JavaScript origins para desarrollo local:

http://localhost:3000

Paso 4 — Copiar credenciales a .env

Tras crear el cliente, Google muestra un Client ID y un Client secret. Añádelos a .env:

GOOGLE_CLIENT_ID=123456789-abcdef.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx

Ambos valores son solo de servidor — nunca los pongas en NEXT_PUBLIC_*.

Paso 5 — Verificar en local

  1. Reinicia el servidor de desarrollo: pnpm dev
  2. Abre http://localhost:3000/sign-in
  3. El botón Sign in with Google debería estar habilitado (no en gris)
  4. Haz clic — deberías ir a Google y volver a /dashboard

Si el botón sigue deshabilitado, comprueba que ambas GOOGLE_CLIENT_ID y GOOGLE_CLIENT_SECRET estén definidas y no vacías.

Solución de problemas de Google

ProblemFix
redirect_uri_mismatchRedirect URI in Google Console must match {BETTER_AUTH_URL}/api/auth/callback/google exactly (scheme, host, port, path)
Button disabledBoth GOOGLE_* vars must be set; restart dev server
access_denied in Testing modeAdd your Google account as a test user on the consent screen
Works locally, fails in productionAdd production redirect URI and set BETTER_AUTH_URL to your live domain

GitHub OAuth

Paso 1 — Crear una GitHub OAuth App

  1. Abre GitHub Developer Settings → OAuth Apps
  2. Haz clic en New OAuth App
  3. Completa:
    • Application name — p. ej. Motoko Base
    • Homepage URL — la URL de tu app (local: http://localhost:3000)
    • Authorization callback URL — ver Paso 2

Paso 2 — Definir el callback URL

El Authorization callback URL debe ser:

{BETTER_AUTH_URL}/api/auth/callback/github

Ejemplos:

EnvironmentCallback URL
Localhttp://localhost:3000/api/auth/callback/github
Productionhttps://app.example.com/api/auth/callback/github

Haz clic en Register application.

Paso 3 — Generar un client secret

  1. En la página de la OAuth app, haz clic en Generate a new client secret
  2. Copia el Client ID y el Client secret de inmediato — el secret solo se muestra una vez

Paso 4 — Copiar credenciales a .env

GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Ambos valores son solo de servidor.

Paso 5 — Verificar en local

  1. Reinicia el servidor de desarrollo: pnpm dev
  2. Abre http://localhost:3000/sign-in
  3. El botón Sign in with GitHub debería estar habilitado
  4. Haz clic — autoriza la app y aterriza en /dashboard

GitHub Apps vs OAuth Apps

Motoko Base usa una OAuth App estándar (no una GitHub App). Si usas una GitHub App en su lugar, asegúrate de que Account permissions → Email addresses esté en Read-only para que Better Auth pueda leer el email verificado del usuario.

Solución de problemas de GitHub

ProblemFix
redirect_uri mismatchCallback URL must be {BETTER_AUTH_URL}/api/auth/callback/github exactly
Button disabledBoth GITHUB_* vars must be set; restart dev server
Missing email / sign-in failsFor GitHub Apps, enable Email addresses read permission; OAuth Apps include email by default
Works locally, fails in productionUpdate callback URL in GitHub settings and set production BETTER_AUTH_URL

Checklist de producción

Usa esta checklist al desplegar OAuth en staging o producción:

  1. Definir URLs canónicas

    BETTER_AUTH_URL=https://app.example.com
NEXT_PUBLIC_APP_URL=https://app.example.com

  2. Añadir callback URLs de producción en Google Console y en la configuración de la GitHub OAuth app (mantén las URI locales si sigues desarrollando en local)

  3. Opcional — orígenes extra para deploys de preview:

    BETTER_AUTH_TRUSTED_ORIGINS=https://staging.example.com,https://*.vercel.app

  4. Reiniciar / redesplegar tras cambios de env

  5. Probar ambos proveedores en la URL en vivo — iniciar sesión, cerrar sesión y confirmar que la sesión persiste

Dónde está cableado OAuth en el código

Normalmente solo necesitas variables de entorno. Para personalizar el comportamiento, edita estos archivos:

FilePurpose
src/lib/auth/auth.tsRegisters socialProviders.google and socialProviders.github
src/lib/auth/social.tsisGoogleAuthConfigured() / isGitHubAuthConfigured()
src/app/sign-in/sign-in-form.tsxGoogle/GitHub sign-in handlers
src/app/sign-up/sign-up-form.tsxGoogle/GitHub sign-up handlers
src/app/sign-in/page.tsxPasses enabled flags to the form

Los secretos OAuth nunca pertenecen a archivos TypeScript de config — solo a .env.

Siguientes pasos

Better Auth — Visión general completa de auth, sesiones, rutas protegidas y mapa de archivos.

Variables de entorno — Todas las variables de auth en un solo lugar.