Skip to content
Thermite SCADA
Docs · Operate

Users, roles & security

View as Markdown

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.

[auth]

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.

thermite-passwd

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.auth]

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.

Role flags

Permissions with authentication enabled.

Flag
Default
Status
Gates
can_write_tags
false
Enforced
With authentication enabled, permits writes through the project API.
can_read_history
true
Enforced
With authentication enabled, permits project history queries.
can_ack_alarms
false
Enforced
With authentication enabled, permits acknowledgement and shelving through the project alarm API.
can_run_queries
false
Reserved
Accepted in config; no project route enforces this flag.
can_trigger_transactions
false
Reserved
Accepted in config; no project route enforces this flag.
can_run_reports
false
Reserved
Accepted in config; no project route enforces this flag.
Sessions

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.
TLS

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.