Skip to content

Who may operate it

A shared token cannot say who changed a value or be taken back from one person. In this lesson each person gets a name and a role, and every change is recorded against them. About twenty minutes, on the box from the last lessons.

One command adds an auth: block to nautilus.yaml, naming the people and their roles (run it in the project folder, on your own computer):

Terminal window
naut auth init --user akhan:operator --user jsmith:engineer
nautilus.yaml: wrote a starter auth: block
With it, every request needs a credential: reads too, unless you set anonymous: viewer.
server.tls: self-signed: the controller serves HTTPS with a certificate it makes in its state directory, so passwords never cross the network in the clear.
…
Next:
naut users add akhan # akhan's password, kept on the controller (sudo on a box)
naut users add jsmith # jsmith's password, kept on the controller (sudo on a box)
restart naut run to apply (a built controller: build and deploy it again)

It changed two things in the file. Under server: it added tls: self-signed (the HTTPS part, below), and at the end it added the block:

auth:
users: # viewer < operator < supervisor < engineer < administrator
akhan: [operator]
jsmith: [engineer]
# anonymous: viewer # a request with no credential may read (a wall screen)
# session: 12h # a browser sign-in lasts this long (1m to 168h)
…

The manifest says which user has which role, so it is reviewed in git; the passwords are not in it. The other keys are left as commented examples to turn on when you need them. The built-in roles each add to the one before: viewer reads; operator also writes tags, acknowledges alarms and commands sequences; supervisor shelves alarms and reads the audit journal; engineer also forces, edits online and downloads; administrator manages users. Run naut check (it refuses a misspelt role), then update the box:

Terminal window
naut deploy update deploy@plc1

From now on every GET under /api/ needs the read permission, too. With no credential, a request gets 401, and a screen opened in a browser goes to a sign-in page. Only /healthz and /readyz, which say one word each, answer without one.

Passwords live on the box, in a file the project never contains, managed with the controller itself (the box has no naut):

Terminal window
ssh deploy@plc1
sudo /opt/nautilus/current/controller users --state-dir /var/lib/nautilus add akhan

It asks for the password twice. The controller picks the change up within a second, so do not test it in the same instant. users list shows who exists, users passwd, users disable and users token change them, and every change is journalled with the system user who made it. A user the manifest does not name cannot sign in, whatever the file says.

A script, a historian or the VS Code extension signs in with a personal access token that acts as its user:

Terminal window
sudo /opt/nautilus/current/controller users --state-dir /var/lib/nautilus token akhan
token 001bbaf2fb94084b for akhan (shown once; naut users revoke akhan 001bbaf2fb94084b ends it)

(The token itself, naut_pat_…, is printed on the line before; copy it now, it is not shown again.) Use it as a bearer token, and see exactly what it may do:

Terminal window
curl -s https://plc1:8080/api/me -H "Authorization: Bearer $TOKEN"
{"auth":true,"secure":true,"principal":"user:akhan","roles":["operator"],"permissions":{"*":["read","write","ack","sfc"]}}

akhan can write a setpoint, and cannot force a tag; the refusal names the role and the missing permission:

{"error":"user:akhan (operator) may not force"}

HTTPS, and the certificate’s fingerprint

Section titled “HTTPS, and the certificate’s fingerprint”

A browser sign-in sends a password, so the controller accepts one only over HTTPS. naut auth init already turned that on: tls: self-signed makes the controller create its own certificate the first time it starts, in its state directory on the box, and renew it. The start-up log says so, and prints the certificate’s fingerprint:

Terminal window
ssh deploy@plc1 'sudo journalctl -u nautilus -n 20 --no-pager | grep -A1 self-signed'
controller[1423]: naut run: HTTPS with a self-signed certificate it just made (/var/lib/nautilus/tls/self-signed.pem, until 2027-12-22).
controller[1423]: SHA-256 fingerprint: C1:2C:37:75:EE:0C:7B:9A:F8:82:76:08:83:99:B7:CE:76:70:E0:08:AB:BA:F9:FD:37:24:D9:07:60:20:90:EC

A self-signed certificate is not vouched for by anyone, so a browser warns the first time. The fingerprint is how you know it is your box you are talking to: open https://plc1:8080, look at the certificate in the warning page, and compare. (The same fingerprint from the outside, with openssl s_client -connect plc1:8080 | openssl x509 -noout -fingerprint -sha256.) The log also lists the names and addresses the certificate is valid for.

Plain http:// to that port is refused (400: it speaks only HTTPS). After you accept the certificate, https://plc1:8080 goes to the sign-in page, and after signing in the screen opens. A wrong password and an unknown user both answer the same way, so the page does not say which names exist:

{"error":"sign-in refused: the user name or password is wrong"}

The browser’s session lasts 12 hours by default (auth.session), and a restart of the controller signs everyone out.

For a plant, use a certificate from your own certificate authority, so no browser warns: set server.tls: {cert: /abs/cert.pem, key: /abs/key.pem}. On a box the service’s user cannot read a root-owned key, so the files are handed over as systemd credentials: HTTPS in Continuous deployment has the steps (and notes that they need a real machine or virtual machine, not every container).

A person who can force a tag or edit the program can change what the plant does, so those actions need a fresh password: a signed-in browser holds force, edit, activate, deploy, config, users and override only for a while after its password was last typed (clearing a force counts: it can start a motor). The window is auth.elevation, 15 minutes by default:

auth:
elevation: 15m

Right after signing in, an engineer can force a tag:

{"forces":[{"name":"Sensor","value":20,"sinceMs":1795165440819}]}

Once the window has passed, the same kind of request is refused, and nothing is done. With a one-minute window, clearing the force a minute later gives:

{"elevate":true,"error":"confirm your password to do this: sign in again (/signin), or enter your password where the HMI asks for it (POST /api/elevate). force needs a password entered within the last 1m (auth.elevation)"}

The person confirms their password, by signing in again or, for an HMI of your own, with POST /api/elevate:

{"elevatedUntil":"2026-11-20T09:06:05.890423355Z","user":"jsmith"}

and the action then works. A screen built with the HMI kit does this itself: when the controller refuses an elevated action, it asks for the password in a dialog, sends it, and repeats the action once (the auth guide shows the one call that turns it on). An HMI of your own handles the 401 as above. A user whose roles hold none of these permissions, a viewer or an operator, has nothing to confirm: they get a 403, never a password prompt. Using an action does not extend the window. Tokens, for scripts and the VS Code extension, always count as elevated, since they are sent with every request and their role already limits them. Five wrong passwords in a row end the session. The auth guide has the rest: how the journal records it, and what a redundant pair does.

Users, roles & sign-in covers areas (limit a person to part of the plant), service tokens for monitoring, the audit journal and a redundant pair. Continuous deployment covers certificates, renewal and running behind a proxy.

nautilus is free and open source (Apache 2.0), built by Joy Automation. For implementation or support on your site, see Joy Automation services. Privacy.