Exclusive Access · Invitation Only

Accounts and Access Control

Who may manage your servers, and what each of them may do. People get their own accounts, sign in with a password and a second factor or through your organisation's identity provider, and are given roles on paths — the whole system, one server, one customer, one machine. Scripts get API tokens that can do no more than the account they belong to. The web console and the API apply the same rules on every server; root on a server's command line is always an administrator.

This page is about access to your servers: their web console and their API. Your account on this website — orders, licences, invoices — is separate; see Your account.

What you get

  • Accounts for people, each signing in with their own password, and a second factor (an authenticator app) where you require one. Administrators always need one.
  • Sign-in through your identity provider (OpenID Connect), next to or instead of passwords.
  • Groups, so a role is given to several people at once.
  • Roles, built in or your own, given on a path, so someone can manage one customer's machines and nothing else.
  • Personal API tokens for scripts, narrowed to exactly what the script needs.
  • Your password again before a sensitive change, so a session left open cannot be used to give someone more power.
  • Immediate revocation. Disabling an account or revoking a token ends what it opened, consoles included, at once.

None of this is a licence feature: every plan has it, and a frozen licence never stops you changing who may do what.

When it is available

A server on its own has access control as soon as it runs this release. In a cluster, it starts once every member runs this release. Until then the access settings answer 409:

access control is available once every node of this cluster runs version <v>; <n> nodes still need the update

Nothing that worked before stops working, before or after:

  • The node's API token keeps full control of its node.
  • Operator API keys (apikeys mint) keep working, with the same full control. They become API tokens of a built-in account, apikeys@local, so you can see them, narrow them and revoke them like any other token (see Operator API keys).
  • Tenant keys and the customer portal keep working; see Tenants & Bandwidth.
  • Root on a server's command line is an administrator, always.

The first administrator

On the server, as root — the password is read at a prompt, never from the command line:

sudo cenvero-str-ctl user add alice@local --display-name "Alice" --role Administrator --password-stdin

Then open the web console (https://<server>:7070/console/) and sign in as alice with that password. An Administrator must use a second factor, so the console first asks you to set one up: scan the code with an authenticator app, enter the code it shows, and store the ten recovery codes it gives you. Then the console opens.

You can do the same from the web console: sign in with the node's API token (sudo cat /etc/cenvero-str/api-token on a server installed with the compute or suite profile). A banner says you signed in with the node's own token; Accounts takes you to Datacenter › Permissions, where Add account makes the account and Add permission gives it Administrator on /.

Make a second Administrator before you need one. The last account that can manage access cannot be deleted, disabled or have that role taken away:

this is the last account that can manage access; give another account Administrator first

Accounts and sign-in methods

An account's id is its name and its sign-in method (a realm), joined by @: alice@local, bob@corp.

  • local is built in: Stratum accounts with a password. Names are lower case: letters, digits, ., _ and -, up to 64 characters.
  • An identity provider you add is a sign-in method of its own, such as corp. Its accounts sign in there; Stratum never holds their password (see Signing in through your identity provider).

An account can be disabled (it cannot sign in, and its tokens stop working), given an expiry (from that moment, UTC, the same), made to use a second factor whatever its roles, and deleted, which removes its tokens, second factor and permissions with it. A new account can do nothing until it is given a role.

sudo cenvero-str-ctl user add bob@local --display-name Bob --role Support --path /tenants/t-acme
printf '%s\n' "$NEW_PASSWORD" | sudo cenvero-str-ctl user passwd bob@local --password-stdin
sudo cenvero-str-ctl user set bob@local --expires 2027-01-01
sudo cenvero-str-ctl user set bob@local --enabled=false
cenvero-str-ctl user list

A password has at least 12 characters and is not one of the most common passwords; there are no other rules, so a long phrase is the easiest to remember. It is never shown, logged or stored: only a one-way check value is kept.

Groups

A group holds accounts. A role given to a group is held by every member, so a team is set up once:

sudo cenvero-str-ctl group add ops --comment "On-call operators"
sudo cenvero-str-ctl group member add ops alice@local
sudo cenvero-str-ctl acl add --path / --group ops --role Operator

Deleting a group removes its permissions; its members keep their accounts.

Roles

A role is a named set of privileges. You give a role on a path; the privileges then apply there.

The built-in roles

They never change. cenvero-str-ctl role show <role> lists a role's privileges.

RoleWhat it may do
AdministratorEverything, including who may do what and the cluster itself. Must use a second factor
OperatorEverything except managing access and forming, joining or changing the cluster
AuditorSee everything — servers, machines, images, storage, networks, tenants, accounts, the cluster — and read the audit log; change nothing
VMAdminEverything about virtual machines (create, delete, power, consoles, size, disks, network cards, guest agent, snapshots, backups, moves to another member); see images, storage and networks
VMUserSee machines, start and stop them, open their consoles, use the guest agent
NetworkAdminCreate, change and delete networks; see and change a server's network settings
StorageAdminCreate, grow and delete volumes; restore and delete backups; add and delete images; snapshot and back up machines' volumes; see machines
TenantManagerCreate, change and delete tenants and their quotas; suspend, resume and limit them; revoke their keys; see their machines, networks, storage and images
BillingSee tenants; suspend, resume and limit them
SupportSee machines, start and stop them, open their consoles, use the guest agent; see tenants and networks
NoAccessNothing: given on a path, it takes away what a wider path gives there

Custom roles

Make your own for anything else. A custom role's name starts with a capital letter, and it can require a second factor of anyone who holds it:

sudo cenvero-str-ctl role add TenantSupport --privileges Tenant.Audit,VM.Audit,VM.PowerMgmt
sudo cenvero-str-ctl role set TenantSupport --require-tfa

Deleting a custom role removes every permission that gives it.

Which role reaches a server's settings

A server's own settings pages in the web console — Interfaces, Routing, Firewall, Services, Traffic, Backups, Certificates, **System log and Updates** — and the API routes behind them follow the server's privileges:

ToYou need, on the serverBuilt-in roles that hold it
See its settings, its system log and its configuration exportSys.AuditAdministrator, Operator, Auditor, NetworkAdmin
Change them (firewall, load balancers, BGP, VRF, Geneve, NAT64, DNS forwarders, certificates, an alert's resolution)Sys.ModifyAdministrator, Operator, NetworkAdmin
Check for, apply or roll back an updateSys.UpdateAdministrator, Operator
Start the cluster's rolling updateSys.Update on every memberAdministrator, Operator

No role puts the server's own certificate on a web (layer-7) frontend, or changes the pools such a frontend routes to: only root does, with cenvero-str-ctl on the command line. Over the API and in the web console such a frontend can only be removed (see Load Balancer).

The Datacenter › Options page — the brand and the notification settings — needs Cluster.Audit on /cluster to see (Administrator, Operator, Auditor) and Cluster.Modify to change (Administrator only), with your password again. Every signed-in person reads the tags' colours. An object's tags and notes follow that object's own privileges: whoever may see a machine sees its tags, and changing them needs the privilege that changes the object (VM.Config.Options for a machine, Network.Modify for a network, Storage.Allocate for a volume, Image.Allocate for an image, Tenant.Modify for a tenant, Sys.Modify for a server). A tag never grants or takes away access.

Every privilege

GET /api/v1/access/privileges lists them with these descriptions.

PrivilegeAllows
Sys.AuditSee a server's status, settings and history
Sys.ModifyChange a server's network settings
Sys.UpdateUpdate a server's software (not used yet)
Sys.ConsoleOpen a shell on a server (not used yet)
VM.AuditSee virtual machines
VM.PowerMgmtStart, stop and restart virtual machines
VM.ConsoleOpen a virtual machine's console
VM.AllocateCreate, clone and delete virtual machines
VM.Config.CPUChange a virtual machine's processors
VM.Config.MemoryChange a virtual machine's memory
VM.Config.DiskChange a virtual machine's disks and CD-ROM drives
VM.Config.NetworkChange a virtual machine's network cards
VM.Config.CloudInitChange a virtual machine's first-boot settings
VM.Config.OptionsChange a virtual machine's name, protection, boot order and start-at-boot setting
VM.GuestAgentUse a virtual machine's guest agent, such as resetting a password
VM.SnapshotTake, revert and delete snapshots
VM.BackupBack up virtual machine volumes and set their retention
VM.MigrateMove a virtual machine to another member, and move several at once; each machine is checked on its own
Image.AuditSee base images, templates and installation discs
Image.AllocateAdd and delete base images, catalogue images, templates and installation discs; share a template
Storage.AuditSee volumes, snapshots, backups and backup schedules
Storage.AllocateCreate, grow, attach and delete volumes
Storage.BackupRestore and delete backups; set, run and remove backup schedules
Network.AuditSee networks and addresses
Network.AllocateCreate and delete networks
Network.ModifyChange networks and attach machines to them
Tenant.AuditSee tenants
Tenant.ModifyCreate, change and delete tenants and their quotas
Tenant.BillingSuspend, resume and limit tenants
Tenant.KeysManage tenants' keys
Access.AuditSee accounts, groups, roles, permissions, tokens and sign-in methods
Access.ModifyManage accounts, groups, roles, permissions, tokens and sign-in methods
Access.TokenManage one's own API tokens
Cluster.AuditSee the cluster
Cluster.ModifyForm, join, leave and change the cluster, and put a member into maintenance or end it
Audit.ReadRead the audit log

Some changes need more than one privilege. Attaching a volume to a machine also needs VM.Config.Disk on the machine. Making a tenant key needs Tenant.Keys and also everything the key lets its holder do on that tenant (see it, its machines and networks, start and stop the machines, open their consoles, use the guest agent), because whoever holds the key can do those things: an Operator or Administrator on the tenant can, a TenantManager cannot.

Permissions

A permission gives one role, on one path, to an account, a group or an API token.

sudo cenvero-str-ctl acl add --path /tenants/t-acme --user bob@local --role Support
cenvero-str-ctl acl list --path /tenants/t-acme
sudo cenvero-str-ctl acl remove <entry-id>

Paths

PathWhat it covers
/Everything
/nodes/<node>One server: its status and settings, its networks, its storage and its images
/nodes/<node>/storageOne server's volumes and images
/vms, /vms/<id>Every virtual machine, or one
/tenants, /tenants/<id>Every tenant, or one: the tenant, and its machines, networks and volumes
/networks/<node>/<id>One network, with its endpoints
/volumes/<id>One volume, with its snapshots and backups
/images/<node>/<id>One base image
/isos/<node>/<id>One installation disc in a server's disc library
/access, /access/users/<id>, /access/groups/<id>, /access/realms/<id>Accounts, groups and sign-in methods
/cluster, /cluster/membersThe cluster, and its members
/auditThe audit log

<node> is a server's id, as GET /api/v1/nodes lists it. A permission may name something that does not exist yet: it applies once it does.

How a permission reaches an object

  • Below its path. A permission applies to its path and everything below it — /vms covers every machine — unless it is made with --no-propagate ("propagate": false), which keeps it to the path itself.
  • From every path the object belongs to. A machine is reached from its own path and from its tenant's; a volume from its own, its tenant's and its server's storage; a network from its own, its tenant's and its server's; an image from its own and its server's storage. What reaches it from each is added together. A permission on a server does not reach the machines on it: give those on /vms, on their tenant, or on /.
  • The most specific path decides. Along one path, the deepest level that holds a permission for you replaces what is above it. So Operator on / and Auditor on /vms/vm-1a2b3c4d leave you an Auditor on that machine. Your own permissions and your groups' at the same level are added together.
  • NoAccess takes away. NoAccess on a path leaves nothing there for you, whatever else is given at that level. NoAccess on an object's own path always wins, even over what its tenant gives.

Example: a support desk for one customer

sudo cenvero-str-ctl group add acme-support
sudo cenvero-str-ctl group member add acme-support bob@local
sudo cenvero-str-ctl acl add --path /tenants/t-acme --group acme-support --role Support

Bob now sees tenant t-acme, its machines and its networks, can start, stop and restart those machines, open their consoles and reset a guest password. He does not see any other tenant, your own machines, or the servers' settings: in the console his tree holds only what he may see, and the API answers for anything else as if it did not exist.

To keep him away from one of that customer's machines:

sudo cenvero-str-ctl acl add --path /vms/vm-1a2b3c4d --user bob@local --role NoAccess --no-propagate

Who may grant what

  • Giving and removing permissions needs Access.Modify on the permission's path.
  • Nobody can give a role with privileges they do not hold on that path. Removing a NoAccess also needs everything it would give back — for a NoAccess on a machine, volume, network or image, including what its tenant or its server would give.
  • A permission that reaches below its path needs what it gives on every path below it: someone kept out of a path cannot grant a role above it that would reach it, add someone to a group that would, or hand over an account that holds it.
  • Handing someone an account is giving them what it holds. These need every permission the account holds, where it holds it, as well as Access.Modify on the account:
- setting another account's password, or resetting its second factor; - making another account an API token that holds everything it holds (--no-privsep); - enabling an account again, or moving its expiry later or removing it; - enabling a sign-in method again (for the accounts it brings back); - for a sign-in method through your identity provider, mapping a group or trusting the provider's second factor (see Signing in through your identity provider).

An account that holds nothing can be managed with Access.Modify alone.

you cannot grant a role with privileges you do not hold on <path>
  • Giving Administrator, or any role that can manage access, asks for your password again, and so does a removal that gives that power back (see Confirming your password). Taking power away never does.

cenvero-str-ctl role list, acl list and, in the console, Datacenter › Permissions show who holds what; a machine's, a network's and a tenant's Permissions tab shows and adds the permissions on that object.

What a refusal looks like

  • Something you may not see answers exactly as if it did not exist: the same 404 and the same words as a wrong id. A list holds only what you may see; it is never refused. So "not found" is the honest answer for an object that exists but is not yours, and nobody learns what else runs on a server.
  • Something you may see but not change answers 403, naming what is missing and where:
{"error":"you do not have permission to do this: it needs VM.PowerMgmt on /vms/vm-1a2b3c4d","missing_privilege":"VM.PowerMgmt","path":"/vms/vm-1a2b3c4d"}

To ask what you may do before you try, use GET /api/v1/access/permissions (see the API Reference). The web console asks it for you: a button you may not use is shown disabled, saying which privilege it needs.

Signing in with a password

The console's sign-in page offers your sign-in methods. For a Stratum account:

  1. Enter your user name and password. Any failure — a wrong password, an unknown, disabled or expired account — gives the same answer: that user name and password were not accepted.
  2. If the account has an authenticator app, enter the 6-digit code it shows (or Use a recovery code instead). You have five minutes and five tries.
  3. An account that must use a second factor but has none yet can only set one up: the console shows Set up a second factor, and opens once it is done.

After five failed attempts for a user name, it must wait a minute before the next, doubling up to 15 minutes (too many failed attempts; try again in a few minutes). The wait is the same for names that exist and names that do not. Failed attempts also count towards the address's lock-out on the API. Sign-in attempts are also limited per address; all addresses of one IPv6 /64 network count as one. Past the limit the sign-in page says too many sign-in attempts; wait a minute and try again.

A second factor

Any authenticator app works: on a phone, or in a password manager. It shows a new 6-digit code every 30 seconds. Set it up under Your account › Second factor (or at your first sign-in when you must have one): scan the code the console shows, or type the key shown under it, then enter the code the app shows. Each code works once. On a cluster, a code is refused on every member once every member runs this release; until then it works once on each member.

An account must use a second factor when Must use a second factor is set on it (user set <id> --require-tfa), or when any role it holds, directly or through a group, requires one. Administrator always does; custom roles can. user tfa show <id> and Datacenter › Permissions › Second factors show who has one and who must set one up.

Recovery codes

When you set up the authenticator you get ten recovery codes, shown once: print them or store them somewhere safe, away from the device that holds the authenticator. Each lets you sign in once without the app. Your account › Second factor › New recovery codes replaces them all; the old ones stop working.

If a second factor is lost

  • You still have a recovery code: sign in with it, then under Your account › Second factor choose Replace the authenticator. Make new recovery codes if few are left.
  • You have none left: ask an administrator — someone who holds at least what your account holds — to reset it: Datacenter › Permissions › Second factors › Reset, or sudo cenvero-str-ctl user tfa reset <id>. Your authenticator and recovery codes stop working; if your account must have a second factor, you set up a new one at your next sign-in.
  • The only administrator lost theirs: root on any server can reset it, and set a new password, from the command line:
sudo cenvero-str-ctl user tfa reset alice@local
printf '%s\n' "$NEW_PASSWORD" | sudo cenvero-str-ctl user passwd alice@local --password-stdin

A forgotten password is set again the same way, by an administrator (the Password button on the account) or by root.

Sessions

A session ends after 30 minutes without activity, after 12 hours in all, when you sign out, and when the agent restarts. One account holds at most eight sessions at once; signing in a ninth time closes its least recently used one, so nobody can sign others out by signing in repeatedly. An API token's sessions count with its account's eight. Each server records the last sign-in it saw.

Changing or resetting a password signs the account out everywhere at once: every session that signed in before the change ends, on every server, and the session you changed your own password in carries on. Setting up a new authenticator app, removing the second factor, or deleting an account and making it again under the same name does the same.

Console tickets

The web console and the customer portal open a machine's console with a single-use ticket (see Consoles). Each tenant, each account and each operator API key can hold at most 16 unused console tickets on a server at a time; beyond that the request is refused with too many console tickets are outstanding; use or let some expire first. A ticket is used up when opened and expires after 60 seconds. Some capacity is always kept for the node's own API token and for root.

Confirming your password

A change that gives someone more power, or weakens a sign-in, asks for your password again — and your authenticator's code, if you have one. A confirmation lasts five minutes. Signing in with your password or your authenticator's code counts as one; signing in through your identity provider alone counts only when it asked for its trusted second factor during that sign-in.

It is asked for when you:

  • change any password;
  • set up, replace, remove or reset a second factor, or make new recovery codes;
  • give Administrator, or a role that can manage access (Access.Modify);
  • add someone to a group that holds such a role;
  • create or change a custom role so that it can manage access, or delete one that can;
  • make an API token that holds everything its account holds (--no-privsep);
  • add, change or delete a sign-in method;
  • change the brand (its settings, logo or favicon) or the notification settings, which hold the mail server's password;
  • delete any account, or disable one that holds Administrator;
  • remove a permission (a NoAccess, say), a group member, a group or a role when that gives someone back the power to manage access;
  • enable an account again, or remove or extend its expiry, when it holds Administrator or Access.Modify;
  • stop requiring a second factor for an account or a role.

The web console shows Confirm it is you when a change needs it, and carries on once you have. If you signed in through your identity provider, the console sends you there to sign in again.

These changes can be made by a person in the web console who has confirmed, by root on the server's command line, and with the node's own API token on its own server. An API token or an operator key never can:

an API token cannot make this change; sign in to the web console to make it

Over the API, an unconfirmed session answers 403 confirm your password to make this change, with "reauth_required": true.

API tokens

An API token lets a script or an integration use the API as an account. Its id is <account>!<name>, and its secret — cst_ followed by 64 characters — is shown once, when it is made:

sudo cenvero-str-ctl token add alice@local ci --comment "deploy pipeline" --expires 2027-01-01
sudo cenvero-str-ctl acl add --path /vms --token 'alice@local!ci' --role VMUser
Authorization: Bearer cst_…

Quote a token id in your shell: an unquoted ! can be taken as a history expansion.

A token's own permissions

By default a token holds only the permissions given to the token itself, and never more than its account holds: the token above can see, start and stop machines and open their consoles — and only where Alice can too. Give a token just what its job needs. A token made with --no-privsep ("privsep": false) instead holds everything its account holds; making one asks for your password.

  • A token never does more than its account. It stops working the moment it is revoked, its expiry passes, or its account is disabled, expires or is deleted, or its account's sign-in method is disabled.
  • A token can never give another token more than it holds itself, and can never make a change that needs a confirmed password.
  • A token never makes a token that outlives it. A token made by another token expires no later than the token that made it: a later expiry, or none, is cut to that token's own.
  • Managing your own tokens needs Access.Token on your account (/access/users/<you>): Administrator and Operator have it; give it to others with a custom role. Anyone else's tokens need Access.Modify.
  • Each server records the last use of a token it saw.

Operator API keys

Operator API keys (cenvero-str-ctl apikeys mint) are tokens of the built-in account apikeys@local, which nobody signs in as. Each holds Administrator on /, exactly as before. token list shows them, marked as operator keys, with the id apikeys@local!<key id>, and apikeys mint, list and revoke keep working as they always have. Operator keys belong to no sign-in method, so disabling one never stops them. For that reason only apikeys mint, run as root on a server, makes them: no person and no API token can make a token of apikeys@local — make a token of your own account instead.

To narrow one — say the key your billing system uses — replace its permission:

cenvero-str-ctl acl list --token 'apikeys@local!<key id>'   # note its Administrator entry on /
sudo cenvero-str-ctl acl add --path /tenants --token 'apikeys@local!<key id>' --role Billing
sudo cenvero-str-ctl acl remove <that entry's id>

A key you narrowed stays narrowed: it is never widened again on its own.

See Billing Integration for a billing key made from scratch.

Signing in through your identity provider

People can sign in with your organisation's identity provider (any that speaks OpenID Connect) instead of a Stratum password. Each provider is a sign-in method of its own, and the sign-in page offers Sign in with <its name>.

What the provider needs

  • The authorization code flow with PKCE (S256). Register Stratum as a client (with a client secret, or as a public client) and note its client id.
  • Each server's sign-in address, registered with the provider as a redirect address — one per server, at the address people open its console on:
https://<server address>:7070/console/auth/oidc/callback
  • An https issuer address each server can reach, which publishes the provider's settings and signing keys at their standard addresses.
  • Signatures the realm accepts: RS256, ES256 and EdDSA by default, PS256 on request. Others are never accepted.

Setting it up

In the web console: Datacenter › Permissions › Sign-in methods › Add identity provider. From the command line, with the client secret read from standard input:

printf '%s\n' "$CLIENT_SECRET" | sudo cenvero-str-ctl realm add-oidc corp --display-name "Corporate sign-in" \
  --issuer https://id.example.net/realms/corp --client-id stratum --client-secret-stdin \
  --redirect-uri https://node1.example.net:7070/console/auth/oidc/callback \
  --redirect-uri https://node2.example.net:7070/console/auth/oidc/callback \
  --groups-claim groups --group-map stratum-ops=ops
sudo cenvero-str-ctl realm test corp

realm test (Check in the console) fetches the provider's settings and signing keys and says what it found, without signing anyone in. The client secret is never shown again; realm set keeps it unless you give a new one. Adding, changing or deleting a sign-in method asks for your password.

Who an account is

  • The first sign-in names the account, from the claim you choose: preferred_username (the default), email — only when the provider says the address is verified — or sub. alice signing in with corp is alice@corp.
  • From then on the account stays with that person at that provider, whatever the provider later calls them. An account linked to one person is never given to another: this account is linked to another sign-in at <name>.
  • Accounts made at first sign-in have no permissions until you grant them. To prepare one, make it first (user add alice@corp) and give it its roles; the first sign-in links it. --no-autocreate lets only accounts you made sign in.
  • The display name and a verified email follow the provider at each sign-in. Passwords are changed at the provider, never here.

Groups from the provider

With --groups-claim and --group-map provider-group=stratum-group, each sign-in puts the account in exactly the mapped groups the provider lists for the person, and takes it out of mapped groups it no longer lists. Only the groups in the map are touched; groups you manage by hand stay as they are. A provider can never take the last administrator out of a group: that sign-in is refused instead.

Because the provider decides who is in a mapped group, mapping a group — or pointing the sign-in method at another provider, another client or another groups claim — needs every permission the group holds, and everything that taking the method's accounts out of it would give back (a group that holds a NoAccess, for example).

Second factor

Stratum's rule applies to these accounts too: an account that has an authenticator is asked for its code after the provider, and one whose roles require a second factor must set one up. If your provider already asks people for a second factor, --trust-provider-mfa lets Stratum count it, when the provider says it asked. Whoever runs your provider can then sign in as any of the method's accounts without a Stratum code, so turning it on needs every permission held by the method's accounts that have, or must have, a second factor.

A link or tile in your provider's own portal must open the console, https://<server address>:7070/console/, and never the address a sign-in starts at (…/console/auth/oidc/start).

For your people's safety a sign-in only starts from the console's own page, or from an address typed or bookmarked in the browser; one started by a link on another site is refused. The console then shows Sign in with <name>, and the sign-in works.

Open the console at an address you registered: a server opened at an address its sign-in method does not list answers this address is not registered for sign-in with <name>.

When it is refused

The sign-in page saysWhat to do
sign-in with <name> did not complete; try againTry again; if it keeps happening, the server's log says why (the provider's own message is kept there, never shown)
this address is not registered for sign-in with <name>Register this server's sign-in address with the provider and in the sign-in method (--redirect-uri), or open the console at an address that is
your account at <name> has no verified email addressThe sign-in method names accounts by email: verify the address at the provider
sign-in with <name> took too long; try againStart again: a sign-in at the provider must finish within ten minutes
this account is linked to another sign-in at <name>Someone else already signed in to that account; an administrator decides who should have it

A sign-in method can only be deleted once it holds no accounts.

Taking access away

Disabling or deleting an account, letting it expire, disabling its sign-in method, or revoking a token takes effect at once: every session it opened ends, and every machine console it opened closes. Taking a role away also closes the consoles that role allowed. In a cluster this reaches every member within a few seconds.

sudo cenvero-str-ctl user set bob@local --enabled=false
sudo cenvero-str-ctl token revoke 'alice@local!ci'

Revoking never asks for your password: taking power away should always be easy.

In a cluster

  • Accounts, groups, roles, permissions, sign-in methods, API tokens and operator keys belong to the whole cluster. Make them on any member; they work on every member. Each member checks every account and token itself, so a key or token works when you call any member directly, and a revoked one stops on all of them.
  • New accounts. An account created on one server — for example by a person's first sign-in through your identity provider — is recognised by every server of the cluster at once: when a request passed on from another server reaches one that has not yet received the change, that server waits up to a second for it instead of refusing the request.
  • Paths name each member's objects: /nodes/<node> is one member; a machine, network or volume is reached the same way wherever it runs.
  • The node's own API token belongs to its server. Signed in with it, you can act on every member, because that server vouches for you; prefer personal accounts for everyday work.
  • Root on any member can administer the whole cluster, including who may do what. Protect every member as you would the most sensitive one.
  • Each server records the last sign-ins and token uses it saw.

A server cut off from the others

A server that cannot reach the rest of the cluster keeps the access rules it last knew until it can. People can still sign in there, and what they may do is what that server last knew. Changes to accounts and permissions wait:

the cluster has no leader reachable from this node; changes to shared settings are paused until it has one

A first sign-in through your identity provider, or one that would change the account's groups, waits too. A recovery code cannot be used there either, so that it can never be used twice:

a recovery code cannot be used while this server is cut off from the others; use your authenticator app, or try again later

Outside a cut-off, a recovery code is refused with that code was not accepted when it is not written as a recovery code, when it is not one of the account's unused codes (a code is used up by its first use, and new codes replace all the old ones), when the account is disabled or past its expiry, or when the sign-in method it uses is switched off.

The web console says so in a banner, with since when. Changes made elsewhere in the meantime — a revoked token, a disabled account — reach it within a few seconds of the network coming back. Sign in to a member that can reach the others to make changes.

While a server cannot reach the rest of its cluster, or has not yet caught up with it, every audit record it writes includes "identity_stale": "true" in its detail, so you can tell which actions were checked against access settings that may be out of date.

A server catching up

While a server is restarting or joining a cluster and has not yet caught up with the cluster's access settings, it refuses requests passed on to it with an operator API key instead of trusting them; retry once it is back in step, normally within seconds.

Joining a node that has accounts

A node with accounts of its own can join a cluster once every member runs this release; its accounts, tokens and permissions join the cluster's. If one of its accounts has the same id as one of the cluster's but differs, the join is refused with this node's accounts conflict with the cluster's, listing each conflict: change one of them, or join with discard-local-identity, so that the joining node drops its own accounts and takes the cluster's.

When a server joins a cluster, an API token it once revoked — itself, or by deleting its account — whose name matches a token that still exists in the cluster is reported as a conflict, and the join is refused until you resolve it: revoke the token in the cluster, or join with discard-local-identity. An operator key the server revoked is revoked in the cluster too: it is the same key.

While some member still runs an earlier release, a node with accounts is refused (every node of this cluster must run version <v> before a node with accounts can join; …), and once access control is on, a node on an earlier release is refused with update this node to version <v> before it joins.

Commands and API

TaskCommand lineAPI
Accountsuser add, list, show, set, passwd, delete/api/v1/access/users
Second factorsuser tfa show, user tfa reset/api/v1/access/users/{id}/tfa
Groupsgroup add, list, show, delete, member add, member remove/api/v1/access/groups
Rolesrole list, show, add, set, delete/api/v1/access/roles
Permissionsacl list, add, remove/api/v1/access/acl
API tokenstoken add, list, revoke/api/v1/access/users/{id}/tokens, /api/v1/access/tokens
Sign-in methodsrealm list, show, add-oidc, set, delete, test/api/v1/access/realms
What you may do—/api/v1/access/me, /api/v1/access/permissions

Root on the command line acts as an Administrator and never needs to confirm a password. Every command answers with the API's own sentences, and --json prints the API's answer. See the CLI Reference and the API Reference.

See also

↓ This page as JSON ↓ All documentation as JSON