Users in the sidebar (admin only). Three sections: Users, Roles and Group Mappings, plus an Authentication button in the page header that opens the sign-in configuration (tabs SAML, OIDC, LDAP, App Proxy and Settings).

Every route declares a function key plus a required level. A role is a matrix over the 35 keys:

none  <  read  <  write  <  fullwrite

Most keys do not offer all four. See Short ladders below: a rung only exists where it grants something the rung beneath it does not.

A user has one role. A bearer token is bound to one role at mint time and passes the same gates a session does.

Five keys carry an ownership dimension: subnets, reservations, contacts, credentials, networkScan.

A row with no creator is unowned and therefore fullwrite-only. Discovered networks have no creator, which is why archiving one is fullwrite — retiring a site's address space is not an own-rows action.

A key declares only the levels it can actually hold, and most hold fewer than four. The rule is that a rung has to grant something the rung below it does not — otherwise it is a radio button that changes nothing, and picking it is a decision the operator did not really make.

The UI renders a dash instead of a radio for an unsupported cell. Stored values clamp down, never up — a fullwrite on a read-only key means "as much as possible", so rounding up would silently grant and resolving to none would silently revoke.

Top rung names the highest level the key offers. Where that is Full Read-Write, the last column says what it buys over Read-Write — because that is the only thing that justifies the rung existing.

The manufacturer alias map sits on manufacturerProfiles, not a key of its own. An alias rewrites the manufacturer on every matching asset, and that is what picks the device's profile — so editing aliases is editing which profile applies. See Rule 43.

serverSettingsData has no Read rung because downloading a backup is not a read — the archive is the entire database. A Read rung would make "may look at the Data tab" and "may walk off with the database" the same grant. Every other read on that tab rides the System key's floor.

authentication is its own key, separate from serverSettingsSystem, and it is worth knowing why if you maintain custom roles.

Identity-provider configuration repoints every login in the install at an identity provider of your choosing. That is not a lesser grant than changing the logo, and an admin delegating "some server settings" is almost never delegating the install's login path. Keeping the two apart lets you hand out TLS, HA, tags, DNS, NTP, branding, capacity and the agent fleet (serverSettingsSystem, which tops out at Read-Write like most keys) without handing out the login path. A role can see the sign-in configuration with authentication Read-Only; repointing it takes authentication Read-Write, which is a decision rather than a side effect.

Two neighbours deliberately sit elsewhere. IdP group mappings remain on users Full Read-Write: a mapping decides which role an IdP group receives, which is granting authority rather than configuring authentication, and it is already the documented path to admin outside the last-admin guard. And the login-page source-IP restriction remains on serverSettingsSystem: it governs who can reach a page over the network, not how Polaris decides who you are.

readonly is the floor. No built-in role reaches less of Polaris than the look-only role does — a role that exists to do more than look should never see less. There is exactly one deliberate exception: user holds networkScan: none where readonly holds read, because that role exists for address-space self-service and an active sweep is IDS-visible.

Create custom roles with + Add Role in the Roles section. A role bound to any API token refuses deletion.

Nothing may leave Polaris with zero users holding users:fullwrite and roles:fullwrite. Enforced on role change and on user delete.

Nobody hands out authority they do not hold (rule 48, rule 114).

Every place a grant is made — creating or editing a role, creating an account on a role, moving an account to a role, binding an API token to a role — is refused 403 if it would grant any permission above your own level, unless you are admin-equivalent. Editing a role is refused only for the permissions the edit raises, so you can still rename or adjust a role that holds something you do not. Beyond that, the admin-equivalent pair is guarded at these places:

A caller whose own permissions are not admin-equivalent is refused 403 at the four places the grant could be minted:

• POST /roles and PUT /roles/:id — writing the two fullwrite grants onto a new role, or onto the role you already hold
• POST /users — creating an account on an admin-equivalent role with a password you choose
• PUT /users/:id/role — promoting an existing account into it

The same bar applies to acting on an account that is already admin-equivalent. Resetting its password, removing its two-factor method or its passkeys, deleting it, or moving it to another role is refused 403 unless you are admin-equivalent too, because each of those is a way to become that administrator. Accounts on any lesser role stay within Users Read-Write, so a help-desk role can still reset their passwords.

Without it, both users:write and roles:write would be a one-step path to full control of the install, and the shortest one needs no existing account at all.

It is not four-eyes. A caller who already holds admin-equivalence is unaffected, and the check is skipped entirely when the target permission set is not admin-equivalent — so every ordinary role edit is untouched.

It is the mirror of the last-admin guard, and neither replaces the other: that one refuses to demote the last admin, this one refuses to promote into the tier. A "you cannot change your own role" check is not an escalation guard — the escalation runs through somebody else's row.

A request with no role snapshot resolved counts as not admin. It fails closed.

Read-Write on Server Settings → System, Server Settings → Data, Automation Scripts, Automations and Maintenance reaches more than it did before the September 2026 permission update. Custom roles that held Read-Write on any of them carry a Review grants badge in the Roles list, and the capacity card names them. Nothing was taken away. Check that the access is intended, then save the role or choose Mark reviewed from its menu (rule 114).

Role, User and GroupMapping each carry two operator-typed tag dimensions: region tags and other tags. Empty means unrestricted.

A session's effective scope is the union of role, user and group-derived tags, per dimension. Group-derived tags are re-resolved live on every /auth/me, never persisted onto the user's own columns — so operator-set tags survive a re-login.

Assign Tags edits both dimensions through one picker. A map region already is a registry tag (region:<name> in a locked category), so a separate region control listed the same names twice in the same dialog. The prefix carries the split instead.

Two behaviours that exist because the columns hold bare names with no foreign key:

• A region rename carries these columns with it. A rename that left them behind would revoke every scoped operator's region in silence — the tag still present, matching no region, and every name-resolving consumer quietly reaching nobody.
• A region delete never strips them. There is no new name to move an assignment to, so the assignment survives and a warning Event names who now holds a dangling one.

That second case is why rule 58 exists: an orphaned region tag makes an automation's level-scoped routing abstain entirely rather than promote the container region — because dropping the leaf would page the division while the site's own people hear nothing.

Region scope never narrows an administrator's alerts. An admin-equivalent role (Full Read-Write on both users and roles) sees and can acknowledge every alert, whatever region tags its user, role or SSO group carry. An admin in a regional IdP group picks up that group's tags without anyone meaning to narrow them, and the Active Alerts widget and the device's Alerts tab are not region-scoped — so a scoped admin would see an alert there and then be told it was "not here any more" by its acknowledge card. Every other role is narrowed by its regions on the Alerts list and the acknowledge page.

The Users list draws both dimensions under the username — regions in their map colour, then tags in their registry colour.

Users → Authentication. Five providers; every one must keep working.

Never fix a login-adjacent bug for the provider you happen to run. The five have different transport semantics, and the SAML/OIDC difference above is the one that bites.

PostgreSQL-backed, 8-hour max age, HttpOnly, SameSite=Lax.

Secure is not unconditional — it is set only when the request is HTTPS, including behind a proxy but only when TRUST_PROXY is set so X-Forwarded-Proto is believed. A plain-HTTP lab install is a supported shape, so nothing may hard-require a Secure cookie.

(rule 108)

• Wrong second-factor codes keep counting. Typing the password again does not reset the account's failure count, so five wrong codes lock the account whatever is typed in between. A completed sign-in resets it.
• A TOTP code works once. The 30-second step it belongs to is recorded, and a second use within its window is refused, as RFC 6238 requires.
• Account changes sign the user out. Deleting a user, changing their role, or resetting their password, two-factor method or passkeys ends every session they hold; changing your own does not end the one you are using. A session is also checked against its account about once a minute, so a deleted or re-roled account does not keep its old access until the cookie expires.
• Registering a passkey asks for your current password, because a passkey is a way in that skips the password. A wrong password counts toward the same lockout as a wrong password at sign-in.
• Your own password, two-factor and passkey routes need a signed-in session. An API token cannot use them.
• Azure SAML ties a response to its request when it names one, and refuses a sign-in response that has already been used. Sign-in started from the Azure My Apps portal is still accepted.

For installs published through Entra Application Proxy with pre-authentication. App Proxy authenticates in the cloud and forwards claims as plain HTTP headers.

The headers are unsigned. The entire security model is source-IP trust. Polaris honours them only from operator-allowlisted connector IPs — an empty allowlist means header login is disabled, failing closed — and a middleware strips those headers from every untrusted request as defence in depth.

The Test button reports the request's source IP as Polaris sees it, which is the value to put in the allowlist.

Note: Entra silently omits the groups header past roughly 150 groups unless the App Proxy app uses "groups assigned to the application".

Users → Group Mappings, gated users:fullwrite.

IdP group → role + tags. Highest-privilege role wins; tags from all matched groups union. No match keeps an existing user's role; a new user gets readonly and a review flag.

Security caveat, and Polaris says so with a warning Event when you create one: a mapping to an admin-equivalent role makes IdP group membership a path to Polaris admin, outside the last-admin guard.

Azure AD emits group object IDs in the groups claim, so map those GUIDs unless the IdP is configured to emit names.

Off by default (rule 31). It gates both halves or neither — the page and the login API — because the form is a plain POST to a JSON API.

The GET returns callerIp as Polaris resolves it, precisely because this is only as true as that value.

The restriction holds however the path is typed: /API/V1/AUTH/LOGIN/ is the same route and is gated the same way.

Users → Authentication → Settings (rule 63).

Minimum length (clamped to 8–128, NIST SP 800-63B's floor) and four character-class toggles. Turning every class off is a legitimate posture, not a misconfiguration.

The service fails to the defaults, never to "no policy" — the opposite of the login-restriction fail-open, because there failing safe means letting people in and here it means keeping the bar up.

Force change on login is answered against the plaintext, at the one moment Polaris can judge an existing password: the login where its owner types it.

And the demand is made on the far side of the second factor. A password-change token minted at the password step would let someone holding a stolen password set a new one — and collect the withheld session — without ever facing TOTP or a passkey. That is an MFA bypass wearing a policy's clothes. The token that is finally issued buys exactly one thing, is single-use, and is consumed only after the write lands.

Local accounts only, enforced at the route and re-checked at verification: an SSO account's credentials belong to its identity provider, and a Polaris-owned second way in would be invisible to whoever thinks they control it centrally.

Modes: off / login / second-factor / both (default — enabling passkeys refuses nothing).

requireUserVerification (default on) is what licenses a passkey to be the whole login: UV is two factors in one gesture.

The relying party is derived from the request, not configured — TLS terminates anywhere, POLARIS_PUBLIC_URL may be unset, and one install is legitimately reached by several names. That is safe only because the browser refuses any ceremony whose relying-party id is not a registrable suffix of the page's own origin, so a forged Host can make a ceremony fail and nothing else. The id and origin are then pinned into the ceremony at issue time and replayed at verify.

Two shapes cannot host passkeys at all, and both return a reason rather than an opaque browser error: plain HTTP off localhost, and an IP-address install. Two more are misconfigured proxies wearing those refusals — see Troubleshooting.

The passwordless options endpoint names no credentials, so it cannot answer "does alice exist, and how many keys has she?" — which is why registration demands a resident key. Every refusal returns the same message. And unlike every other credential path in Polaris, it never provisions: a credential resolving to no account is an authentication failure, not a signup.

Server Settings → API Tokens, gated apiTokens.

Each token is bound to a role at mint time and passes the same requirePermission gates a session does — so it reaches exactly what its role grants, filter-don't-403 surfaces included.

• The value (polaris_ plus a 32-character tail) is shown once, at creation; afterwards the list shows only its prefix, with the role, scoped integrations, trusted hosts, creator, last used time and expiry. An expiry is optional — blank means never. Revoke stops a token immediately; an expired or revoked token gets the same 401 as no token.
• A token granting quarantine at write or above must name the integrations it is scoped to.
• Binding a token to an admin-equivalent role needs you to be admin-equivalent yourself: API Tokens Read-Write alone is refused 403. When an administrator does it, a warning Event is logged.
• Trusted hosts (optional) limit the source addresses a token is accepted from. Set them at creation or change them later with Edit Hosts on the token's row; the token value stays the same and the change applies to the next request. Clearing a restricted token's list logs a warning Event. Entries are one IP address or CIDR per line, IPv4 or IPv6. Blank means any source. A valid token from any other address is refused with a 403 naming the address Polaris saw, and an api_token.untrusted_host warning Event is written — at most once per token and address every 15 minutes. The address is the one Polaris resolves through TRUST_PROXY, so behind a reverse proxy that does not forward the client address every caller looks like the proxy.
• CSRF is skipped for bearer requests — cross-site attackers cannot attach custom headers — while authentication is fully enforced downstream.
• Writes are attributed in the audit log as api:<token name>.