Configuración y acceso a la consola de administración

Sincronizado con el commit 7d452a6 del starter.

El starter incluye una consola operativa en apps/admin. Es una segunda aplicación Next.js, no una ruta /admin dentro de la aplicación para clientes. Esta separación permite desplegar la consola en un origen dedicado y protegido, y publicarla de forma independiente, aunque comparte autenticación, esquema de base de datos, modelos y servicios.

Ejecución local

Completa primero la configuración habitual del starter, crea un usuario desde la aplicación pública y ejecuta la aplicación de administración:

pnpm dev:admin

Escucha en http://localhost:3001. Los comandos relacionados son:

pnpm build:admin
pnpm start:admin

Define el origen local de administración en .env:

NEXT_PUBLIC_ADMIN_WEB_URL=http://localhost:3001

Cuando existe ese valor, la compilación de administración lo usa como origen de Better Auth, salvo que el shell o el entorno de despliegue proporcione de forma explícita BETTER_AUTH_URL o NEXT_PUBLIC_AUTH_BASE_URL. Como NEXT_PUBLIC_ADMIN_WEB_URL queda incorporada durante la compilación, un cambio en producción exige volver a desplegar.

Asignar un operador

El acceso de plataforma se guarda en users.role y es independiente de los roles owner, admin y member de una organización.

• admin_ro puede entrar en la consola y consultar datos operativos.
• admin_rw también puede ejecutar las acciones de escritura de la consola.

Asigna el rol a una cuenta existente desde la raíz del repositorio:

pnpm admin:promote operator@example.com admin_rw

El comando usa admin_rw por defecto, admite --dry-run y se niega a adivinar cuando un mismo correo pertenece a más de un proveedor de inicio de sesión. En ese caso, selecciona la cuenta exacta con --provider, por ejemplo:

pnpm admin:promote operator@example.com --role admin_ro --provider google

La autorización nunca resuelve el rol mediante el correo. El servidor carga el usuario de base de datos que coincide con el ID o UUID único de la sesión y comprueba el rol almacenado en cada página y ruta API protegida.

MFA es obligatorio

El rol de administración no basta. Cada operador debe activar la autenticación de dos factores de Better Auth desde la interfaz pública de la cuenta. Un operador con rol de administración pero sin MFA es enviado a /mfa-required; después de activarlo, completa el desafío /two-factor de la aplicación de administración.

Las cuentas que solo usan Google necesitan una contraseña antes de poder activar la autenticación de dos factores en Better Auth. La interfaz pública de la cuenta ofrece Establecer una contraseña para ese caso. El inicio de sesión con Google sigue funcionando después.

El acceso de administración utiliza el mismo endpoint de correo con desafío que la aplicación pública. Por ello, el despliegue de administración también necesita NEXT_PUBLIC_TURNSTILE_SITE_KEY y TURNSTILE_SECRET_KEY cuando la protección captcha está activa.

Despliegue separado

Crea un segundo proyecto de alojamiento desde el mismo repositorio y ejecuta pnpm build:admin. Asígnale un origen dedicado, como https://admin.example.com.

La aplicación de administración importa el validador compartido del entorno de producción. Por ahora necesita todo el conjunto de variables obligatorias de producción, aunque una pantalla de administración no use directamente cada proveedor. Parte de las variables de producción de la aplicación para clientes, compáralas con .env.example y sigue Despliegue y seguridad. Después ajusta los valores específicos de administración:

• conserva los mismos DATABASE_URL y BETTER_AUTH_SECRET que usa la aplicación para clientes;
• configura NEXT_PUBLIC_ADMIN_WEB_URL con el origen de administración (el build también lo usa para las URL de Better Auth salvo que las sobrescribas explícitamente);
• proporciona un par de claves de Turnstile válido para el hostname de administración; reutiliza las claves del sitio público solo si su configuración admite ese hostname;
• elige un límite ADMIN_MAX_CREDIT_GRANT adecuado para el producto (el valor predeterminado es 100000).

Mantén separados los orígenes web y de administración. La aplicación de administración envía cabeceras noindex, nofollow, noarchive y no-store, además de políticas restrictivas de marcos, referencia y seguridad de contenido. Estas cabeceras reducen la exposición, pero no sustituyen la autorización: el layout del servidor y cada API de administración comprueban rol y MFA.

Lista de comprobación

1. Compila la consola con pnpm build:admin.
2. Confirma que el origen de administración y la URL base de autenticación apuntan al mismo despliegue.
3. Inicia sesión como admin_ro y comprueba que los datos son visibles pero las escrituras no están disponibles.
4. Inicia sesión como admin_rw, completa MFA y prueba una escritura reversible.
5. Confirma que la acción aparece en /audit.
6. Confirma que un usuario normal no puede abrir una página ni llamar a una API de administración.

Continúa con Páginas y operaciones de la consola para ver las superficies que incluye la versión actual.