Features
Identity and access
Who is signed in, what they may do, and how the first account comes to exist. This is
CONTRACT.md Addendum v0.5 as services/rust/orbit-api implements it: local users, sessions,
roles over a closed permission set, and an audit line for every change (see
audit.md). People can also sign in through Google (Addendum v0.8) or any
OpenID Connect provider (Addendum v0.19); see "Single sign-on".
Two credentials, two jobs
Every call into orbit-api carries two things, and they answer different questions.
| Credential | Who holds it | What it proves | Where it travels |
|---|---|---|---|
Service bearer ORBIT_AUTH_TOKEN | web's server only | The call came through web (Addendum v0.2) | Authorization: Bearer ... on every proxied call |
| Session token | The browser, inside an HttpOnly cookie | Which person is asking | Cookie orbit_session from the browser to web; X-Orbit-Session from web to orbit-api |
orbit-api checks the bearer first, then the session, then the one
permission the route asks for. No session is 401 unauthorized; a session whose role lacks
the permission is 403 forbidden, with the permission named in the message and an
access.denied event in the audit trail. With ORBIT_AUTH_MODE=disabled (local demos
only) there is no bearer to check, and the session is still verified.
Routes that answer without a session, the whole list (PUBLIC in
services/rust/orbit-api/src/api.rs): GET /healthz, GET /readyz,
GET /api/v1/auth/state, POST /api/v1/auth/login, POST /api/v1/auth/setup,
POST /api/v1/contact, and the single sign-on pairs POST /api/v1/auth/sso/start and
/callback (Google) and POST /api/v1/auth/sso/oidc/start and /callback. Every other
route, including one nobody has written yet, needs a session. GET /api/v1/version and GET /api/v1/nocturne/models need a session and no
permission.
On the browser side, a Deck page requested without the cookie is redirected to /login
(/pt-BR/login in Portuguese) with ?next= set to the page, and the Deck layout checks
the session again against orbit-api before it renders anything. A web server with no
ORBIT_API_URL has no one to sign in: it serves the console as an anonymous read-only
demo, with the permissions of the viewer role, and the admin pages say they need
orbit-api.
The first admin
orbit-api creates the first account at startup, and only while no user exists. It tries
three sources, in this order.
1. ORBIT_ADMIN_USER and ORBIT_ADMIN_PASSWORD_VERIFIER. Set both or neither: one
without the other refuses to start. The verifier is the PBKDF2 string
apps/web/scripts/hash-password.mjs prints, never the password itself:
openssl rand -base64 24 > admin-password && chmod 600 admin-passwordORBIT_ADMIN_PASSWORD_VERIFIER="$(node apps/web/scripts/hash-password.mjs < admin-password)"The script refuses anything under 15 characters and writes 600,000 iterations;
orbit-api accepts a verifier of 210,000 iterations or more and refuses a malformed one at
startup. The username must match [a-z0-9][a-z0-9._-]{0,31}. Where the two values go is
install-path specific: the release Secret for Helm and plain manifests
(install/helm.md, install/kubectl.md),
.env for compose (install/docker-compose.md). The pair is
read on every start and ignored once any user exists (the log says so); changing it later
changes nothing.
2. The demo users, when ORBIT_DEMO_DATA=true and no admin pair is set: admin,
editor and viewer, one per built-in role, sharing one password per install:
ORBIT_DEMO_PASSWORD, which the Helm chart draws into its Secret at install, or a random one
orbit-api draws when that is empty. orbit-api prints it once, in a WARN line with a
demo_password field, at the start that creates the accounts; the login page lists the
enabled ones without it. Read it back with
kubectl -n sreorbit get secret sreorbit-secrets -o jsonpath='{.data.ORBIT_DEMO_PASSWORD}' | base64 -d
on Helm, or docker compose logs orbit-api | grep demo_password on compose. An account an
older release created with its public password gets this one at the next start. They exist to demo
the roles; they are ordinary accounts once created, so a data directory that started on
demo data keeps them even after ORBIT_DEMO_DATA turns false. Delete them, or start
production on an empty data directory.
3. A one-time setup code, when neither applies (a live install with no admin pair).
orbit-api logs it once at startup, as a WARN line with a setup_code field:
kubectl -n sreorbit logs deploy/sreorbit-orbit-api | grep setup_codeOn compose,
docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml logs orbit-api | grep setup_code.
Open /login: while no user exists it offers "create the first admin", which takes that
code, a username, a name and a password, creates the account with the admin role and
signs you in. The code is 12 characters in groups of four (dashes and spaces are ignored
when you type it), lives only in the process's memory and dies with it: a restart before
the admin exists prints a new one, and once the admin exists there is no code at all. Five
wrong codes from one address start a wait that doubles up to 15 minutes. The same step
from a shell, against orbit-api port-forwarded as in "Signing in from a shell" below,
with setup.json holding setupCode, username, name and password:
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \ --data @setup.json localhost:8080/api/v1/auth/setupIt answers 201 with the new user, 401 for a wrong code and 409 once any user exists.
Signing in
In a browser: /login. From a shell, write the credentials to a file only you can read
(printf is a shell builtin, so the password never shows up in ps):
umask 077printf '{"username":"%s","password":"%s"}\n' admin 'REPLACE_WITH_THE_PASSWORD' > login.jsonReplace REPLACE_WITH_THE_PASSWORD with the password of that account: the contents of
admin-password for the env admin, the install's demo password for a demo user, or the one typed at
setup. A password holding " or \ needs JSON escaping.
Signing in from a shell
Through web, the way the browser does it. web's route sets the cookie and strips the
token from the body, so keep a cookie jar. When web's own Basic auth is on (the chart's
default; see security.md), add -u "admin:$(cat web-password)" to both
calls, where admin is the WEB_AUTH_USER you put in the Secret and web-password the
file you hashed into WEB_AUTH_VERIFIER. YOUR_REAL_HOSTNAME is your ingress.host:
curl -fsS -c orbit.cookies -H 'content-type: application/json' --data @login.json \ https://YOUR_REAL_HOSTNAME/api/v1/auth/logincurl -fsS -b orbit.cookies https://YOUR_REAL_HOSTNAME/api/v1/auth/meDirectly against orbit-api, for scripts and agents inside the cluster: the login answer
carries the token, and every later call sends it as X-Orbit-Session beside the bearer:
kubectl -n sreorbit port-forward svc/sreorbit-orbit-api 8080:8080 &SESSION="$(curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H 'content-type: application/json' \ --data @login.json localhost:8080/api/v1/auth/login | python3 -c 'import json,sys; print(json.load(sys.stdin)["token"])')"curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/auth/me$ORBIT_AUTH_TOKEN is the bearer you generated at install time; on the k3d loop read it
from the release Secret, as install/local-k3d.md shows.
What a refusal means
| Answer | Why |
|---|---|
401 unauthorized | Wrong username or password. The message is the same for an unknown username, and a sign-in takes as long either way, so a refusal does not reveal which accounts exist. |
403 forbidden | The password was right and the account is disabled. |
429 rate_limited + Retry-After | A wait is running. Nothing is checked until it ends. |
401 mfa_required | The password was right and the account signs in with a code too: send it as code. Nothing is counted. |
401 mfa_wrong | The code was wrong or already used. Counts as a failed sign-in. |
Failures are counted per username and per client address before any password is checked.
A username gets 5 free failures, then a wait that starts at 1 s and doubles up to 1 minute;
a client address gets 20, then up to 15 minutes. The address budget applies only when an
edge proxy named the client (see "How the client IP is determined" in
audit.md); without one every visitor arrives from web's address and only
the username budget holds, so one visitor cannot lock everyone else out. On top of that the
sign-in routes allow 30 requests a minute per named client, and 300 a minute shared by all
unattributed ones. A correct sign-in clears the username's count, 30 minutes without a
failure forgets it, and a restart of orbit-api forgets every count.
Two-step sign-in
A role that holds users.manage or settings.manage signs in with a password and a 6-digit
code from an authenticator app (TOTP, RFC 6238: HMAC-SHA1, 30-second steps, the codes 1Password,
Bitwarden, Google Authenticator and Authy show). Any other account may turn it on too. A demo
account never has it: everyone who reads the demo password shares it.
- Enrolling. The first time such an account signs in with its password, the Deck opens
/login/secureand nothing else:orbit-apianswers that session403 mfa_enrollment_requiredeverywhere butGET /api/v1/auth/me, sign-out and the two calls below.POST /api/v1/auth/mfa/setupdraws a new 20-byte key and answers it once, in base32 and as anotpauth://link.POST /api/v1/auth/mfa/confirmwith{"code":"123456"}turns it on: this session counts as one that gave a code, and every other session of the account ends. A role that gains one of the two permissions later gets the same page at its next request. - Signing in. With a second factor on,
POST /api/v1/auth/logintakescodebesideusernameandpassword. Without it, a right password answers401 mfa_requiredand counts as nothing; a wrong code, or one already used, answers401 mfa_wrongand counts as a failed sign-in for the username and the address, so codes cannot be guessed faster than passwords. A code works once:orbit-apikeeps the last time step it took. - Losing the phone. An admin turns it off from
PATCH /api/v1/users/{id}with{"mfa": false}(audited asuser.mfa_reset); every session of that account ends, and its next sign-in enrolls again. The subset rule applies: you reset only an account whose role holds nothing yours lacks. Turning off your own needs your password and a code (see Passwords below). - The key at rest.
orbit-apiseals it withORBIT_SEAL_KEY(AES-256-GCM, the same sealing as database and SSO secrets) when that key is set, and stores it as typed otherwise. The chart drawsORBIT_SEAL_KEYat install whensecrets.sealKeyis empty and keeps the one its live Secret holds on every upgrade, so a default install seals every key. A key stored as typed before the install hadORBIT_SEAL_KEYgets sealed at the first start with one. It never leaves the store after the setup answer and never reaches the audit trail. KeepORBIT_SEAL_KEYwith your other secrets and back it up: under another key, or with none, a sealed key no longer reads, and every account with a second factor gets401at sign-in, admins included. Setting the old key back restores them. If it is lost, an account that still signs in withusers.manageturns the others' factor off; plan one such account (an SSO admin, whose sign-in needs no local factor) before you rotate the key. - SSO sessions bring the identity provider's own factors: Google and OIDC sign-ins skip this step. Require MFA at the provider.
- API tokens of an account whose role needs the second factor work only once it is on, or when the account signs in through SSO.
- Rollback. A release before this one ignores the key and signs the account in with the password alone; it drops the key the first time it rewrites that user, so the account enrolls again after you upgrade back.
Single sign-on
People can also sign in through an identity provider; the local username and password stay
for the emergency admin. Each provider is off until an admin configures it at Admin >
Integrations (settings.manage) or the environment seeds it, and /login shows its
button only while it can sign someone in. Google is Addendum v0.8: one Workspace, its
domains, one role for a first sign-in. The rest of this section is the generic provider of
Addendum v0.19.
Any OpenID Connect provider
One provider at a time, beside Google: Okta, Microsoft Entra ID, Keycloak, Auth0, or any other that publishes a discovery document. What the admin sets:
| Setting | Default | Notes |
|---|---|---|
| Issuer URL | none | https only, no query, fragment or credentials. orbit-api reads <issuer>/.well-known/openid-configuration, follows no redirect, and refuses a document whose issuer is not this exact string (Auth0's ends in /, Entra ID's in /v2.0). |
| Client ID and secret | none | A confidential web client on the authorization code flow. The secret is write-only: no read answers it, and the audit trail records only that it changed. |
| Scopes | openid email profile | openid is required. Add the scope your provider sends groups for (groups on Okta). |
| Button name | SSO | "Sign in with" this name on /login; the audit trail names the provider by it. |
| Allowed email domains | any | When set, the email's domain must be on the list. |
| Email claim | email | A top-level claim holding the address. When the ID token carries email_verified, it must be true; without it the person can still get a new account, but no existing account is linked to them. |
| Groups claim | groups | A top-level list of strings (a single string works too). |
| Group to role | none | Ordered rows: the first row whose group the person is in gives the role, admin included, as long as the admin saving the settings holds every permission of that role. |
| Role when no group maps | viewer | A role that manages neither users nor settings, or deny, which refuses the sign-in. |
Register https://<your console>/api/v1/auth/sso/oidc/callback as the redirect URI (the
settings page prints it with the host you reached it on). Run Test before turning the
provider on: it reads the discovery document and the signing keys, then tries the client ID
and secret at the token endpoint with a code that cannot exist, so invalid_grant proves
the credentials. A test saves nothing. The stored secret goes only to the stored issuer for
the stored client ID: to test another issuer or client, type its secret. Every test writes
settings.test to the audit trail with the issuer, the client ID and each check's result.
The flow. web's GET /api/v1/auth/sso/oidc/start asks orbit-api to open a flow
(state, nonce and a PKCE S256 verifier, good once for 10 minutes), keeps its binding in the
same HttpOnly cookie the Google flow uses and sends the browser to the provider. The
provider returns to /api/v1/auth/sso/oidc/callback; web hands the state, the binding and
the code to orbit-api, which redeems the code with the verifier (client_secret_post when
discovery lists it, client_secret_basic otherwise) and checks the ID token:
- signed RS256, PS256 or ES256 by a key in the provider's JWKS, never
noneor an HMAC; RSA keys of 2048 bits or more, EC keys on P-256, and a key the JWKS pins to one algorithm is used for that one only; - the JWKS is read with a 1 MiB cap and a 10 s timeout and cached for its
max-age(5 minutes to a day); an unknownkidfetches it again at most every 30 s, so a key rotation is picked up and a flood of inventedkids is not; issexactly the configured issuer;audholds the client ID, andazpmust be the client ID when there are several audiences or whenever it is present;exp,nbfandiatwithin 60 s of skew and issued during the flow; thenoncethe flow's own;- then the email,
email_verified, the domain and the groups, as in the table.
Accounts. The account linked to the provider's subject (sso: "oidc:<sub>") signs in;
failing that, the one local account with the email (ASCII case ignored, not a demo account,
not linked to another provider) is linked, but only when the ID token says
email_verified: true (email_unverified otherwise) and the account holder set that email, or
saved it, with their password and a code. An email another admin typed into someone's account
links nothing (email_unproven) until its holder saves it with that proof from their own drawer
on /deck/admin/users. Failing that, a new account is created,
its username taken from the email's local part. With a group mapping, the role it gives is
written onto the account at every sign-in: a group removed at the provider takes the
role away at the next one, and a user.role_change event records it. Without a mapping,
the default role applies to new accounts only and admins change roles in the Deck, as with
Google. A role change that would leave no enabled user holding users.manage refuses the
sign-in instead (last_admin). The settings remember the permissions of the admin who saved
them, and no sign-in through them lands on an account whose role holds more (beyond_provider):
someone who manages settings but not everything cannot point the console at an identity
provider of their own and sign in as an admin. Settings saved before this rule, and the
environment seed, carry no such limit. The session is the ordinary one: 24 hours, revocable.
Refusals and the trail. Each sign-in writes auth.login with method: "oidc", the
provider's name, the issuer and the role. Each refusal writes auth.login_failed with the
same fields and a reason: invalid_state, expired, off, cancelled, provider_error,
exchange_failed, invalid_token (with the check that failed: format, algorithm,
key, signature, issuer, audience, expired, not_before, issued_at, nonce or
subject), unavailable, no_email, email_unverified, domain_not_allowed,
no_group, disabled, or an account conflict (linked_elsewhere, ambiguous_email, email_unproven,
demo_account, role_missing, default_role_missing, default_role_unsafe,
last_admin, beyond_provider). A refused person lands on /login?oidc=<why>, told in their language. The
two routes are counted in orbit_http_requests_total, by status, under
POST /api/v1/auth/sso/oidc/start and POST /api/v1/auth/sso/oidc/callback.
Seeding it from the environment. While the store holds no OIDC settings, orbit-api
reads ORBIT_SSO_OIDC_* (configuration.md); from the first save in
the console on, the console's settings win. The client secret belongs in the Secret
(secrets.ssoOidcClientSecret in the chart). A client secret saved in the console, for OIDC or
Google, sits in the store sealed with ORBIT_SEAL_KEY (AES-256-GCM, the key the database
connections use) when that variable is set; one an earlier release kept in the clear gets sealed
at the next save of its page. Without ORBIT_SEAL_KEY the store keeps it as typed. If you change
the key, sign-in through that provider stops until an admin types the secret again. The same
happens after a rollback to a release without sealing: it sends the sealed text as the secret,
so type the secret again on the provider's page after you roll back. A save that changes the
issuer or the client ID takes the client secret again: the stored one only ever goes to the
issuer and client it was typed for. To read what
is in effect, with an admin's
SESSION from "Signing in from a shell":
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ localhost:8080/api/v1/settings/sso/oidcPasswords
orbit-api stores a PBKDF2-HMAC-SHA256 verifier for every password it sets: 600,000
iterations, a 16-byte random salt, a 32-byte hash, the same format as web's own
WEB_AUTH_VERIFIER. A new password needs at least 12 characters, at most 128, no control
characters, must not equal the username, and must not be one of the 10,000 passwords of 12
characters or more leaked most often (SecLists tag 2025.3, case ignored). There are no composition
rules and no expiry. Sign-in still accepts up to 1,024 bytes, so a longer password set earlier
keeps working.
- Your own password: the Account page (
/deck/account), orPOST /api/v1/auth/passwordwith{current, next}. A wrongcurrentis400, and counts as a failed sign-in for your username. Every other session of yours ends; this one stays. - Someone else's: an admin sets a new one from the user's drawer on
/deck/admin/users, orPATCH /api/v1/users/{id}withpassword. Every session of that user ends. - Your own through
PATCH /api/v1/users/{id}on your own id, withpasswordor{"mfa": false}: send your password ascurrent, and with a second factor on, a freshcodetoo. Without them, or with a wrong one,orbit-apianswers400(mfa_requiredormfa_wrongfor the code), counts a failed sign-in for your username and audits the refusal. Someone who stole your session cannot set a password and a key of their own and lock you out. Every other session of yours ends; this one stays. - Your own email through the same route takes the same proof: SSO links an account by its
email, so a stolen session could otherwise point your account at an address the thief holds
at the provider. A missing password answers
400and costs no attempt. An email an admin sets on someone else's account is saved, and SSO does not link that account by it until the holder saves it with their password and a code. - After a proof (your password and a code here, for a token, or a sign-in again at the provider) the same session needs none for 5 minutes.
- Each of these changes, on any account, posts a security notice to the alert channels that
take them (
alert-notifications.md). - A password an admin typed, when creating a user or resetting someone else's, is a first
password only: its next sign-in lands on
/login/secureand changes it before anything else (orbit-apianswers403 password_change_requiredto everything else). Then a role that needs it enrolls its second factor. - A password set before it made the leaked list still signs in, and lands on the same page.
- Every new-password field in the Deck shows a strength meter as you type. It is a rough
guess from length and character mix;
orbit-api's rules above decide.
Sessions
- Token. A 32-hex-digit session id and an HMAC-SHA256 signature over it. A forged or
altered token is refused before anything is looked up. The key is
ORBIT_SESSION_SECRETwhen set (32 bytes or more); otherwiseorbit-apigenerates a 32-byte key once and keeps it inORBIT_DATA_DIR/session.key. Changing the secret or deleting the file ends every session at once. - Lifetime. 24 hours from sign-in, absolute: activity does not extend it. A session that
no request used for 8 hours ends too, and its next request is
401. An open Deck tab keeps reading only while the browser lets it run: a tab it freezes, or a laptop asleep, counts as no request. A restart oforbit-apistarts every idle clock again. A user keeps at most 100 sessions; the oldest go first. Expired ones are swept at most every 10 minutes. - Revocation. A session is also a document under
ORBIT_DATA_DIR/sessions, deleted on logout, on disable, on a password change or reset, and by "End all sessions" (POST /api/v1/users/{id}/revoke-sessions). The next request with that token is401. A password change or reset, and a second factor turned off, also delete every API token of the account (seemcp.md). - Your own sessions. Account, "Your sessions" lists every browser signed in to your
account (
GET /api/v1/auth/sessions: when it signed in, from which address and browser, when it ends, and which one is this browser). Typing your password there signs out the others (POST /api/v1/auth/sessions/end-others, metered like a sign-in and audited asauth.sessions_end_others). A demo account sees only its own session and ends none. An account Google or OIDC created has no password: the page offers "Sign in again with Google" (or your provider's name) instead. The session that sign-in starts signs the others out without a password for 5 minutes, and only when the provider's id_token says inauth_timethat you signed in there after you clicked, a minute of clock skew allowed. With an olderauth_time, or none, you get an ordinary session, and the page says the provider did not confirm it asked for your credentials. "Change password" says the account has no password instead of showing a form it cannot use. For OIDC,orbit-apisendsprompt=loginandmax_age=0. The first asks the provider for your credentials; the second makesauth_timea required claim (OpenID Connect Core 3.1.2.1). Google takes no reauthentication request: its sign-in may reuse the Google session your browser already has, and thenauth_timeis old. Google sendsauth_timeonly when the request asks for it, whichorbit-apidoes withclaims={"id_token":{"auth_time":{"essential":true}}}, and only when "Session age claims" is on in Google Auth Platform, Settings, Advanced settings (the app must be in production and verified). Without that setting, a Google account without a password cannot sign its other sessions out; an admin can, with "End all sessions". To get a freshauth_time, sign out of your Google account in that browser first, then sign in again. - Role changes. The permissions are read from the user's role on every request, so a role change, or an edit of the role itself, applies to the next request, without a new sign-in.
- The cookie.
__Host-orbit_sessionwhen the browser is on https (X-Forwarded-Proto, or an httpspublicUrl, which outranks that header: seeconfiguration.md), withSecureand noDomain, andorbit_sessionon plain http;HttpOnly,SameSite=Lax,Path=/, and aMax-Ageequal to the session's remaining lifetime. Onlyweb's two routesapi/v1/auth/loginandapi/v1/auth/logoutwrite it; page JavaScript cannot read it.webcopies its value intoX-Orbit-Sessionand never forwards the browser'sCookieheader.
Your data
Account, "Your data", downloads what orbit-api keeps about you as one JSON file
(GET /api/v1/auth/export, audited as user.export): your account, your sessions, your API
tokens' names and expiry, the saved views, SQL queries and Nocturne chats you own, and the audit
events you caused in the last 90 days, at most 1,000. It holds no password verifier, second
factor key, token secret or webhook. A demo account is shared and exports nothing (403). To
remove your data, delete your views, queries and chats where you made them; an admin deletes
the account itself.
Roles and permissions
A user holds exactly one role, and a role is a set of permissions from this closed list. Each route asks for one of them; the Deck hides the sections a role does not grant and refuses them before the page reads anything.
| Permission | Grants | Deck section |
|---|---|---|
estate.read | Clusters, nodes, workloads, events, alerts, FinOps, recommendations, workload events, and Nocturne's read routes | /deck and everything under it not listed below |
telemetry.query | query_range, the engine's label, series and instant reads, Nocturne's PromQL tool | /deck/observability, /deck/explore, every dashboard panel |
apm.read | Traces, services, operations and the service map | /deck/apm |
logs.read | Container logs of a workload's pods, and the stored logs | The logs tab of a workload, /deck/logs |
databases.query | Database monitoring and read-only SQL on the database connections the role reaches (/api/v1/databases, POST /api/v1/sql/query and /explain with a database) | /deck/databases, /deck/sql |
databases.raw_sql | With databases.query: a monitored statement's recent runs with their values, each reveal audited | "Show values" in a statement's drawer |
dashboards.read | Listing and opening dashboards | /deck/dashboards |
dashboards.write | Creating, changing and deleting saved dashboards | Edit and Save on a dashboard |
nocturne.use | POST /api/v1/nocturne/chat and /analyze | /deck/nocturne |
workloads.write | Scale and resources writes, CronJob suspend, resume and run now, alert acknowledgements and silences, never in orbit-api's own namespace or kube-system | The Scale and resources tab |
config.read | A workload's environment against its ConfigMaps and Secrets, and revealing one masked value, never in orbit-api's own namespace; Nocturne's ConfigMap tool, the env values in its pods tool and the values its patch check diffs (without it, each variable shows its name and source and the value [redacted]); every view and every reveal is audited | The Configuration tab of a workload |
users.manage | Users, roles, the sales leads list | /deck/admin, /deck/admin/users, /deck/admin/roles, /deck/admin/leads |
audit.read | The audit trail and its CSV export | /deck/admin/audit |
settings.manage | The console's settings page, the ingestion rules, and the AWS account's bill on the FinOps overview | /deck/settings, /deck/admin/ingestion |
workloads.write is necessary and not sufficient: a scale or resources change also needs
the deployment to allow writes (ORBIT_WRITE_ENABLED=true with the write ClusterRole,
Addendum v0.4) and the operator token on web's hop. Opening a dashboard needs
dashboards.read, and drawing its panels needs telemetry.query as well: a role with the
first and not the second sees the layout with every panel refused.
Built-in roles
| Role | Permissions |
|---|---|
viewer | estate.read, telemetry.query, apm.read, logs.read, dashboards.read |
editor | Everything viewer has, plus dashboards.write, nocturne.use and workloads.write |
admin | Every permission in the list |
Built-in roles live in the binary: nothing in the data directory can change them, and an
edit or a delete is 400. For another set, create a custom role (or clone a built-in one
in the Deck and edit the copy).
Custom roles and the rules that protect an install
- A custom role has a name (1 to 64 characters, unique), a description of up to 280
characters, and any subset of the permissions above; an unknown permission is
400. - A custom role may list the database connections its
databases.queryreaches (databases, up to 64 connection ids); none listed is every connection. Outside the list a connection answers404on every database route. Seedatabases.md, "A role for a database team". - A role that any user holds cannot be deleted (
409): move its users first. - Nobody changes their own role, disables their own account or deletes it (
400). - Nobody grants more than they hold. Creating or editing a role, giving a user a role, and
changing, resetting, disabling, deleting or ending the sessions of an account all need the
actor's own role to hold every permission involved; otherwise the answer is
403and anaccess.deniedevent withreason: "subset". With the built-in roles onlyadminmanages users, so nothing changes; a custom role withusers.managemanages only the accounts and roles it outranks. The same rule applies to the roles an SSO setting gives, and to database connections: an actor whose role lists some grants and touches only roles that list some of the same. - No change may leave zero enabled users who hold
users.manage: a disable, a delete, a role change or an edit of a role that would do so is409.
Managing users and roles
In the Deck, with users.manage: /deck/admin/users creates users, changes roles, resets
passwords, disables, enables and deletes accounts and ends sessions;
/deck/admin/roles creates, edits, clones and deletes custom roles and shows the full
permission matrix. From a shell, with the SESSION of an admin from "Signing in from a
shell" above: list the roles, create a user, promote them, end their sessions.
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" localhost:8080/api/v1/rolescurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \ -d '{"username":"grace","name":"Grace Hopper","email":"grace@example.com","role":"viewer","password":"REPLACE_WITH_AN_INITIAL_PASSWORD","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' \ localhost:8080/api/v1/userscurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \ -X PATCH -d '{"role":"editor","current":"REPLACE_WITH_YOUR_PASSWORD","code":"CODE"}' localhost:8080/api/v1/users/USER_IDcurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -X POST \ localhost:8080/api/v1/users/USER_ID/revoke-sessionsCreating a user, and setting another account's password, second factor, email or role,
take your own password as current and, with a second factor on, a code: without them the
answer is 400, audited as a refusal under your name. One proof covers the same session for
5 minutes. Saving the Google or OIDC settings takes the same proof: a provider lets people in.
Name, disable, delete and ending sessions take none: they only take access away.
REPLACE_WITH_YOUR_PASSWORD and CODE are yours, typed again.
REPLACE_WITH_AN_INITIAL_PASSWORD is a password you choose for the new user (12
characters or more, not the username) and hand over on a channel you trust. USER_ID is
the id field of that user in the answer to the create call, or in GET /api/v1/users
(16 hex digits), not the username. Every shape and error of these routes is in
api.md; every change above lands in the audit trail named by what
changed (user.role_change, user.disable, user.password_reset, ...).
Where the state lives
Everything on this page is files under ORBIT_DATA_DIR (default /var/lib/sreorbit), one
JSON document per object, each written to a temporary file, fsynced and renamed into
place, so a crash leaves the old version or the new one and never half of either:
| Path | Holds |
|---|---|
users/ | One document per user, with the password verifier |
roles/ | Custom roles (built-in ones are in the binary) |
sessions/ | One document per live session |
dashboards/ | Saved dashboards (dashboards.md) |
alertstate/ | Alert acknowledgements and silences, one document per cluster |
leads/ | Submissions of the site's contact form |
settings/ | Sign-in settings: sso for Google, oidc for the OpenID Connect provider, secrets included |
audit/ | The audit trail, one JSONL file per UTC day (audit.md) |
changes/ | The change timeline, one JSONL file per cluster and UTC day, 14 days (audit.md) |
changestate/ | What the change timeline's last tick saw, one document per cluster |
session.key | The session signing key, when ORBIT_SESSION_SECRET is not set |
orbit-api refuses to start when the directory is not writable. The store has one
writer, which is why every install path runs orbit-api as one replica: the chart
renders replicas: 1 whatever replicaCount says and refuses to render with autoscaling
on (components.orbit-api.singleWriter). With components.orbit-api.persistence.enabled
the directory is a ReadWriteOnce claim and the Deployment uses Recreate; without it, an
emptyDir that loses every user, session, dashboard and audit line with the pod. Compose
mounts the named volume orbit-api-data. Backups: operations.md.
Nocturne acts as the signed-in user
When someone asks Nocturne a question, orbit-api's proxy passes their X-Orbit-Session
through to nocturne, and every cluster tool call Nocturne makes carries it back to
orbit-api. A tool therefore reads exactly what that person may read (its PromQL tool
needs telemetry.query, the rest estate.read), and a refusal lands in the audit trail
under their name.
Ceilings
- One OpenID Connect provider at a time, beside Google; no SAML. The groups must be a
top-level claim of the ID token: Entra ID's group overage (past 200 groups it sends a link
instead) is not followed.
ORBIT_AUTH_MODE=oidc, which is about the service bearer and not about people, still refuses to start. - TOTP is the only local second factor. No WebAuthn or FIDO keys and no recovery codes: a lost phone is an admin reset. No SCIM, no password expiry.
- One replica. The file store has one writer; the upgrade path named in the source is
Postgres, which is what lets
orbit-apiscale out. - Sign-in waits are per process. A restart of
orbit-apiforgets them, which a single replica can live with. - No per-dashboard or per-cluster scoping. A permission applies to every cluster and every saved dashboard.
Where to go next
- What every change and refusal leaves behind, and how to read it:
audit.md. - The threat model around sessions, cookies and cross-site requests:
security.md. - Every variable on this page with its default:
configuration.md.