Accounts and console users

The Orchestrator has three kinds of users. They live in different places and do different things.

Kind	Where it exists	What it is for
Global administrator	`ORC_ADMIN_USER` and `ORC_ADMIN_PASSWORD`, plus the API token	Everything in the console.
Console users	The Orchestrator's database, Console users page	People who manage only the workspaces they own.
Accounts	The Orchestrator's database, Accounts page	Users that exist inside every workspace.

Accounts in every workspace

The Accounts page lists the users every workspace gets: a user name, an optional name and e-mail, a password and a role (User, Read-only administrator or Administrator). Only the global administrator edits them. Passwords are never sent back to the console. An account saved without a password keeps its stored one.

When they are applied

Each time a workspace comes online, before the proxy lets anyone in.
In every running workspace when you save the list.
A sleeping workspace that misses an account, or has an older version of one, is woken, waited for, set up and put back to sleep, one at a time. It stays up if somebody opens it meanwhile or it is kept warm.
Each workspace remembers a fingerprint of the accounts it was given, so a save that changes nothing wakes nothing.
A sleeping workspace is never woken by stopping another one for room (ORC_MAX_RUNNING_INSTANCES). It gets the accounts on its next start.
A password changed inside a workspace is set back to the listed one on its next start.

Only the users the Orchestrator created

Each workspace's record lists the users the Orchestrator created there. A user of the same name that someone made inside a workspace by hand is left as it is: no password set, never disabled or deleted. The workspace's activity says so.

Disable and delete

Disable keeps the account in the list. Where the Orchestrator created it, the account gets a random password nobody knows and loses the administrator role, which also ends its open sessions. Enable sets the password and role back.
Delete asks you to type delete, then removes the account from the list and deletes the user wherever the Orchestrator created it, sleeping workspaces included. A workspace that could not be reached deletes it on its next start. Deleting cannot be undone.
An account left out of a saved list, rather than deleted, is only no longer managed. It stays in the workspaces.
admin is the Orchestrator's own account and cannot be listed.

The name and e-mail are applied when an account is created only.

Guest account

A workspace's Settings tab and the new workspace form have two options:

Guest account turns on Studio's guest account. Anyone who opens the workspace can sign in as guest with the password guest.
Sign visitors in as guest skips the sign-in page for them.

They are Studio's EnableGuestAccount and AutoSignInGuest interface options. The Orchestrator applies them as the workspace's administrator when the workspace is online: at once for a running one, on the next start for a sleeping one. It applies a value only when you change it here, so a guest account turned on or off inside the workspace is left alone until the setting changes.

Signing in on the landing page

With ORC_LANDING_SIGN_IN=true, the landing page shows a sign-in form instead of the workspaces. It takes the user name and password of one of the Accounts. Not a console user, and not a workspace's own users. After that it lists the workspaces, and every one of them opens already signed in as that account, from a card or from an address that is typed or bookmarked, on the path route and on the subdomain.

sequenceDiagram participant B as Browser participant O as Orchestrator participant W as Workspace B->>O: POST /api/account/sign-in O-->>B: orc-account cookie B->>O: GET /acme/api/login/check (no token of its own) O->>W: POST /api/login/create as the account O->>W: GET /api/login/check with the token W-->>B: the token, which Studio's front-end keeps

The session is a random token in the orc-account cookie, with its SHA-256 in the database, for ORC_SESSION_HOURS (12). It is separate from the console's session. It ends when the account is disabled, deleted or given a new password. Failed sign-ins are throttled per client address, 5 in 5 minutes.
Which requests get a token: only those the workspace's own pages make (Sec-Fetch-Site same-origin, or none for a typed address), and only those without a token of their own or with an expired one. A token the visitor already has is left alone.
Signing out on the landing page ends its session and removes the tokens the workspaces' front-ends keep on the Orchestrator's origin. A workspace open on its own subdomain keeps its token until it signs out there or the token expires. Signing out inside a workspace ends the landing page's session too.
When there is no token to give, the workspace shows its own sign-in form. That happens when the workspace has not been given this version of the account yet, or when a user of that name exists there that the Orchestrator did not create.
On localhost or an IP address, browsers refuse a domain cookie, so the subdomain route opens unsigned there.
Waking and the workspaces themselves are not gated. A workspace still asks for its own sign-in when it is reached without the landing page.

Studio image requirement

Landing sign-in needs a Studio image whose login/check answers the token as text. An older image answers a JSON array, which its front-end cannot use, so the workspace shows its own sign-in form. On older images, a second workspace opened in the same browser tab may not load; open it in a new tab.

Console users

The Console users page adds people who sign in to the console with their own name and password, next to the global administrator.

Setting	Effect
User name, display name, password	Passwords are stored as PBKDF2-SHA256 hashes. A user name cannot be the administrator's.
Address prefix	With `acme`, every workspace the user creates is served under `/acme-…/` and `acme-….<host>`. The prefix is added to whatever address the user types.
Workspaces at once	How many workspaces the user may have created that still exist. Deleting one frees its place. Empty is no limit, `0` lets the user only manage what it is given.
Manages	Workspaces the user owns.
Disabled	Ends the user's sessions and refuses sign-in.

What a console user can do

It sees and manages the workspaces it owns, and nothing of the others. Lists, activity and operations are filtered. Any route under api/admin/instances/<slug>/ of a workspace it does not own answers 403.
Within its own workspaces it does everything the administrator does (start, stop, settings, logs, backups, the administrator account, delete), except change the image. A user's workspaces run the default image.
The server's usage (the overview's CPU, memory, disk and charts) is visible to everyone.
Images, Accounts, Settings, Nodes, Console users and Custom HTML are the global administrator's and answer 403 to others. So do Update all, Check for updates, moving and adopting.

Ownership

A workspace a user creates is owned by that user. Any owner can add other console users as owners on the workspace's Owners tab and remove them again, but never itself nor the user who created the workspace. The global administrator gives and takes away any workspace, from the Owners tab or from the user's Manages list.

Disabling a user, deleting it or setting a new password ends its sessions at once.

Custom HTML

Custom HTML (global administrator only) holds CSS and HTML that the Orchestrator adds to every page it serves: the landing page, the starting page and the console. The server puts the CSS in a <style> at the end of the head and the HTML at the end of the body when it serves index.html. The file on disk is never changed, and nothing is added while both fields are empty. Workspaces serve their own pages and are not affected.

Custom HTML runs on every page of the Orchestrator, the console included, so treat it as code with the administrator's rights.