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.
localis 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.
| Role | What it may do |
|---|---|
| Administrator | Everything, including who may do what and the cluster itself. Must use a second factor |
| Operator | Everything except managing access and forming, joining or changing the cluster |
| Auditor | See everything — servers, machines, images, storage, networks, tenants, accounts, the cluster — and read the audit log; change nothing |
| VMAdmin | Everything about virtual machines (create, delete, power, consoles, size, disks, network cards, guest agent, snapshots, backups, moves to another member); see images, storage and networks |
| VMUser | See machines, start and stop them, open their consoles, use the guest agent |
| NetworkAdmin | Create, change and delete networks; see and change a server's network settings |
| StorageAdmin | Create, grow and delete volumes; restore and delete backups; add and delete images; snapshot and back up machines' volumes; see machines |
| TenantManager | Create, change and delete tenants and their quotas; suspend, resume and limit them; revoke their keys; see their machines, networks, storage and images |
| Billing | See tenants; suspend, resume and limit them |
| Support | See machines, start and stop them, open their consoles, use the guest agent; see tenants and networks |
| NoAccess | Nothing: 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:
| To | You need, on the server | Built-in roles that hold it |
|---|---|---|
| See its settings, its system log and its configuration export | Sys.Audit | Administrator, Operator, Auditor, NetworkAdmin |
| Change them (firewall, load balancers, BGP, VRF, Geneve, NAT64, DNS forwarders, certificates, an alert's resolution) | Sys.Modify | Administrator, Operator, NetworkAdmin |
| Check for, apply or roll back an update | Sys.Update | Administrator, Operator |
| Start the cluster's rolling update | Sys.Update on every member | Administrator, 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.
| Privilege | Allows |
|---|---|
Sys.Audit | See a server's status, settings and history |
Sys.Modify | Change a server's network settings |
Sys.Update | Update a server's software (not used yet) |
Sys.Console | Open a shell on a server (not used yet) |
VM.Audit | See virtual machines |
VM.PowerMgmt | Start, stop and restart virtual machines |
VM.Console | Open a virtual machine's console |
VM.Allocate | Create, clone and delete virtual machines |
VM.Config.CPU | Change a virtual machine's processors |
VM.Config.Memory | Change a virtual machine's memory |
VM.Config.Disk | Change a virtual machine's disks and CD-ROM drives |
VM.Config.Network | Change a virtual machine's network cards |
VM.Config.CloudInit | Change a virtual machine's first-boot settings |
VM.Config.Options | Change a virtual machine's name, protection, boot order and start-at-boot setting |
VM.GuestAgent | Use a virtual machine's guest agent, such as resetting a password |
VM.Snapshot | Take, revert and delete snapshots |
VM.Backup | Back up virtual machine volumes and set their retention |
VM.Migrate | Move a virtual machine to another member, and move several at once; each machine is checked on its own |
Image.Audit | See base images, templates and installation discs |
Image.Allocate | Add and delete base images, catalogue images, templates and installation discs; share a template |
Storage.Audit | See volumes, snapshots, backups and backup schedules |
Storage.Allocate | Create, grow, attach and delete volumes |
Storage.Backup | Restore and delete backups; set, run and remove backup schedules |
Network.Audit | See networks and addresses |
Network.Allocate | Create and delete networks |
Network.Modify | Change networks and attach machines to them |
Tenant.Audit | See tenants |
Tenant.Modify | Create, change and delete tenants and their quotas |
Tenant.Billing | Suspend, resume and limit tenants |
Tenant.Keys | Manage tenants' keys |
Access.Audit | See accounts, groups, roles, permissions, tokens and sign-in methods |
Access.Modify | Manage accounts, groups, roles, permissions, tokens and sign-in methods |
Access.Token | Manage one's own API tokens |
Cluster.Audit | See the cluster |
Cluster.Modify | Form, join, leave and change the cluster, and put a member into maintenance or end it |
Audit.Read | Read 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
| Path | What it covers |
|---|---|
/ | Everything |
/nodes/<node> | One server: its status and settings, its networks, its storage and its images |
/nodes/<node>/storage | One 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/members | The cluster, and its members |
/audit | The 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 —
/vmscovers 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-1a2b3c4dleave 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.Modifyon 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.Modifyon the account:
--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:
- 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. - 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.
- 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.Tokenon your account (/access/users/<you>): Administrator and Operator have it; give it to others with a custom role. Anyone else's tokens needAccess.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
httpsissuer 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 — orsub.alicesigning in withcorpisalice@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-autocreatelets 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.
Link people to the console, not to the sign-in address
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 says | What to do |
|---|---|
sign-in with <name> did not complete; try again | Try 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 address | The sign-in method names accounts by email: verify the address at the provider |
sign-in with <name> took too long; try again | Start 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
| Task | Command line | API |
|---|---|---|
| Accounts | user add, list, show, set, passwd, delete | /api/v1/access/users |
| Second factors | user tfa show, user tfa reset | /api/v1/access/users/{id}/tfa |
| Groups | group add, list, show, delete, member add, member remove | /api/v1/access/groups |
| Roles | role list, show, add, set, delete | /api/v1/access/roles |
| Permissions | acl list, add, remove | /api/v1/access/acl |
| API tokens | token add, list, revoke | /api/v1/access/users/{id}/tokens, /api/v1/access/tokens |
| Sign-in methods | realm 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
- The Web Console — signing in, your account and the Permissions pages.
- Security — what is protected, and your checklist.
- Tenants & Bandwidth — tenant keys and the customer portal.
- Clustering Overview — what a cluster shares.