{
    "product": "Cenvero Stratum",
    "generated_at": "2026-11-16T13:19:22+00:00",
    "format": "cenvero-docs-v1",
    "document_count": 1,
    "documents": [
        {
            "slug": "access-control",
            "title": "Accounts and Access Control",
            "category": null,
            "url": "https://stratum.cenvero.com/docs/access-control",
            "headings": [
                {
                    "level": 1,
                    "text": "Accounts and Access Control"
                },
                {
                    "level": 2,
                    "text": "What you get"
                },
                {
                    "level": 2,
                    "text": "When it is available"
                },
                {
                    "level": 2,
                    "text": "The first administrator"
                },
                {
                    "level": 2,
                    "text": "Accounts and sign-in methods"
                },
                {
                    "level": 2,
                    "text": "Groups"
                },
                {
                    "level": 2,
                    "text": "Roles"
                },
                {
                    "level": 3,
                    "text": "The built-in roles"
                },
                {
                    "level": 3,
                    "text": "Custom roles"
                },
                {
                    "level": 3,
                    "text": "Which role reaches a server's settings"
                },
                {
                    "level": 3,
                    "text": "Every privilege"
                },
                {
                    "level": 2,
                    "text": "Permissions"
                },
                {
                    "level": 3,
                    "text": "Paths"
                },
                {
                    "level": 3,
                    "text": "How a permission reaches an object"
                },
                {
                    "level": 3,
                    "text": "Example: a support desk for one customer"
                },
                {
                    "level": 3,
                    "text": "Who may grant what"
                },
                {
                    "level": 2,
                    "text": "What a refusal looks like"
                },
                {
                    "level": 2,
                    "text": "Signing in with a password"
                },
                {
                    "level": 3,
                    "text": "A second factor"
                },
                {
                    "level": 3,
                    "text": "Recovery codes"
                },
                {
                    "level": 3,
                    "text": "If a second factor is lost"
                },
                {
                    "level": 3,
                    "text": "Sessions"
                },
                {
                    "level": 3,
                    "text": "Console tickets"
                },
                {
                    "level": 2,
                    "text": "Confirming your password"
                },
                {
                    "level": 2,
                    "text": "API tokens"
                },
                {
                    "level": 3,
                    "text": "A token's own permissions"
                },
                {
                    "level": 3,
                    "text": "Operator API keys"
                },
                {
                    "level": 2,
                    "text": "Signing in through your identity provider"
                },
                {
                    "level": 3,
                    "text": "What the provider needs"
                },
                {
                    "level": 3,
                    "text": "Setting it up"
                },
                {
                    "level": 3,
                    "text": "Who an account is"
                },
                {
                    "level": 3,
                    "text": "Groups from the provider"
                },
                {
                    "level": 3,
                    "text": "Second factor"
                },
                {
                    "level": 3,
                    "text": "Link people to the console, not to the sign-in address"
                },
                {
                    "level": 3,
                    "text": "When it is refused"
                },
                {
                    "level": 2,
                    "text": "Taking access away"
                },
                {
                    "level": 2,
                    "text": "In a cluster"
                },
                {
                    "level": 3,
                    "text": "A server cut off from the others"
                },
                {
                    "level": 3,
                    "text": "A server catching up"
                },
                {
                    "level": 3,
                    "text": "Joining a node that has accounts"
                },
                {
                    "level": 2,
                    "text": "Commands and API"
                },
                {
                    "level": 2,
                    "text": "See also"
                }
            ],
            "word_count": 4367,
            "markdown": "# Accounts and Access Control\n\nWho may manage your servers, and what each of them may do. People get their own\n**accounts**, sign in with a password and a second factor or through your\norganisation's identity provider, and are given **roles** on **paths** — the\nwhole system, one server, one customer, one machine. Scripts get **API tokens**\nthat can do no more than the account they belong to. The web console and the\nAPI apply the same rules on every server; root on a server's command line is\nalways an administrator.\n\n> This page is about access to your servers: their web console and their API.\n> Your account on this website — orders, licences, invoices — is separate; see\n> [Your account](/docs/your-account).\n\n## What you get\n\n- **Accounts for people**, each signing in with their own password, and a\n  second factor (an authenticator app) where you require one. Administrators\n  always need one.\n- **Sign-in through your identity provider** (OpenID Connect), next to or\n  instead of passwords.\n- **Groups**, so a role is given to several people at once.\n- **Roles**, built in or your own, given on a **path**, so someone can manage\n  one customer's machines and nothing else.\n- **Personal API tokens** for scripts, narrowed to exactly what the script needs.\n- **Your password again before a sensitive change**, so a session left open\n  cannot be used to give someone more power.\n- **Immediate revocation.** Disabling an account or revoking a token ends what\n  it opened, consoles included, at once.\n\nNone of this is a licence feature: every plan has it, and a frozen licence never\nstops you changing who may do what.\n\n## When it is available\n\nA server on its own has access control as soon as it runs this release. In a\n[cluster](/docs/clustering/overview), it starts once **every member** runs this\nrelease. Until then the access settings answer **409**:\n\n```text\naccess control is available once every node of this cluster runs version <v>; <n> nodes still need the update\n```\n\nNothing that worked before stops working, before or after:\n\n- **The node's API token** keeps full control of its node.\n- **Operator API keys** (`apikeys mint`) keep working, with the same full\n  control. They become API tokens of a built-in account, `apikeys@local`, so you\n  can see them, narrow them and revoke them like any other token (see\n  [Operator API keys](#operator-api-keys)).\n- **Tenant keys** and the customer portal keep working; see\n  [Tenants & Bandwidth](/docs/tenants).\n- **Root on a server's command line** is an administrator, always.\n\n## The first administrator\n\nOn the server, as root — the password is read at a prompt, never from the\ncommand line:\n\n```bash\nsudo cenvero-str-ctl user add alice@local --display-name \"Alice\" --role Administrator --password-stdin\n```\n\nThen open the web console (`https://<server>:7070/console/`) and sign in as\n`alice` with that password. An Administrator must use a second factor, so the\nconsole first asks you to set one up: scan the code with an authenticator app,\nenter the code it shows, and store the ten **recovery codes** it gives you. Then\nthe console opens.\n\nYou can do the same from the web console: sign in with the node's API token\n(`sudo cat /etc/cenvero-str/api-token` on a server installed with the `compute`\nor `suite` profile). A banner says you signed in with the node's own token;\n**Accounts** takes you to **Datacenter › Permissions**, where **Add account**\nmakes the account and **Add permission** gives it **Administrator** on `/`.\n\nMake a second Administrator before you need one. The last account that can\nmanage access cannot be deleted, disabled or have that role taken away:\n\n```text\nthis is the last account that can manage access; give another account Administrator first\n```\n\n## Accounts and sign-in methods\n\nAn account's id is its name and its **sign-in method** (a *realm*), joined by\n`@`: `alice@local`, `bob@corp`.\n\n- **`local`** is built in: Stratum accounts with a password. Names are lower\n  case: letters, digits, `.`, `_` and `-`, up to 64 characters.\n- **An identity provider** you add is a sign-in method of its own, such as\n  `corp`. Its accounts sign in there; Stratum never holds their password (see\n  [Signing in through your identity provider](#signing-in-through-your-identity-provider)).\n\nAn account can be **disabled** (it cannot sign in, and its tokens stop\nworking), given an **expiry** (from that moment, UTC, the same), made to\n**use a second factor** whatever its roles, and **deleted**, which removes its\ntokens, second factor and permissions with it. A new account can do nothing\nuntil it is given a role.\n\n```bash\nsudo cenvero-str-ctl user add bob@local --display-name Bob --role Support --path /tenants/t-acme\nprintf '%s\\n' \"$NEW_PASSWORD\" | sudo cenvero-str-ctl user passwd bob@local --password-stdin\nsudo cenvero-str-ctl user set bob@local --expires 2027-01-01\nsudo cenvero-str-ctl user set bob@local --enabled=false\ncenvero-str-ctl user list\n```\n\nA password has at least 12 characters and is not one of the most common\npasswords; there are no other rules, so a long phrase is the easiest to\nremember. It is never shown, logged or stored: only a one-way check value is\nkept.\n\n## Groups\n\nA **group** holds accounts. A role given to a group is held by every member, so\na team is set up once:\n\n```bash\nsudo cenvero-str-ctl group add ops --comment \"On-call operators\"\nsudo cenvero-str-ctl group member add ops alice@local\nsudo cenvero-str-ctl acl add --path / --group ops --role Operator\n```\n\nDeleting a group removes its permissions; its members keep their accounts.\n\n## Roles\n\nA **role** is a named set of **privileges**. You give a role on a path; the\nprivileges then apply there.\n\n### The built-in roles\n\nThey never change. `cenvero-str-ctl role show <role>` lists a role's privileges.\n\n| Role | What it may do |\n|---|---|\n| **Administrator** | Everything, including who may do what and the cluster itself. Must use a second factor |\n| **Operator** | Everything except managing access and forming, joining or changing the cluster |\n| **Auditor** | See everything — servers, machines, images, storage, networks, tenants, accounts, the cluster — and read the audit log; change nothing |\n| **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 |\n| **VMUser** | See machines, start and stop them, open their consoles, use the guest agent |\n| **NetworkAdmin** | Create, change and delete networks; see and change a server's network settings |\n| **StorageAdmin** | Create, grow and delete volumes; restore and delete backups; add and delete images; snapshot and back up machines' volumes; see machines |\n| **TenantManager** | Create, change and delete tenants and their quotas; suspend, resume and limit them; revoke their keys; see their machines, networks, storage and images |\n| **Billing** | See tenants; suspend, resume and limit them |\n| **Support** | See machines, start and stop them, open their consoles, use the guest agent; see tenants and networks |\n| **NoAccess** | Nothing: given on a path, it takes away what a wider path gives there |\n\n### Custom roles\n\nMake your own for anything else. A custom role's name starts with a capital\nletter, and it can require a second factor of anyone who holds it:\n\n```bash\nsudo cenvero-str-ctl role add TenantSupport --privileges Tenant.Audit,VM.Audit,VM.PowerMgmt\nsudo cenvero-str-ctl role set TenantSupport --require-tfa\n```\n\nDeleting a custom role removes every permission that gives it.\n\n### Which role reaches a server's settings\n\nA server's own settings pages in the web console — **Interfaces**, **Routing**,\n**Firewall**, **Services**, **Traffic**, **Backups**, **Certificates**, **System\nlog** and **Updates** — and the API routes behind them follow the server's\nprivileges:\n\n| To | You need, on the server | Built-in roles that hold it |\n|---|---|---|\n| See its settings, its system log and its configuration export | `Sys.Audit` | Administrator, Operator, Auditor, NetworkAdmin |\n| Change them (firewall, load balancers, BGP, VRF, Geneve, NAT64, DNS forwarders, certificates, an alert's resolution) | `Sys.Modify` | Administrator, Operator, NetworkAdmin |\n| Check for, apply or roll back an update | `Sys.Update` | Administrator, Operator |\n| Start the cluster's rolling update | `Sys.Update` on **every** member | Administrator, Operator |\n\nNo role puts the server's own certificate on a web (layer-7) frontend, or changes\nthe pools such a frontend routes to: only root does, with `cenvero-str-ctl` on the\ncommand line. Over the API and in the web console such a frontend can only be\nremoved (see [Load Balancer](/docs/networking/load-balancer#over-the-api)).\n\nThe **Datacenter › Options** page — the brand and the notification settings —\nneeds `Cluster.Audit` on `/cluster` to see (Administrator, Operator, Auditor) and\n`Cluster.Modify` to change (Administrator only), with your password again. Every\nsigned-in person reads the tags' colours. An object's tags and notes follow that\nobject's own privileges: whoever may see a machine sees its tags, and changing\nthem needs the privilege that changes the object (`VM.Config.Options` for a\nmachine, `Network.Modify` for a network, `Storage.Allocate` for a volume,\n`Image.Allocate` for an image, `Tenant.Modify` for a tenant, `Sys.Modify` for a\nserver). A tag never grants or takes away access.\n\n### Every privilege\n\n`GET /api/v1/access/privileges` lists them with these descriptions.\n\n| Privilege | Allows |\n|---|---|\n| `Sys.Audit` | See a server's status, settings and history |\n| `Sys.Modify` | Change a server's network settings |\n| `Sys.Update` | Update a server's software (not used yet) |\n| `Sys.Console` | Open a shell on a server (not used yet) |\n| `VM.Audit` | See virtual machines |\n| `VM.PowerMgmt` | Start, stop and restart virtual machines |\n| `VM.Console` | Open a virtual machine's console |\n| `VM.Allocate` | Create, clone and delete virtual machines |\n| `VM.Config.CPU` | Change a virtual machine's processors |\n| `VM.Config.Memory` | Change a virtual machine's memory |\n| `VM.Config.Disk` | Change a virtual machine's disks and CD-ROM drives |\n| `VM.Config.Network` | Change a virtual machine's network cards |\n| `VM.Config.CloudInit` | Change a virtual machine's first-boot settings |\n| `VM.Config.Options` | Change a virtual machine's name, protection, boot order and start-at-boot setting |\n| `VM.GuestAgent` | Use a virtual machine's guest agent, such as resetting a password |\n| `VM.Snapshot` | Take, revert and delete snapshots |\n| `VM.Backup` | Back up virtual machine volumes and set their retention |\n| `VM.Migrate` | Move a virtual machine to another member, and move several at once; each machine is checked on its own |\n| `Image.Audit` | See base images, templates and installation discs |\n| `Image.Allocate` | Add and delete base images, catalogue images, templates and installation discs; share a template |\n| `Storage.Audit` | See volumes, snapshots, backups and backup schedules |\n| `Storage.Allocate` | Create, grow, attach and delete volumes |\n| `Storage.Backup` | Restore and delete backups; set, run and remove backup schedules |\n| `Network.Audit` | See networks and addresses |\n| `Network.Allocate` | Create and delete networks |\n| `Network.Modify` | Change networks and attach machines to them |\n| `Tenant.Audit` | See tenants |\n| `Tenant.Modify` | Create, change and delete tenants and their quotas |\n| `Tenant.Billing` | Suspend, resume and limit tenants |\n| `Tenant.Keys` | Manage tenants' keys |\n| `Access.Audit` | See accounts, groups, roles, permissions, tokens and sign-in methods |\n| `Access.Modify` | Manage accounts, groups, roles, permissions, tokens and sign-in methods |\n| `Access.Token` | Manage one's own API tokens |\n| `Cluster.Audit` | See the cluster |\n| `Cluster.Modify` | Form, join, leave and change the cluster, and put a member into maintenance or end it |\n| `Audit.Read` | Read the audit log |\n\nSome changes need more than one privilege. Attaching a volume to a machine also\nneeds `VM.Config.Disk` on the machine. Making a tenant key needs `Tenant.Keys`\nand also everything the key lets its holder do on that tenant (see it, its\nmachines and networks, start and stop the machines, open their consoles, use the\nguest agent), because whoever holds the key can do those things: an Operator or\nAdministrator on the tenant can, a TenantManager cannot.\n\n## Permissions\n\nA **permission** gives one role, on one path, to an account, a group or an API\ntoken.\n\n```bash\nsudo cenvero-str-ctl acl add --path /tenants/t-acme --user bob@local --role Support\ncenvero-str-ctl acl list --path /tenants/t-acme\nsudo cenvero-str-ctl acl remove <entry-id>\n```\n\n### Paths\n\n| Path | What it covers |\n|---|---|\n| `/` | Everything |\n| `/nodes/<node>` | One server: its status and settings, its networks, its storage and its images |\n| `/nodes/<node>/storage` | One server's volumes and images |\n| `/vms`, `/vms/<id>` | Every virtual machine, or one |\n| `/tenants`, `/tenants/<id>` | Every tenant, or one: the tenant, and its machines, networks and volumes |\n| `/networks/<node>/<id>` | One network, with its endpoints |\n| `/volumes/<id>` | One volume, with its snapshots and backups |\n| `/images/<node>/<id>` | One base image |\n| `/isos/<node>/<id>` | One installation disc in a server's disc library |\n| `/access`, `/access/users/<id>`, `/access/groups/<id>`, `/access/realms/<id>` | Accounts, groups and sign-in methods |\n| `/cluster`, `/cluster/members` | The cluster, and its members |\n| `/audit` | The audit log |\n\n`<node>` is a server's id, as `GET /api/v1/nodes` lists it. A permission may\nname something that does not exist yet: it applies once it does.\n\n### How a permission reaches an object\n\n- **Below its path.** A permission applies to its path and everything below it\n  — `/vms` covers every machine — unless it is made with `--no-propagate`\n  (`\"propagate\": false`), which keeps it to the path itself.\n- **From every path the object belongs to.** A machine is reached from its own\n  path and from its tenant's; a volume from its own, its tenant's and its\n  server's storage; a network from its own, its tenant's and its server's; an\n  image from its own and its server's storage. What reaches it from each is\n  added together. A permission on a server does **not** reach the machines on\n  it: give those on `/vms`, on their tenant, or on `/`.\n- **The most specific path decides.** Along one path, the deepest level that\n  holds a permission for you replaces what is above it. So Operator on `/` and\n  Auditor on `/vms/vm-1a2b3c4d` leave you an Auditor on that machine. Your own\n  permissions and your groups' at the same level are added together.\n- **NoAccess takes away.** NoAccess on a path leaves nothing there for you,\n  whatever else is given at that level. NoAccess on an object's own path always\n  wins, even over what its tenant gives.\n\n### Example: a support desk for one customer\n\n```bash\nsudo cenvero-str-ctl group add acme-support\nsudo cenvero-str-ctl group member add acme-support bob@local\nsudo cenvero-str-ctl acl add --path /tenants/t-acme --group acme-support --role Support\n```\n\nBob now sees tenant `t-acme`, its machines and its networks, can start, stop and\nrestart those machines, open their consoles and reset a guest password. He does\nnot see any other tenant, your own machines, or the servers' settings: in the\nconsole his tree holds only what he may see, and the API answers for anything\nelse as if it did not exist.\n\nTo keep him away from one of that customer's machines:\n\n```bash\nsudo cenvero-str-ctl acl add --path /vms/vm-1a2b3c4d --user bob@local --role NoAccess --no-propagate\n```\n\n### Who may grant what\n\n- Giving and removing permissions needs `Access.Modify` on the permission's path.\n- **Nobody can give a role with privileges they do not hold on that path.**\n  Removing a NoAccess also needs everything it would give back — for a\n  NoAccess on a machine, volume, network or image, including what its tenant\n  or its server would give.\n- A permission that reaches below its path needs what it gives on every path\n  below it: someone kept out of a path cannot grant a role above it that would\n  reach it, add someone to a group that would, or hand over an account that\n  holds it.\n- **Handing someone an account is giving them what it holds.** These need\n  every permission the account holds, where it holds it, as well as\n  `Access.Modify` on the account:\n  - setting another account's password, or resetting its second factor;\n  - making another account an API token that holds everything it holds\n    (`--no-privsep`);\n  - enabling an account again, or moving its expiry later or removing it;\n  - enabling a sign-in method again (for the accounts it brings back);\n  - for a sign-in method through your identity provider, mapping a group or\n    trusting the provider's second factor (see\n    [Signing in through your identity provider](#signing-in-through-your-identity-provider)).\n\n  An account that holds nothing can be managed with `Access.Modify` alone.\n\n```text\nyou cannot grant a role with privileges you do not hold on <path>\n```\n\n- Giving Administrator, or any role that can manage access, asks for your\n  password again, and so does a removal that gives that power back (see\n  [Confirming your password](#confirming-your-password)). Taking power away\n  never does.\n\n`cenvero-str-ctl role list`, `acl list` and, in the console,\n**Datacenter › Permissions** show who holds what; a machine's, a network's and\na tenant's **Permissions** tab shows and adds the permissions on that object.\n\n## What a refusal looks like\n\n- **Something you may not see** answers exactly as if it did not exist: the\n  same **404** and the same words as a wrong id. A list holds only what you may\n  see; it is never refused. So \"not found\" is the honest answer for an object\n  that exists but is not yours, and nobody learns what else runs on a server.\n- **Something you may see but not change** answers **403**, naming what is\n  missing and where:\n\n```json\n{\"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\"}\n```\n\nTo ask what you may do before you try, use `GET /api/v1/access/permissions`\n(see the [API Reference](/docs/api#access-control)). The web console asks it\nfor you: a button you may not use is shown disabled, saying which privilege it\nneeds.\n\n## Signing in with a password\n\nThe console's sign-in page offers your sign-in methods. For a Stratum account:\n\n1. Enter your **user name** and **password**. Any failure — a wrong password, an\n   unknown, disabled or expired account — gives the same answer:\n   `that user name and password were not accepted`.\n2. If the account has an authenticator app, enter the **6-digit code** it shows\n   (or **Use a recovery code instead**). You have five minutes and five tries.\n3. An account that must use a second factor but has none yet can only set one\n   up: the console shows **Set up a second factor**, and opens once it is done.\n\nAfter five failed attempts for a user name, it must wait a minute before the\nnext, doubling up to 15 minutes (`too many failed attempts; try again in a few\nminutes`). The wait is the same for names that exist and names that do not.\nFailed attempts also count towards the address's lock-out on the API.\nSign-in attempts are also limited per address; all addresses of one IPv6 /64\nnetwork count as one. Past the limit the sign-in page says\n`too many sign-in attempts; wait a minute and try again`.\n\n### A second factor\n\nAny authenticator app works: on a phone, or in a password manager. It shows a\nnew 6-digit code every 30 seconds. Set it up under\n**Your account › Second factor** (or at your first sign-in when you must have\none): scan the code the console shows, or type the key shown under it, then\nenter the code the app shows. Each code works once. On a cluster, a code is refused on\nevery member once every member runs this release; until then it works once on each\nmember.\n\nAn account must use a second factor when **Must use a second factor** is set on\nit (`user set <id> --require-tfa`), or when any role it holds, directly or\nthrough a group, requires one. Administrator always does; custom roles can.\n`user tfa show <id>` and **Datacenter › Permissions › Second factors** show who\nhas one and who must set one up.\n\n### Recovery codes\n\nWhen you set up the authenticator you get **ten recovery codes**, shown once:\nprint them or store them somewhere safe, away from the device that holds the\nauthenticator. Each lets you sign in **once** without the app.\n**Your account › Second factor › New recovery codes** replaces them all; the old\nones stop working.\n\n### If a second factor is lost\n\n- **You still have a recovery code:** sign in with it, then under\n  **Your account › Second factor** choose **Replace the authenticator**. Make\n  new recovery codes if few are left.\n- **You have none left:** ask an administrator — someone who holds at least\n  what your account holds — to reset it:\n  **Datacenter › Permissions › Second factors › Reset**, or\n  `sudo cenvero-str-ctl user tfa reset <id>`. Your authenticator and recovery\n  codes stop working; if your account must have a second factor, you set up a\n  new one at your next sign-in.\n- **The only administrator lost theirs:** root on any server can reset it, and\n  set a new password, from the command line:\n\n```bash\nsudo cenvero-str-ctl user tfa reset alice@local\nprintf '%s\\n' \"$NEW_PASSWORD\" | sudo cenvero-str-ctl user passwd alice@local --password-stdin\n```\n\nA forgotten password is set again the same way, by an administrator (the\n**Password** button on the account) or by root.\n\n### Sessions\n\nA session ends after **30 minutes** without activity, after **12 hours** in all,\nwhen you sign out, and when the agent restarts. One account holds at most\n**eight** sessions at once; signing in a ninth time closes its least recently\nused one, so nobody can sign others out by signing in repeatedly. An API\ntoken's sessions count with its account's eight. Each server records the last\nsign-in it saw.\n\nChanging or resetting a password signs the account out everywhere at once:\nevery session that signed in before the change ends, on every server, and the\nsession you changed your own password in carries on. Setting up a new\nauthenticator app, removing the second factor, or deleting an account and\nmaking it again under the same name does the same.\n\n### Console tickets\n\nThe web console and the customer portal open a machine's console with a\nsingle-use ticket (see [Consoles](/docs/compute/consoles)). Each tenant, each account and each\noperator API key can hold at most **16** unused console tickets on a server at\na time; beyond that the request is refused with\n`too many console tickets are outstanding; use or let some expire first`. A\nticket is used up when opened and expires after **60 seconds**. Some capacity\nis always kept for the node's own API token and for root.\n\n## Confirming your password\n\nA change that gives someone more power, or weakens a sign-in, asks for your\npassword again — and your authenticator's code, if you have one. A confirmation\nlasts **five minutes**. Signing in with your password or your authenticator's\ncode counts as one; signing in through your identity provider alone counts only\nwhen it asked for its trusted second factor during that sign-in.\n\nIt is asked for when you:\n\n- change any password;\n- set up, replace, remove or reset a second factor, or make new recovery codes;\n- give Administrator, or a role that can manage access (`Access.Modify`);\n- add someone to a group that holds such a role;\n- create or change a custom role so that it can manage access, or delete one\n  that can;\n- make an API token that holds everything its account holds (`--no-privsep`);\n- add, change or delete a sign-in method;\n- change the brand (its settings, logo or favicon) or the notification settings,\n  which hold the mail server's password;\n- delete any account, or disable one that holds Administrator;\n- remove a permission (a NoAccess, say), a group member, a group or a role when\n  that gives someone back the power to manage access;\n- enable an account again, or remove or extend its expiry, when it holds\n  Administrator or `Access.Modify`;\n- stop requiring a second factor for an account or a role.\n\nThe web console shows **Confirm it is you** when a change needs it, and carries\non once you have. If you signed in through your identity provider, the console\nsends you there to sign in again.\n\nThese changes can be made by a person in the web console who has confirmed, by\nroot on the server's command line, and with the node's own API token on its own\nserver. **An API token or an operator key never can:**\n\n```text\nan API token cannot make this change; sign in to the web console to make it\n```\n\nOver the API, an unconfirmed session answers **403**\n`confirm your password to make this change`, with `\"reauth_required\": true`.\n\n## API tokens\n\nAn **API token** lets a script or an integration use the API as an account. Its\nid is `<account>!<name>`, and its secret — `cst_` followed by 64 characters — is\nshown **once**, when it is made:\n\n```bash\nsudo cenvero-str-ctl token add alice@local ci --comment \"deploy pipeline\" --expires 2027-01-01\nsudo cenvero-str-ctl acl add --path /vms --token 'alice@local!ci' --role VMUser\n```\n\n```\nAuthorization: Bearer cst_…\n```\n\nQuote a token id in your shell: an unquoted `!` can be taken as a history\nexpansion.\n\n### A token's own permissions\n\nBy default a token holds **only the permissions given to the token itself**,\nand never more than its account holds: the token above can see, start and stop\nmachines and open their consoles — and only where Alice can too. Give a token\njust what its job needs. A token made with `--no-privsep` (`\"privsep\": false`)\ninstead holds everything its account holds; making one asks for your password.\n\n- **A token never does more than its account.** It stops working the moment it\n  is revoked, its expiry passes, or its account is disabled, expires or is\n  deleted, or its account's sign-in method is disabled.\n- **A token can never give another token more than it holds itself**, and can\n  never make a change that needs a confirmed password.\n- **A token never makes a token that outlives it.** A token made by another\n  token expires no later than the token that made it: a later expiry, or none,\n  is cut to that token's own.\n- Managing your own tokens needs `Access.Token` on your account\n  (`/access/users/<you>`): Administrator and Operator have it; give it to\n  others with a custom role. Anyone else's tokens need `Access.Modify`.\n- Each server records the last use of a token it saw.\n\n### Operator API keys\n\nOperator API keys (`cenvero-str-ctl apikeys mint`) are tokens of the built-in\naccount `apikeys@local`, which nobody signs in as. Each holds Administrator on\n`/`, exactly as before. `token list` shows them, marked as operator keys, with\nthe id `apikeys@local!<key id>`, and `apikeys mint`, `list` and `revoke` keep\nworking as they always have. Operator keys belong to no sign-in method, so\ndisabling one never stops them. For that reason only `apikeys mint`, run as\nroot on a server, makes them: no person and no API token can make a token of\n`apikeys@local` — make a token of your own account instead.\n\nTo narrow one — say the key your billing system uses — replace its permission:\n\n```bash\ncenvero-str-ctl acl list --token 'apikeys@local!<key id>'   # note its Administrator entry on /\nsudo cenvero-str-ctl acl add --path /tenants --token 'apikeys@local!<key id>' --role Billing\nsudo cenvero-str-ctl acl remove <that entry's id>\n```\n\nA key you narrowed stays narrowed: it is never widened again on its own.\n\nSee [Billing Integration](/docs/billing-integration) for a billing key made from\nscratch.\n\n## Signing in through your identity provider\n\nPeople can sign in with your organisation's identity provider (any that speaks\n**OpenID Connect**) instead of a Stratum password. Each provider is a sign-in\nmethod of its own, and the sign-in page offers **Sign in with <its name>**.\n\n### What the provider needs\n\n- **The authorization code flow with PKCE (S256).** Register Stratum as a client\n  (with a client secret, or as a public client) and note its client id.\n- **Each server's sign-in address**, registered with the provider as a redirect\n  address — one per server, at the address people open its console on:\n\n```\nhttps://<server address>:7070/console/auth/oidc/callback\n```\n\n- **An `https` issuer address** each server can reach, which publishes the\n  provider's settings and signing keys at their standard addresses.\n- Signatures the realm accepts: RS256, ES256 and EdDSA by default, PS256 on\n  request. Others are never accepted.\n\n### Setting it up\n\nIn the web console:\n**Datacenter › Permissions › Sign-in methods › Add identity provider**. From\nthe command line, with the client secret read from standard input:\n\n```bash\nprintf '%s\\n' \"$CLIENT_SECRET\" | sudo cenvero-str-ctl realm add-oidc corp --display-name \"Corporate sign-in\" \\\n  --issuer https://id.example.net/realms/corp --client-id stratum --client-secret-stdin \\\n  --redirect-uri https://node1.example.net:7070/console/auth/oidc/callback \\\n  --redirect-uri https://node2.example.net:7070/console/auth/oidc/callback \\\n  --groups-claim groups --group-map stratum-ops=ops\nsudo cenvero-str-ctl realm test corp\n```\n\n`realm test` (**Check** in the console) fetches the provider's settings and\nsigning keys and says what it found, without signing anyone in. The client\nsecret is never shown again; `realm set` keeps it unless you give a new one.\nAdding, changing or deleting a sign-in method asks for your password.\n\n### Who an account is\n\n- **The first sign-in names the account**, from the claim you choose:\n  `preferred_username` (the default), `email` — only when the provider says the\n  address is verified — or `sub`. `alice` signing in with `corp` is\n  `alice@corp`.\n- **From then on the account stays with that person** at that provider, whatever\n  the provider later calls them. An account linked to one person is never given\n  to another: `this account is linked to another sign-in at <name>`.\n- **Accounts made at first sign-in have no permissions until you grant them.**\n  To prepare one, make it first (`user add alice@corp`) and give it its roles;\n  the first sign-in links it. `--no-autocreate` lets only accounts you made sign\n  in.\n- **The display name and a verified email** follow the provider at each\n  sign-in. Passwords are changed at the provider, never here.\n\n### Groups from the provider\n\nWith `--groups-claim` and `--group-map provider-group=stratum-group`, each\nsign-in puts the account in exactly the mapped groups the provider lists for the\nperson, and takes it out of mapped groups it no longer lists. Only the groups in\nthe map are touched; groups you manage by hand stay as they are. A provider can\nnever take the last administrator out of a group: that sign-in is refused\ninstead.\n\nBecause the provider decides who is in a mapped group, mapping a group — or\npointing the sign-in method at another provider, another client or another\ngroups claim — needs every permission the group holds, and everything that\ntaking the method's accounts out of it would give back (a group that holds a\nNoAccess, for example).\n\n### Second factor\n\nStratum's rule applies to these accounts too: an account that has an\nauthenticator is asked for its code after the provider, and one whose roles\nrequire a second factor must set one up. If your provider already asks people\nfor a second factor, `--trust-provider-mfa` lets Stratum count it, when the\nprovider says it asked. Whoever runs your provider can then sign in as any of\nthe method's accounts without a Stratum code, so turning it on needs every\npermission held by the method's accounts that have, or must have, a second\nfactor.\n\n### Link people to the console, not to the sign-in address\n\n**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`).**\n\nFor your people's safety a sign-in only starts from the console's own page, or\nfrom an address typed or bookmarked in the browser; one started by a link on\nanother site is refused. The console then shows **Sign in with <name>**, and the\nsign-in works.\n\nOpen the console at an address you registered: a server opened at an address its\nsign-in method does not list answers\n`this address is not registered for sign-in with <name>`.\n\n### When it is refused\n\n| The sign-in page says | What to do |\n|---|---|\n| `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) |\n| `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 |\n| `your account at <name> has no verified email address` | The sign-in method names accounts by email: verify the address at the provider |\n| `sign-in with <name> took too long; try again` | Start again: a sign-in at the provider must finish within ten minutes |\n| `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 |\n\nA sign-in method can only be deleted once it holds no accounts.\n\n## Taking access away\n\nDisabling or deleting an account, letting it expire, disabling its sign-in\nmethod, or revoking a token takes effect **at once**: every session it opened\nends, and every machine console it opened closes. Taking a role away also closes\nthe consoles that role allowed. In a cluster this reaches every member within a\nfew seconds.\n\n```bash\nsudo cenvero-str-ctl user set bob@local --enabled=false\nsudo cenvero-str-ctl token revoke 'alice@local!ci'\n```\n\nRevoking never asks for your password: taking power away should always be easy.\n\n## In a cluster\n\n- **Accounts, groups, roles, permissions, sign-in methods, API tokens and\n  operator keys belong to the whole cluster.** Make them on any member; they\n  work on every member. Each member checks every account and token itself, so a\n  key or token works when you call any member directly, and a revoked one stops\n  on all of them.\n- **New accounts.** An account created on one server — for\n  example by a person's first sign-in through your identity provider — is\n  recognised by every server of the cluster at once: when a request passed on\n  from another server reaches one that has not yet received the change, that\n  server waits up to a second for it instead of refusing the request.\n- **Paths name each member's objects**: `/nodes/<node>` is one member; a\n  machine, network or volume is reached the same way wherever it runs.\n- **The node's own API token** belongs to its server. Signed in with it, you can\n  act on every member, because that server vouches for you; prefer personal\n  accounts for everyday work.\n- **Root on any member can administer the whole cluster**, including who may do\n  what. Protect every member as you would the most sensitive one.\n- Each server records the last sign-ins and token uses it saw.\n\n### A server cut off from the others\n\nA server that cannot reach the rest of the cluster keeps the access rules it\nlast knew until it can. People can still sign in there, and what they may do is\nwhat that server last knew. Changes to accounts and permissions wait:\n\n```text\nthe cluster has no leader reachable from this node; changes to shared settings are paused until it has one\n```\n\nA first sign-in through your identity provider, or one that would change the\naccount's groups, waits too. A recovery code cannot be used there either, so\nthat it can never be used twice:\n\n```text\na recovery code cannot be used while this server is cut off from the others; use your authenticator app, or try again later\n```\n\nOutside a cut-off, a recovery code is refused with `that code was not accepted` when it\nis not written as a recovery code, when it is not one of the account's unused codes (a\ncode is used up by its first use, and new codes replace all the old ones), when the\naccount is disabled or past its expiry, or when the sign-in method it uses is switched\noff.\n\nThe web console says so in a banner, with since when. Changes made elsewhere in\nthe meantime — a revoked token, a disabled account — reach it within a few\nseconds of the network coming back. Sign in to a member that can reach the\nothers to make changes.\n\nWhile a server cannot reach the rest of its cluster, or has not yet caught up\nwith it, every audit record it writes includes `\"identity_stale\": \"true\"` in its\n`detail`, so you can tell which actions were checked against access settings\nthat may be out of date.\n\n### A server catching up\n\nWhile a server is restarting or joining a cluster and has not yet caught up with\nthe cluster's access settings, it refuses requests passed on to it with an\noperator API key instead of trusting them; retry once it is back in step,\nnormally within seconds.\n\n### Joining a node that has accounts\n\nA node with accounts of its own can join a cluster once every member runs this\nrelease; its accounts, tokens and permissions join the cluster's. If one of its\naccounts has the same id as one of the cluster's but differs, the join is\nrefused with `this node's accounts conflict with the cluster's`, listing each\nconflict: change one of them, or join with discard-local-identity, so that the\njoining node drops its own accounts and takes the cluster's.\n\nWhen a server joins a cluster, an API token it once revoked — itself, or by\ndeleting its account — whose name matches a token that still exists in the\ncluster is reported as a conflict, and the join\nis refused until you resolve it: revoke the token in the cluster, or join with\ndiscard-local-identity. An operator key the server revoked is revoked in the\ncluster too: it is the same key.\n\nWhile some member\nstill runs an earlier release, a node with accounts is refused\n(`every node of this cluster must run version <v> before a node with accounts can join; …`),\nand once access control is on, a node on an earlier release is refused with\n`update this node to version <v> before it joins`.\n\n## Commands and API\n\n| Task | Command line | API |\n|---|---|---|\n| Accounts | `user add`, `list`, `show`, `set`, `passwd`, `delete` | `/api/v1/access/users` |\n| Second factors | `user tfa show`, `user tfa reset` | `/api/v1/access/users/{id}/tfa` |\n| Groups | `group add`, `list`, `show`, `delete`, `member add`, `member remove` | `/api/v1/access/groups` |\n| Roles | `role list`, `show`, `add`, `set`, `delete` | `/api/v1/access/roles` |\n| Permissions | `acl list`, `add`, `remove` | `/api/v1/access/acl` |\n| API tokens | `token add`, `list`, `revoke` | `/api/v1/access/users/{id}/tokens`, `/api/v1/access/tokens` |\n| Sign-in methods | `realm list`, `show`, `add-oidc`, `set`, `delete`, `test` | `/api/v1/access/realms` |\n| What you may do | — | `/api/v1/access/me`, `/api/v1/access/permissions` |\n\nRoot on the command line acts as an Administrator and never needs to confirm a\npassword. Every command answers with the API's own sentences, and `--json`\nprints the API's answer. See the [CLI Reference](/docs/cli#access-control) and\nthe [API Reference](/docs/api#access-control).\n\n## See also\n\n- [The Web Console](/docs/compute/web-console) — signing in, your account and the\n  Permissions pages.\n- [Security](/docs/security) — what is protected, and your checklist.\n- [Tenants & Bandwidth](/docs/tenants) — tenant keys and the customer portal.\n- [Clustering Overview](/docs/clustering/overview) — what a cluster shares.\n"
        }
    ]
}