Users, roles and security

SiteManager can change displays and flash firmware, so it records every change. What else protects it depends on the mode it runs in.

For step-by-step help, see A tour of SiteManager and Logs and diagnostics (the audit log).

Local mode and network mode

Local mode (the default). The service listens on this computer only, at http://127.0.0.1:8790/. There are no logins, users, roles, API tokens or certificates. Everyone who uses this computer, and every program on it, is the administrator. The Account and Users pages and Log out do not appear, and the sections below on roles, users, your account, sign-in limits and the certificate do not apply. The Audit page does appear.
Network mode. The service listens for other computers and serves HTTPS. It makes everyone sign in, and offers the roles, users and API tokens described below. See Opening SiteManager to the network.

The mode is decided by the --listen address of the service, with no separate switch. A loopback address such as 127.0.0.1:8790 gives local mode, and any other address, such as :8790, gives network mode. See sitemanagerd reference.

Because local mode has no logins, every user and every process on that computer is the administrator. This includes every Remote Desktop session on a shared Windows PC and every account on a shared Linux computer. Use network mode where that is not acceptable.

Local mode is plain HTTP on the loopback address, so nothing leaves the computer. The service also protects the browser: it answers only to the host names localhost, 127.0.0.1 and [::1] on its own port, and refuses a change that comes from another web site's page. See The JSON API.

Users and tokens made in network mode stay in the state directory when you switch to local mode. They are not used there and not deleted, and they work again when you open SiteManager to the network again.

Roles

Roles exist in network mode only. | Role | What it can do | |---|---| | admin | Everything: change settings, run jobs, edit walls, profiles and alerts, manage users, and read the audit log. | | viewer | Look at everything except the Users and Audit pages. A viewer cannot change anything. Secrets, such as passwords, profile values and channel credentials, are shown as hidden. A viewer can download a diagnostics bundle, run a drift check, probe capabilities, run the Check of a firmware rollout, ask SiteManager to read displays faster for a while, and manage their own password, tokens and sessions. |

There is no self-registration. An administrator creates every user.

Users

Open Users in the menu (administrators only). The table lists each user with their role, the number of API tokens and browser sessions, and when they were created. For each user you can:

Set role to admin or viewer;
Set password. This ends that user's browser sessions but keeps their API tokens;
Revoke tokens and sessions: end all of their API tokens and browser sessions;
Remove: delete the user together with their tokens and sessions.

To add a user, fill in Add a user: a Name (1 to 64 characters, matched case-sensitively when you sign in; you cannot create Admin while admin exists, and a name cannot contain / or \), a Password and a Role, then select Add user. A site can have up to 64 users.

Passwords must be at least 12 characters and at most 72 bytes.

Two safeguards protect you from locking yourself out: the last administrator cannot be removed or demoted. When you demote a user, the API tokens that need more than the new role are revoked.

From the command line, an administrator uses sitemanager users. See Command reference.

Your account

Open Account in the menu. Everyone has this page.

API tokens

An API token lets a script or the command line act as you. To create one, enter a name next to New token name and select Create token. The token is shown once. Copy it then, because SiteManager cannot show it again.

A token has the role of the user who created it. A token made with the command line can be given a lower role, for example a viewer token for a read-only dashboard.
Tokens do not expire. You can have up to 100.
Revoke ends one token. It stops working on the next request, even after a restart, and any event stream it opened is closed. Revoke all my tokens ends all of yours, including one you may be using right now.

The table shows each token's name, role, when it was created and when it was last used.

Password

Enter your current password and a new one, then select Change password. Your other browser sessions end. This session stays, and your tokens keep working.

Sessions

A browser login is a session. A session lasts 12 hours and survives a restart of the service. When you sign in a 51st time, your oldest session ends. The table shows when each started, was last used and expires, the address it came from and the browser. Select End to end a session, or End my other sessions to keep only the one you are using.

Audit log

Open Audit in the menu (administrators only, which in local mode is everyone). It shows the 200 most recent entries, newest first: the time, the user, the action, the displays involved, and the values before and after.

In local mode the user of every entry is /local, which the Audit page shows as this computer (local mode). SiteManager writes an entry for every change: sign-ins, setup, user and token changes (network mode), display changes and profile applications, configuration files written, alert changes, and so on. It also records a few actions that change nothing, such as downloading a diagnostics bundle, sending a test message and starting or stopping the touch preview. Asking SiteManager to read displays faster is not recorded.

The display-security actions are in it too, never with a key: display.access.secure, display.access.change, display.access.release, display.access.rotate, display.access.trust, display.access.keep-locked and access.policy, the SSH key changes (with the key's type, fingerprint and comment, so keep secrets out of key comments) and display.update-channel.set (with the old and new address and branch). See Display security.

The full log is the file audit.log in the state directory. It starts a new file at 10 MiB and keeps five. Secrets never appear in it. The same entries are available from the JSON API.

Changes made through the command line in direct mode, and by the old 2.x-style commands, do not go through the service and are not in its audit log.

In network mode, to make guessing passwords hard:

at most 4 password checks run at once across the whole service;
one remote address that fails 10 times within 5 minutes is refused for password logins. The page says too many login attempts, try again later, and the API answers with status 429.

The limit applies only to passwords. API tokens and sessions never trigger a password check, so scripts that use tokens are never slowed down. Existing sessions and tokens keep working while the limit is in effect.

The certificate

In network mode the service creates a self-signed certificate the first time it starts and stores it as tls.crt and tls.key in the state directory. It is valid for 10 years, and covers localhost, the computer's name and its addresses. Your browser warns about it because no certificate authority vouches for it. Check the fingerprint in the page footer instead, as described in First start. A service in local mode has no certificate.

To use a network-mode service from the command line, you pin this fingerprint when you log in, so the command line can tell your service from an impostor. See The command line.

Keeping SiteManager safe

Reach the service directly, not through a reverse proxy. See Ports and firewall.
Put the displays on their own network, separate from guest or public networks, and do not expose them to the internet.
Do not leave local mode on a computer that many people share, if they should not all be administrators. Use network mode there.
Treat diagnostics bundles and the state directory as confidential. The state directory holds the credentials of alert channels, because the service must send them, and in network mode password hashes and the certificate key.
In network mode, give people the lowest role that lets them do their job.