Identity & access (admin)
The operator identity surface — admin roles and the granular privilege catalog (RBAC), MFA, impersonation and the tenant simulator, the product-user directory, and keyless SSH access with ephemeral keys and audited sessions.
Identity & access (admin)
This page consolidates the four operator surfaces that govern who can operate the control plane, who can use the product, and how anyone gets onto a box — the Identity, Users, Access, and Account → Security pages under god mode. For the shared RBAC and session model that gates every one of these pages, read the god-mode overview first; this page documents what each surface actually shows and does.
Identity — admin hierarchy, privileges, impersonation
The Identity page (/identity) is the governance centerpiece. It requires the
admin.manage_admins privilege — which is super-admin only and never grantable to
a sub-admin — so only a super-admin (or the seeded root) sees it. Without it the page
renders a locked state.
Administrators
A KPI row summarizes the operator team: Admins, Super-admins, MFA enabled
(shown as on/total, and accented when any admin lacks MFA), and Privileges (the
size of the whole permission catalog). Below it, the Administrators table lists each
operator with their role, permission count, MFA state, and last-active time.
| Role badge | Meaning |
|---|---|
| Root super-admin | The seeded root operator (root: true) — holds every privilege and is re-derived every request, so it can't be edited away |
| Super admin | Full catalog (adminRole === 'super_admin') |
| Admin | A sub-admin — holds only its granted subset |
The permission count reads all for a root or super-admin, and the exact number of
granted privileges for a sub-admin.
In the demo backend the table shows the single seeded root operator; in production it reads real admins from Postgres.
Adding an admin
The Add admin button (super-admins only — it needs admin.manage_admins) opens an invite
drawer: enter the new admin's email and name, optionally pick a custom role to bundle
their privileges, and create. HostSSH mints a strong one-time temporary password, shown once
for you to hand off — it is never stored in plaintext (only its bcrypt hash persists) and can't be
shown again. The new admin signs in with it and enrolls MFA on first login. Without a role they start
with no privileges until you grant them (via a role or direct grants). Requires a configured
database — sub-admins are real persisted accounts, not demo data.
Privilege catalog (RBAC)
The Privilege catalog section renders every permission in lib/rbac.ts as a grid.
Each entry shows its machine key (e.g. fleet.view), a human label, and whether it is
grantable to a sub-admin or super-admin only. Two privileges are super-admin
only and can never be granted to a sub-admin, even explicitly:
| Super-admin-only privilege | Guards |
|---|---|
admin.manage_admins | The Identity page itself — managing admins and privileges |
hardware.manage | The Hardware page — host-level infra |
The catalog is fail-closed: a super-admin implicitly holds everything, and a sub-admin holds only what's in its granted set. A short list of privileges — the ones that act as another identity or bypass billing — are worth calling out:
| Privilege | What it unlocks |
|---|---|
admin.impersonate | Full act-as sessions (below) |
admin.simulate | Tier / tenant preview (the simulator, below) |
admin.billing_bypass | Bypass all license/paywall gating (god billing) |
Impersonation and the simulator
The Impersonation section reproduces a tenant's experience inside their account so you can debug what they see. The panel lets you pick a tenant, choose a mode and a duration, and start a time-boxed, audited session:
| Control | Options | Notes |
|---|---|---|
| Mode | Read-only · Read-write | Read-only observes with no writes; read-write is a full act-as session |
| Duration | 15 / 30 / 60 min | The session auto-expires; every action is logged on-behalf-of |
Starting a session sets the impersonation cookie (hs_imp), writes an
impersonation.start audit entry, and raises a red banner across the chrome. You
exit from that banner (which fires impersonation.stop). There is a hard
server-authoritative ceiling on any act-as session regardless of the chosen duration
— see the Settings page for where that ceiling is set.
Alongside the panel, Available tenants lists every org you can step into, with its tier and status. In the demo backend these are the seeded tenants; onboarding real customers populates the list.
The simulator is the lighter sibling of impersonation. It rides its own cookie
(hs_sim) and requires admin.simulate. Instead of acting as a specific person, it
previews a tier or a tenant — useful for checking how a plan gate or a tenant's
surface renders without touching their account. It's surfaced as a pill in the top
chrome, is time-boxed, and writes a simulation.set audit entry when changed.
Users — the product-user directory
The Users page (/users) is the directory of product accounts (customers), not
operators. It requires the users.manage privilege. A badge by the title reads
persisted (real DB) or demo (seeded, in-memory), so you always know whether
the rows are live customers or the seed set.
A KPI row counts Total, Active, Pending (accented when any are awaiting approval), and Suspended users. The table below lets you change roles, suspend, and remove accounts. The store never returns password hashes to these views — only the sign-in path reads them.
User status flows from the Access Requests queue: an approved early-access application activates (or creates) the corresponding user here.
Access — keyless SSH, keys, sessions, and exposures
The Access page (/access) is the operator's view of keyless-by-default SSH,
issued keys, audited sessions, and public app exposures. It is gated on two privileges
and shows only the sections you're entitled to:
| Privilege | Section |
|---|---|
access.ssh | Sessions table, key list, and the "open Web-SSH" action |
access.expose | Public exposures panel |
access.keys | Required to issue or revoke keys (checked in the actions) |
If you hold neither access.ssh nor access.expose, the page is locked.
Sessions and keys
When access.ssh is granted, a KPI row shows Live sessions (accented when any are
active), Sessions logged, Keys on file, and Ephemeral (auto-expiring) keys.
The Active & recent sessions table lists every brokered shell with the user, source IP, server, the channel it came in on (web-ssh, cli, or bastion), start and end times, and whether it was recorded. A live session is highlighted with a pulsing "live" badge. The seeded session list is demo data; in DB mode this reflects real brokered sessions.
The SSH keys table lists issued keys. Keys are real ed25519 keypairs: issuing
one generates an OpenSSH public line, an OpenSSH-format private key returned to you
once and never stored, and a SHA256 fingerprint. Ephemeral keys carry a TTL and
self-destruct on expiry; standing keys are the exception. Revoking a key drops it from
the list immediately. Every issue and revoke writes an audit entry (sshkey.issue /
sshkey.revoke).
Opening a Web-SSH session mints a short-lived HMAC token the relay verifies before bridging your browser to the agent's PTY — this depends on the Web-SSH relay being configured (see the System Check page).
Public exposures
When access.expose is granted, the Public exposures panel publishes a Node-local
port to the internet at <name>.apps.hostssh.com through a Cloudflare tunnel. The
control plane records the intent (pending), enqueues an expose job the agent polls,
and the agent reports back active or failed. Tearing an exposure down drops the
public CNAME — which needs a Cloudflare DNS token to be configured.
Both Web-SSH and Expose target a Node running the agent, keyed by the node's fingerprint so the agent can claim the pending session or job it polls for.
Account → Security — your own MFA
The Account → Security page (/account/security) is where you protect your own
operator account with two-factor authentication — TOTP from an authenticator app
(1Password, Authy, Google Authenticator). It's available to any signed-in admin (no
extra privilege), and shows your email plus a root badge if you're the root super-admin.
- Set up 2FA begins enrollment: scan the QR (or copy the secret), then confirm the 6-digit code. Once enabled, a code is required at every sign-in.
- Disable 2FA turns it off again.
MFA enforcement across the operator team is a platform policy set on the Settings page, not here — this page is your personal enrollment.
The identity add-on (Clerk-style, for tenants)
Separate from operator identity above, HostSSH ships a multi-tenant identity add-on
(lib/addons/identity) — a Clerk-style layer built on the self-hosted, MIT-licensed
better-auth on our own Postgres (no third-party auth service). It provides orgs,
members and invites, email + optional Google sign-in, passkeys / WebAuthn, 2FA,
M2M API keys, and JWT/JWKS. The active organization is the canonical tenantId that
every other add-on (email, webhooks, scraper, DNS-integrity) scopes by, and the local
JWKS verify chokepoint is what makes Postgres row-level security trustworthy.
Status. The add-on's better-auth server and the verify chokepoint are stood up in code; going fully live needs
DATABASE_URL, theHOSTSSH_AUTH_*env vars, and the0015-identitymigration applied as the owner role. It powers the tenant identity layer, not the operator sign-in this page otherwise documents.
Related
- God mode (admin overview) — the RBAC catalog, session model, and demo-vs-persisted rules that gate every page above
- Web-SSH & access — the customer-facing story of keyless-by-default SSH, ephemeral keys, and audited sessions
- Tenants — the customer orgs you can impersonate or simulate
- Access Requests — the queue that feeds the Users directory
- Settings & system — MFA enforcement, impersonation ceiling, and the connection health that Access depends on