Autenticación

SecureVu almacena la información de usuarios en su base de datos. Los hashes de contraseñas se generan usando el estándar de la industria PBKDF2-SHA256 con 600.000 iteraciones. Tras un inicio de sesión exitoso, se emite un token JWT con fecha de vencimiento y se establece como cookie. La cookie se actualiza automáticamente según sea necesario. Este token JWT también puede pasarse en la cabecera de Authorization como token de portador.

Los usuarios se administran en la interfaz en Configuración > Usuarios.

Los siguientes puertos están disponibles para acceder a la interfaz web de SecureVu.

Puerto	Descripción
8971	Interfaz y API autenticadas. Los proxies inversos deben usar este puerto.
5000	Acceso interno a la interfaz y API sin autenticación. El acceso a este puerto debe estar restringido. Está destinado a usarse dentro de la red Docker para servicios que se integran con SecureVu y no admiten autenticación.

Incorporación

Al iniciar, se genera un usuario administrador y una contraseña que se imprimen en los registros. Se recomienda establecer una nueva contraseña para la cuenta de administrador después de iniciar sesión por primera vez en Configuración > Usuarios.

Restablecer contraseña de administrador

En caso de que pierdas el acceso a tu instancia, puedes indicarle a SecureVu que restablezca la contraseña del administrador y la imprima en los registros en el próximo inicio usando la configuración reset_admin_password en tu archivo de configuración.

auth:
  reset_admin_password: true

Guía de contraseñas

Crear contraseñas seguras y administrarlas correctamente es importante. SecureVu requiere una longitud mínima de 12 caracteres. Para orientación sobre estándares de contraseñas, consulta NIST SP 800-63B. Para aprender qué hace que una contraseña sea verdaderamente segura, lee este artículo.

Limitación de velocidad por fallos de inicio de sesión

Para limitar el riesgo de ataques de fuerza bruta, está disponible la limitación de velocidad para fallos de inicio de sesión. Esto se implementa con SlowApi, y la notación en cadena para valores válidos está disponible en la documentación.

Por ejemplo, 1/second;5/minute;20/hour limitará el endpoint de inicio de sesión cuando los fallos ocurran más de:

• 1 vez por segundo
• 5 veces por minuto
• 20 veces por hora

Reiniciar SecureVu restablecerá los límites de velocidad.

Si ejecutas SecureVu detrás de un proxy, querrás configurar trusted_proxies o estos límites de velocidad se aplicarán a la dirección IP del proxy ascendente. Esto significa que un ataque de fuerza bruta limitará los intentos de inicio de sesión de otros dispositivos y podría bloquearte temporalmente de tu instancia. Para garantizar que los límites de velocidad solo se apliquen a la dirección IP real de donde provienen las solicitudes, deberás listar las redes ascendentes en las que deseas confiar. Estos proxies de confianza se verifican contra la cabecera X-Forwarded-For al buscar la dirección IP de origen de la solicitud.

Si ejecutas un proxy inverso en el mismo archivo Docker Compose que SecureVu, aquí tienes un ejemplo de cómo podría verse tu configuración de autenticación:

auth:
  failed_login_rate_limit: "1/second;5/minute;20/hour"
  trusted_proxies:
    - 172.18.0.0/16 # <---- this is the subnet for the internal Docker Compose network

Duración de la sesión

La duración predeterminada de la sesión para la autenticación de usuario en SecureVu es de 24 horas. Esta configuración determina cuánto tiempo permanece activa la sesión autenticada de un usuario antes de que se requiera una actualización del token; de lo contrario, el usuario deberá iniciar sesión nuevamente.

Si bien el valor predeterminado proporciona un equilibrio entre seguridad y comodidad, puedes personalizar esta duración para adaptarla a tus requisitos de seguridad específicos y preferencias de experiencia de usuario. La duración de la sesión se configura en segundos.

El valor predeterminado de 86400 hará que la sesión de autenticación expire después de 24 horas. Algunos otros ejemplos:

• 0: Establecer la duración de la sesión en 0 requerirá que un usuario inicie sesión cada vez que acceda a la aplicación o después de un tiempo de espera muy corto e inmediato.
• 604800: Establecer la duración de la sesión en 604800 requerirá que un usuario inicie sesión si el token no se actualiza durante 7 días.

auth:
  session_length: 86400

Secreto del token JWT

El secreto del token JWT debe mantenerse seguro. Cualquier persona con este secreto puede generar tokens JWT válidos para autenticarse con SecureVu. Debe ser una cadena aleatoria criptográficamente segura de al menos 64 caracteres.

Puedes generar un token usando la biblioteca de secretos de Python con el siguiente comando:

python3 -c 'import secrets; print(secrets.token_hex(64))'

SecureVu busca un secreto de token JWT en el siguiente orden:

1. Una variable de entorno llamada SECUREVU_JWT_SECRET
2. Un archivo llamado SECUREVU_JWT_SECRET en el directorio especificado por la variable de entorno CREDENTIALS_DIRECTORY (por defecto, el directorio de secretos Docker: /run/secrets/)
3. Una opción jwt_secret de las opciones de la App de Home Assistant
4. Un archivo .jwt_secret en el directorio de configuración

Si no se encuentra ningún secreto al iniciar, SecureVu genera uno y lo almacena en un archivo .jwt_secret en el directorio de configuración.

Cambiar el secreto invalidará los tokens actuales.

Configuración de proxy

SecureVu puede configurarse para aprovechar las funciones de proxies de autenticación ascendentes comunes como Authelia, Authentik, oauth2_proxy o traefik-forward-auth.

Si estás aprovechando la autenticación de un proxy ascendente, probablemente quieras deshabilitar la autenticación de SecureVu, ya que no hay correspondencia entre los usuarios en la base de datos de SecureVu y los usuarios autenticados a través del proxy. Opcionalmente, si la comunicación entre el proxy inverso y SecureVu se realiza sobre una red no confiable, debes establecer un auth_secret en la configuración de proxy y configurar el proxy para enviar el valor secreto como una cabecera llamada X-Proxy-Secret. Asumiendo que es una red no confiable, también querrás configurar un certificado TLS real para garantizar que el tráfico no pueda simplemente ser interceptado para robar el secreto.

Aquí tienes un ejemplo de cómo deshabilitar la autenticación de SecureVu y también garantizar que las solicitudes provengan solo de tu proxy conocido.

auth:
  enabled: False

proxy:
  auth_secret: <some random long string>

Puedes usar el siguiente código para generar un secreto aleatorio.

python3 -c 'import secrets; print(secrets.token_hex(64))'

Mapeo de cabeceras

Si has deshabilitado la autenticación de SecureVu y tu proxy admite pasar una cabecera con nombres de usuario y/o roles autenticados, puedes usar la configuración header_map para especificar el nombre de la cabecera para que se pase a SecureVu. Por ejemplo, lo siguiente mapeará los valores X-Forwarded-User y X-Forwarded-Groups. Los nombres de cabecera no distinguen entre mayúsculas y minúsculas. Se pueden incluir múltiples valores en la cabecera de rol. SecureVu espera que el carácter que separa los roles sea una coma, pero esto puede especificarse usando la entrada de configuración separator.

proxy:
  ...
  separator: "|" # This value defaults to a comma, but Authentik uses a pipe, for example.
  header_map:
    user: x-forwarded-user
    role: x-forwarded-groups

SecureVu admite los roles admin, viewer y roles personalizados (ver más abajo). Al usar el puerto 8971, SecureVu valida estas cabeceras y las solicitudes posteriores usan las cabeceras remote-user y remote-role para la autorización.

Se puede proporcionar un rol predeterminado. Cualquier valor en la cabecera role mapeada anulará el predeterminado.

proxy:
  ...
  default_role: viewer

Mapeo de roles

En algunos entornos, los proveedores de identidad ascendentes (OIDC, SAML, LDAP, etc.) no pasan un rol compatible con SecureVu directamente, sino que pasan una o más reclamaciones de grupo. Para manejar esto, SecureVu admite un role_map que traduce los nombres de grupos ascendentes a los roles internos de SecureVu (admin, viewer o personalizados).

proxy:
  ...
  header_map:
    user: x-forwarded-user
    role: x-forwarded-groups
    role_map:
      admin:
        - sysadmins
        - access-level-security
      viewer:
        - camera-viewer
      operator:  # Custom role mapping
        - operators

En este ejemplo:

• Si el proxy pasa una cabecera de rol que contiene sysadmins o access-level-security, al usuario se le asigna el rol admin.
• Si el proxy pasa una cabecera de rol que contiene camera-viewer, al usuario se le asigna el rol viewer.
• Si el proxy pasa una cabecera de rol que contiene operators, al usuario se le asigna el rol personalizado operator.
• Si ningún mapeo coincide, SecureVu recurre a default_role si está configurado.
• Si role_map no está definido, SecureVu asume que la cabecera de rol contiene directamente admin, viewer o un nombre de rol personalizado.

Nota sobre la semántica de coincidencia:

• Precedencia de administrador: si el mapeo de admin coincide, SecureVu resuelve la sesión como admin para evitar una degradación accidental cuando un usuario pertenece a múltiples grupos (por ejemplo, tanto a los grupos admin como viewer).

Consideraciones sobre puertos

Puerto autenticado (8971)

• El mapeo de cabeceras está completamente admitido.
• La cabecera remote-role determina los privilegios del usuario:
  • admin → Acceso completo (gestión de usuarios, cambios de configuración).
  • viewer → Acceso de solo lectura.
  • Roles personalizados → Acceso de solo lectura limitado a las cámaras definidas en auth.roles[role].
• Asegúrate de que tu proxy envíe tanto las cabeceras de usuario como de rol para una aplicación adecuada de roles.

Puerto no autenticado (5000)

• Las cabeceras se ignoran para la aplicación de roles.
• Todas las solicitudes se tratan como anónimas.
• El valor de remote-role se sobreescribe con acceso de nivel administrador.
• Este diseño garantiza el uso interno no autenticado dentro de una red de confianza.

Ten en cuenta que solo la siguiente lista de cabeceras está permitida por defecto:

Remote-User
Remote-Groups
Remote-Email
Remote-Name
X-Forwarded-User
X-Forwarded-Groups
X-Forwarded-Email
X-Forwarded-Preferred-Username
X-authentik-username
X-authentik-groups
X-authentik-email
X-authentik-name
X-authentik-uid

Si deseas agregar más opciones, puedes sobreescribir el archivo predeterminado con un montaje bind de Docker en /usr/local/nginx/conf/proxy_trusted_headers.conf. Consulta el código fuente para el formato del archivo predeterminado.

Redirección de la página de inicio de sesión

SecureVu realiza correctamente la redirección de la página de inicio de sesión que debería funcionar con la mayoría de los proxies de autenticación. Si tu proxy inverso devuelve una cabecera Location en respuestas no autorizadas 401, 302 o 307, el frontend de SecureVu la detectará automáticamente y redirigirá a esa URL.

URL de cierre de sesión personalizada

Si tu proxy inverso tiene una URL de cierre de sesión dedicada, puedes especificarla usando la opción de configuración logout_url. Esto actualizará el enlace de Cerrar sesión en la interfaz.

Roles de usuario

SecureVu admite roles de usuario para controlar el acceso a ciertas funciones en la interfaz y la API, como la gestión de usuarios o la modificación de ajustes de configuración. Los roles se asignan a los usuarios en la base de datos o a través de cabeceras de proxy y se aplican al acceder a la interfaz o API a través del puerto autenticado (8971).

Roles admitidos

• admin: Acceso completo a todas las funciones, incluyendo gestión de usuarios y configuración.
• viewer: Acceso de solo lectura a la interfaz y API, incluyendo la visualización de cámaras, elementos de revisión y grabaciones históricas. El editor de configuración y los ajustes en la interfaz son inaccesibles.
• Roles personalizados: Nombres de rol arbitrarios (alfanuméricos, con puntos/guiones bajos) con permisos específicos de cámara. Estos amplían el sistema para un acceso granular (p. ej., "operator" para cámaras seleccionadas).

Roles personalizados y acceso a cámaras

El rol viewer proporciona acceso de solo lectura a todas las cámaras en la interfaz y la API. Los roles personalizados permiten a los administradores limitar el acceso de solo lectura a cámaras específicas. Cada rol especifica una lista de nombres de cámaras permitidas. Si a un usuario se le asigna un rol personalizado, su cuenta es similar al rol viewer: solo puede ver En Vivo, Revisión/Historial, Explorar y Exportar para las cámaras designadas. Los endpoints de la API backend aplican esto del lado del servidor (p. ej., devolviendo 403 para cámaras no autorizadas), y la interfaz frontend filtra el contenido en consecuencia (p. ej., los desplegables de cámaras solo muestran las opciones permitidas).

Ejemplo de configuración de roles

cameras:
  front_door:
    # ... camera config
  side_yard:
    # ... camera config
  garage:
    # ... camera config

auth:
  enabled: true
  roles:
    operator: # Custom role
      - front_door
      - garage # Operator can access front and garage
    neighbor:
      - side_yard

Si deseas proporcionar acceso a todas las cámaras a un usuario específico, simplemente usa el rol viewer.

Gestión de roles de usuario

1. Inicia sesión como usuario admin a través del puerto 8971 (preferido), o sin autenticación a través del puerto 5000.
2. Navega a Configuración.
3. En la sección Usuarios, edita el rol de un usuario seleccionando entre los roles disponibles (admin, viewer o personalizado).
4. En la sección Roles, añade/edita/elimina roles personalizados (selecciona cámaras mediante interruptores). Eliminar un rol reasigna automáticamente a los usuarios como "viewer".

Aplicación de roles

Al usar el puerto autenticado (8971), los roles se validan mediante el token JWT o las cabeceras del proxy (p. ej., remote-role).

En el puerto no autenticado interno (5000), los roles no se aplican. Todas las solicitudes se tratan como anónimas, otorgando acceso equivalente al rol admin sin restricciones.

Para usar el control de acceso basado en roles, debes conectarte a SecureVu a través del puerto autenticado (8971) directamente o a través de un proxy inverso.

Visibilidad de roles en la interfaz

• Al iniciar sesión a través del puerto 8971, tu nombre de usuario y rol se muestran en el menú de cuenta (esquina inferior).
• Al usar el puerto 5000, la interfaz siempre mostrará "anonymous" como nombre de usuario y "admin" como rol.

Gestión de roles de usuario

1. Inicia sesión como usuario admin a través del puerto 8971.
2. Navega a Configuración > Usuarios.
3. Edita el rol de un usuario seleccionando admin o viewer.

Guía de autenticación de la API

Obtener un token de portador

Para usar la API de SecureVu, primero debes autenticarte. Sigue estos pasos para obtener un token de portador:

1. Inicio de sesión

Realiza una solicitud POST a /login con tus credenciales:

curl -i -X POST https://securevu_ip:8971/api/login \
  -H "Content-Type: application/json" \
  -d '{"user": "admin", "password": "your_password"}'

nota

Es posible que debas incluir -k en la lista de argumentos en estos pasos (p. ej.: curl -k -i -X POST ...) si tu instancia de SecureVu usa un certificado autofirmado.

La respuesta contendrá una cookie con el token JWT.

2. Usar el token de portador

Una vez que tengas el token, inclúyelo en la cabecera de Authorization para las solicitudes posteriores:

curl -H "Authorization: Bearer <your_token>" https://securevu_ip:8971/api/profile

3. Ciclo de vida del token

• Los tokens son válidos durante la duración de sesión configurada
• Los tokens se actualizan automáticamente cuando visitas el endpoint /auth
• Los tokens se invalidan cuando se cambia la contraseña del usuario
• Usa /logout para borrar tu cookie de sesión