Skip to content

Autenticacion

AgentCrew incluye un sistema de autenticacion integrado con gestion de usuarios, organizaciones, incorporacion mediante invitaciones y control de acceso basado en roles. La autenticacion se configura mediante la variable de entorno AUTH_PROVIDER y soporta dos modos: local (por defecto) y noop.

Modos de Autenticacion

Autenticacion Local (por defecto)

Establece AUTH_PROVIDER=local para habilitar la autenticacion por email/contrasena con tokens JWT. Este es el modo por defecto cuando se usa el instalador.

  • Los usuarios se registran con email, contrasena, nombre y nombre de organizacion.
  • Las contrasenas se hashean con bcrypt (factor de coste 12).
  • Se emiten tokens de acceso JWT (por defecto 24h) y tokens de refresco (por defecto 7d) al iniciar sesion.
  • Los tokens se firman con HMAC-SHA256 usando la variable de entorno JWT_SECRET.
  • El frontend refresca automaticamente los tokens de acceso expirados usando el token de refresco.

Variables de entorno requeridas para el modo local:

Variable Descripcion
JWT_SECRET Secreto para firmar tokens JWT. Minimo 32 caracteres. Generar con openssl rand -base64 48.
SETTINGS_ENCRYPTION_KEY Clave para cifrar datos sensibles (claves API, tokens de invitacion) en reposo usando AES-256-GCM. Generar con openssl rand -base64 32.

Autenticacion Noop (sin auth)

Establece AUTH_PROVIDER=noop para desactivar completamente la autenticacion. En este modo:

  • No se muestra pantalla de login.
  • Se crean automaticamente una organizacion y un usuario por defecto.
  • Todas las peticiones a la API se aceptan sin tokens.
  • Ideal para desarrollo local, pruebas o configuraciones auto-alojadas de un solo usuario donde la seguridad se maneja a nivel de red.
Nota: Cambiar de noop a local es transparente. Los datos existentes (equipos, agentes, configuracion) se asocian automaticamente con la organizacion por defecto. Solo necesitaras crear tu primera cuenta de usuario.

Organizaciones

Cada usuario pertenece a una organizacion. Las organizaciones proporcionan aislamiento de datos: equipos, agentes, tareas programadas, webhooks, configuracion y todos los demas recursos estan limitados a la organizacion. Los usuarios de una organizacion no pueden ver ni acceder a recursos de otra.

Modo Single-Tenant (por defecto)

Con MULTI_TENANT=false (el valor por defecto), solo puede existir una organizacion. El primer usuario que se registra crea la organizacion y se convierte en su administrador. Los usuarios adicionales solo pueden unirse mediante invitacion.

Modo Multi-Tenant

Con MULTI_TENANT=true, cualquiera puede registrarse y crear una nueva organizacion. Cada organizacion esta completamente aislada con sus propios usuarios, equipos, configuracion y datos.

Roles de Usuario

AgentCrew usa un modelo simple de dos roles:

Rol Capacidades
Admin Acceso completo. Puede gestionar configuracion de la organizacion, invitar usuarios, cambiar roles, restablecer contrasenas y eliminar miembros. El primer usuario (creador de la organizacion) siempre es administrador y no puede ser degradado.
Miembro Puede crear y gestionar equipos, agentes, tareas programadas, webhooks y configuracion. No puede gestionar usuarios ni la configuracion de la organizacion.
Seguridad: El sistema garantiza que siempre exista al menos un administrador. El propietario de la organizacion no puede ser eliminado ni degradado.

Configuracion Inicial

  1. Instala AgentCrew usando la guia de Inicio Rapido. El instalador genera todos los secretos necesarios automaticamente.
  2. Abre la interfaz en http://localhost:8080. Veras la pagina de registro.
  3. Crea tu cuenta con tu nombre, correo, contrasena y nombre de organizacion. Esta cuenta se convierte en el administrador de la organizacion.
  4. Agrega las claves API en Configuracion para comenzar a desplegar equipos de agentes.

Invitar Usuarios

Los administradores pueden invitar nuevos usuarios desde la pagina de Configuracion de la Organizacion:

  1. Ve a Configuracion de la Organizacion en la barra lateral.
  2. En la seccion de Invitaciones, ingresa la direccion de correo y haz clic en Invitar.
  3. Copia el enlace de invitacion desde el listado y compartelo con el usuario.
  4. El usuario invitado abre el enlace, completa su nombre y contrasena, y se une a la organizacion.

Las invitaciones expiran despues de 7 dias. Los administradores pueden cancelar invitaciones pendientes en cualquier momento. El sistema previene invitaciones duplicadas: no se puede invitar un correo que ya es miembro o que tiene una invitacion pendiente.

Gestion de Contrasenas

Cambiar tu Contrasena

Los usuarios pueden cambiar su propia contrasena desde su pagina de Perfil. Deben ingresar su contrasena actual y la nueva. Las contrasenas deben tener al menos 8 caracteres e incluir una letra mayuscula, una minuscula y un digito.

Restablecimiento de Contrasena por Admin

Los administradores pueden restablecer la contrasena de cualquier miembro desde la pagina de Configuracion de la Organizacion. Al restablecer, se genera una contrasena temporal que se muestra en pantalla. El usuario debe cambiarla en su proximo inicio de sesion (se muestra una pantalla de cambio de contrasena obligatorio).

Autenticacion WebSocket

Las conexiones de chat en tiempo real usan WebSocket. Como WebSocket no soporta cabeceras personalizadas, el token JWT se pasa como parametro de consulta: 

ws://localhost:8080/api/ws/team/<team-id>?token=<jwt-access-token>

El servidor API valida el token antes de aceptar la conexion. En modo noop, no se requiere token.

Detalles de Seguridad

  • Hashing de contrasenas: bcrypt con factor de coste 12.
  • Firma JWT: HMAC-SHA256. El algoritmo none esta explicitamente bloqueado.
  • Tipos de token: Los tokens de acceso y refresco incluyen un claim type para prevenir el uso cruzado.
  • Tokens de invitacion: 32 bytes de crypto/rand. Se almacena un hash SHA-256 en la base de datos; el token original se cifra con AES-256-GCM para su recuperacion por administradores.
  • Datos sensibles en reposo: Las claves API y valores de configuracion se cifran con AES-256-GCM usando SETTINGS_ENCRYPTION_KEY.
  • Normalizacion de email: Todos los correos se convierten a minusculas y se recortan para prevenir problemas de distincion entre mayusculas y minusculas.
  • Aislamiento de datos: Todas las consultas a la base de datos estan limitadas al ID de organizacion del usuario, aplicado a nivel de middleware.

Desactivar la Autenticacion

Para ejecutar AgentCrew sin autenticacion (util para desarrollo local o redes de confianza): 

# En tu archivo .env
AUTH_PROVIDER=noop

En modo noop, JWT_SECRET y SETTINGS_ENCRYPTION_KEY no son necesarios. Todos los endpoints de la API aceptan peticiones sin autenticar, y se crean automaticamente un usuario y una organizacion por defecto.

Siguientes Pasos

  • Configuracion: Lista completa de variables de entorno incluyendo ajustes de autenticacion.
  • Arquitectura: Como la capa de autenticacion se integra con el servidor API y el frontend.
  • Inicio Rapido: Pon AgentCrew en marcha con autenticacion en un solo comando.