Users, roles & security
Authentication uses cookie sessions and is off by default. Enable it with gateway [auth].enabled = true in server.toml, then configure each project's sources, bindings, and roles in project.toml. A project auth block alone does not enable enforcement.
Gateway admin auth.
# config/server.toml [auth] enabled = true session_ttl_secs = 86400 # 24h (default) cookie_name = "thermite_session" cookie_secure = false # set true behind TLS [[auth.users]] username = "admin" password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…$…" roles = ["admin"]
With authentication enabled, gateway public routes are /login, /logout, GET /api/status (health probes), GET /api/license/status, GET /favicon.ico, /hmi/thermite.js and /hmi/thermite.css when HMI serving is enabled; also GET / and GET /portal/logo when the portal is enabled. Public GET branding assets are /admin/logo and /admin/assets/ followed by base.css, theme.css, roboto.ttf, or roboto-mono.ttf. On a project mount: /login, /logout, /healthz, and /branding/*, /hmi/thermite.js, and /hmi/thermite.css. A project's /api/status and screens require a session. Projects can explicitly permit restricted anonymous access.
Generate password hashes with thermite-passwd.
Passwords are argon2id hashes with per-user random salts. The bundled thermite-passwd binary reads the password from stdin — it refuses arguments, so the secret never has to appear on a command line. Use the interactive prompt for credentials, then store the resulting hash in the user configuration.
# interactive — prompts without echoing $ thermite-passwd # output: paste the generated hash into password_hash $argon2id$v=19$m=19456,t=2,p=1$…$…
Paste the output into a password_hash field — in [[auth.users]] or a project's users.toml.
Project users, bindings, and roles.
With authentication enabled, each project authenticates its operators. A source supplies identities, a binding maps a user to role names, and a role is a set of permission flags. Two source types exist today: embedded (a project-local users.toml) and gateway-source, which today uses the built-in gateway user list. Directory (LDAP/AD) and SSO sources are not integrated.
# projects/press-line/project.toml [project.auth] inherit = false # disable the implicit server credential source sources = ["local"] [project.auth.source.local] type = "embedded" credentials_file = "users.toml" [[project.auth.bindings]] source = "local" username = "operator" roles = ["operator"] [project.auth.roles.operator] can_write_tags = true can_read_history = false # projects/press-line/users.toml [[users]] username = "operator" password_hash = "$argon2id$…"
With authentication enabled, projects require login by default and named users need a matching binding. Setting anonymous_role to a defined role issues restricted anonymous sessions with read permissions; anonymous sessions cannot write tags or acknowledge alarms. Sessions are scoped per project and draft, so a cookie from one is rejected on another.
Permissions with authentication enabled.
Cookies, CSRF, and lifecycles.
- Session cookies are HttpOnly; SameSite=Lax; tokens are 32 random bytes. With authentication enabled, protected state-changing requests need the X-CSRF-Token header matching a JS-readable CSRF cookie (thermite.js handles this for screens). Login and logout are exempt.
- With authentication enabled, WebSocket upgrades use single-use tickets from POST /api/ws-ticket rather than the cookie alone — cross-origin hijack defense.
- Sessions live in memory: restarting the gateway logs everyone out. Logout revokes immediately.
- Per-client login rate limiting is not built in. Rate-limit /login at the proxy if the gateway is reachable from untrusted networks.
Terminate TLS in front of the gateway.
The gateway's HTTP listener is plain HTTP; run it behind a reverse proxy (nginx, Caddy, your load balancer) that terminates TLS, and set cookie_secure = true so browsers refuse to send sessions over plaintext. The TLS that is built in is gateway-to-gateway: mesh links between peers are mutually authenticated with per-gateway certificates pinned by fingerprint.