Instalar Lockatus

Lockatus se distribuye como una única imagen Docker más una base de datos Postgres. Genera su clave de firma RS256 en el primer arranque (almacenada cifrada en la base de datos) y siembra el primer superadmin — así que un solo docker compose up te da un hub de identidad funcionando.

Requisitos

Docker

El camino soportado. El docker compose incluido levanta el hub y Postgres juntos.

Una clave maestra

LOCKATUS_SECRET cifra los secretos TOTP y firma la sesión del hub. Genera 32 bytes aleatorios.

Una URL de issuer alcanzable

LOCKATUS_ISSUER es la URL pública que llevan los tokens — debe ser alcanzable tanto desde el navegador como desde las apps federadas.

Ejecutar con Docker

git clone https://github.com/diegoparras/lockatus.git && cd lockatus
cp .env.example .env        # set POSTGRES_PASSWORD and LOCKATUS_SECRET
docker compose up -d --build
docker compose logs lockatus   # the generated admin password is printed once here
# → http://localhost:8081

Genera la clave maestra con:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

La URL del issuer

Para un solo host, http://localhost:8081 está bien. Cuando las apps corren en contenedores separados, usa una URL que resuelva igual desde el navegador y los contenedores (por ejemplo http://host.docker.internal:8081 en Docker Desktop), para que el redirect front-channel y la verificación JWKS offline coincidan.

Primera ejecución

1. Abre http://localhost:8081 e inicia sesión como LOCKATUS_ADMIN_EMAIL con la contraseña impresa una sola vez en los logs (o la que hayas definido en LOCKATUS_ADMIN_PASS).
2. En Acceso, la matriz muestra quién tiene qué rol en cada app. Crea usuarios y asigna roles.
3. Opcionalmente registra dos factores para tu cuenta, y agrega cualquier nueva app de la familia desde la matriz con el botón + App.

Endpoints de discovery OIDC

Route	Propósito
GET /health	Salud del servicio (y estado de la base de datos).
GET /.well-known/openid-configuration	Metadatos del issuer para el discovery OIDC.
GET /jwks.json	La clave pública, para que las apps verifiquen los tokens offline.

Variables de entorno

Variable	Default	Descripción
POSTGRES_PASSWORD	(requerido)	Contraseña de la base de datos.
LOCKATUS_SECRET	(requerido)	Clave maestra — cifra los secretos TOTP y firma la sesión del hub.
LOCKATUS_ISSUER	http://localhost:8081	URL pública del issuer embebida en los tokens.
LOCKATUS_ADMIN_EMAIL	admin@lockatus.local	El primer superadmin.
LOCKATUS_ADMIN_PASS	(vacío)	Vacío → se genera y se imprime una sola vez en los logs.
LOCKATUS_SECURE_COOKIE	0	Define 1 detrás de TLS.
LOCKATUS_PORT	8081	Puerto del host.