Auth & RBAC
Four roles, two scopes, three kinds of identity — local password + TOTP, LDAP/AD federation, and single sign-on through OIDC, SAML 2.0 and GitHub (Sign-in methods). Each account uses exactly one of them. Browser sessions are JWT in httpOnly cookies with double-submit CSRF and refresh-token reuse detection.
Roles & scope
owner ⊃ admin ⊃ operator ⊃ viewer
Roles are hierarchical — a higher role implies every capability of lower roles. Scopes are orthogonal:
- Org role applies to every project in the organisation by default.
- Project role overrides on a per-project basis. Most-permissive wins — a user who is org viewer + project operator is operator on that project, viewer elsewhere.
- Org-level actions (user management, LDAP, license) ignore project roles — only org-wide roles count, the user's own or one it has through a user group (a group never holds owner, so owner-only actions always need a user's own owner role).
- User groups add roles: a member has its own roles plus the roles of its groups, and the highest one wins in each project. A group never holds the owner role.
| Role | Description |
|---|---|
| Owner | Full control. The only role that can create users, assign or change roles, force a password reset, configure LDAP and the OTP policy, create or delete projects, and hand ownership on by granting the owner role to another user. Verifying the audit chain is also owner-only. |
| Admin | Deactivates or deletes non-owner users, manages the licence, syslog and general settings, and holds admin rights inside projects. Cannot create users, grant roles, configure LDAP, or create/delete projects — those are owner-only. |
| Operator | Day-to-day cert operations — issue, renew, reissue, and distribute (link a distribution to a certificate, execute, dry-run, roll back). Can also edit the distribution-side config surface — Targets, TargetGroups, PathSets/ActionSets, project-variables, module configs — but by default only through the approval gate (see below). Cannot build issuance infrastructure (ACME accounts, DNS credentials) or module credentials (they hold secrets — admin-only), and cannot delete certificates or manage users/org settings — those are admin. Can revoke certificates (the whole certificate or one retained version); when the project's approval policy gates revocation for that operator, the revocation waits for a project admin's approval. |
| Viewer | Read-only. Dashboards, cert listings, job status, audit logs. No mutations. |
Action → minimum role
The lowest role that can perform each action. Project-scoped actions check the user's project role; org-scoped actions ignore project overrides.
| Action | Minimum role | Scope |
|---|---|---|
| Issue / renew / reissue certificate | operator | project |
| Import / re-import certificate (bring-your-own) | admin | project |
| Revoke certificate | operator (through approval when the project's approval policy gates revocation for them) | project |
| Download private key | operator — there is no separate key-export permission | project |
| Delete certificate | admin | project |
| Distribute: link a distribution to a cert · execute · dry-run · roll back · unlink | operator (approval-gateable — no approval by default) | project |
| Configure issuance: ACME accounts · MSCA connections · CA connections (vendor APIs) · DNS credentials · zones | admin | project |
| Configure distribution — targets · target-groups · PathSets/ActionSets · project-variables · module configs | operator (approval-gated by default) | project |
| Configure distribution — module credentials | admin (they hold secrets) | project |
| Configure distribution — secret stores | admin (they hold the connection to your secret manager) | project |
| Health-check a target / module / credential | admin | project |
| Certificate policy | admin | project |
| Approval policy (read / change) | viewer / owner | project / org |
| Notification channels & rules | admin | project |
| Create users · assign roles · force password reset · LDAP · OTP policy | owner | org |
| Create / delete projects | owner | org |
| Rename / update a project | admin | project |
| Deactivate / delete a user · licence · syslog · general settings | admin | org |
Role assignment is owner-only. There is no graded "assign at or below your own level" ladder: only an owner can grant or change any role. An admin can deactivate or delete a non-owner user but cannot grant a role to anyone, including themselves.
An organization always keeps an active owner. Removing the owner role from the last active owner, deactivating that user, or deleting them is refused with a 400. Grant the owner role to another active user first; the former owner can then step down.
Distribution & targets — who builds vs who wires
Operators can now edit most of the distribution-side config surface and run distributions; the approval gate — not the role — is the control point for the riskier writes. The project's approval policy (Settings → Approvals, changed only by an organization owner) decides whether an operator's action executes directly or must be approved first — for all operators, or only for selected users and groups (see Approval workflow → What can be gated). Admins and owners bypass approval entirely.
- Operators EDIT the deploy config — create/update/delete targets, target-groups (+ members), library PathSets/ActionSets, project-variables, and module configs. Gated by the configuration changes rule of the approval policy, which gates all operators by default (these writes were admin-only before, so the write access is new and approval-gated).
- Admins-only infrastructure — module credentials remain admin (they hold secrets), as do issuance objects (ACME accounts, DNS credentials, zones), and target/module/credential health checks (an operational probe against a live device, not a config mutation).
- Operators WIRE and RUN it — link a distribution to a certificate, execute / dry-run it, and roll back to a previous version (or unlink). Gated by the distribution actions rule of the approval policy, which is No approval by default (opt-in).
| Action | Minimum role | Approval rule (default) |
|---|---|---|
| Create / edit / delete a target | operator | configuration changes (all operators) |
| Create / edit / delete a target-group (+ add/remove members) | operator | configuration changes (all operators) |
| Create / edit / delete a PathSet / ActionSet | operator | configuration changes (all operators) |
| Create / edit / delete a project-variable | operator | configuration changes (all operators) |
| Create / edit / delete a module config | operator | configuration changes (all operators) |
| Create / edit / delete a module credential (holds secrets) | admin | — |
| Health-check a target / module / credential | admin | — |
| Browse a saved target's live resources (pickers, IIS placement preview) | operator | — (audited) |
| Browse with an unsaved target's connection details, or a saved target paired with a different credential | admin | — (that pairing is what the configuration-changes approval reviews) |
| Link a distribution to a certificate | operator | distribution actions (no approval) |
| Update / unlink a distribution | operator | distribution actions (no approval) |
| Execute / dry-run a distribution | operator | distribution actions (no approval) |
| Roll back a distribution (manual, version picker) | operator | distribution actions (no approval) |
| Approve a changed SSH host key on a target | operator | — (never gated; audited with both fingerprints) |
| View targets / modules / credentials / distributions | viewer | — |
A stored credential follows its hosts. Each module credential remembers the hosts it is used with. Pairing it with a new host (a new or edited target, a group or module override, a secret store, a live picker), turning a bound target's certificate check down, or pointing a store-backed credential at another secret is allowed only for the person who entered its secret (for a credential that reads from a secret store, the person who set that store up) or an organization owner. Anyone else — whatever their role — must enter the secret again first; the request is refused with 422 otherwise. Changing where a DNS credential or AD CS connection connects likewise needs its secret in the same request. The credential page shows who entered the secret and the hosts it may reach.
Distributions that run commands need Admin. Executing or rolling back a distribution whose SSH or WinRM targets run an action set, and choosing a distribution's path set or action set, are refused for operators (or become an approval request when the project gates distribution actions); automatic runs after a renewal are not affected.
Reading is open to any project member (viewer+). Admins and owners bypass every
approval gate — their edits and deploys auto-execute and are recorded in the audit
trail. A distribution that runs an ActionSet (commands or a script) on SSH or WinRM
targets needs Admin to execute or roll back by hand, and choosing a distribution's
PathSet or ActionSet override needs Admin too — an operator gets 403, or an approval
request when the project's approval policy gates its distribution actions. The certificate
page's Run and Roll back buttons are disabled for such an operator and say why (the
distribution's runs_commands field). The scheduler's automatic post-renewal distribution sweep is not
gated — only the manual, operator-initiated distribution action is.
Auto-rollback is not a user action — it is a per-distribution setting an operator enables; the system triggers it on a failed/partial run. It fires only for the stateful modules; the push modules (Webhook, SMTP) are manual-rollback only.
Resource grants — limiting a role to some resources
A project role can cover the whole project (the default) or only the resources granted to the user. With Only granted resources the user reaches a certificate, target, credential, module, certificate authority, DNS credential, zone or other granted resource only through a grant on it, and acts with the lower of the grant's role and the project role. Grants are set on each resource's Access tab, panel or button, or in Settings → Users → Roles → Grants, which can also allow creating new resources.
The full rules — what is narrowed, the role matrix per action, what a restricted user sees, approvals and clean-up — are on Resource grants.
Local users
Each user record carries:
| Field | Purpose |
|---|---|
email | Unique per organisation. Used for login, notifications, audit correlation. |
display_name | Shown in UI lists and audit logs. |
org_role | owner / admin / operator / viewer. |
project_roles | Map of project_id → role; per-project overrides. |
auth_source | local (password + optional TOTP), ldap, or sso. Only a local account has a password and profile managed in CertAutoPilot; for the others a password reset, password change or profile edit is refused. |
totp_enabled | Whether the user has enrolled in TOTP. The OTP policy is org-wide — there is no per-user override. |
is_active | Boolean. There is no three-state status and no "pending/invited" state. |
Create: Settings → Users → New user (owner only). Username + email + an initial password + org role — all four required. There are no invite emails and no invite tokens: you set the password and communicate it out of band. Project roles are granted afterwards from Users → Roles.
Disable vs delete: disabling a user ends their access now and is reversible. It revokes every refresh token the user holds, the refresh endpoint refuses a disabled account outright (so a token that somehow survived still cannot mint a session), and a login that is mid-way through the second factor is refused at completion. What remains is the access token already in the browser — it lives at most 15 minutes and is not re-checked per request. Re-enabling restores login with the same roles; the old tokens stay dead, the user simply signs in again. Delete is hard — audit records keep the user's id + display name at time of action for forensics, but you lose the user record itself.
Password reset: there is no forgot-password flow on the login page. A signed-in user changes their own password from their profile (supplying the current one); an owner can force a reset from Settings → Users. A forced reset revokes every refresh token for that user; a self-service change ends every other session and keeps the one it was made in.
Locked out (no admin left)? If the only owner forgot their password and can't reset it from the UI, run the offline recovery command on the server with access to the database (it rewrites the account's bcrypt hash — it does not touch MongoDB's own password).
On a standalone install, run it through the cap wrapper, which loads the database credentials the bare binary can't see from an interactive shell (details in the CLI reference):
cap user reset-password --username <user> --password '<new-password>'
Forgotten the username too? List the accounts first:
cap user list
Anywhere else (Docker, Helm, dev), run the binary with the database credentials in the environment (CERTAUTOPILOT_DATABASE_*) or in the config file:
certautopilot user reset-password --username <user> --password '<new-password>' \
--config /etc/certautopilot/config.yaml
To keep the new password off the command line (where other local accounts can read it from the process list), pipe it in with --password-stdin instead of --password:
printf '%s\n' "$NEW_PASSWORD" | cap user reset-password --username <user> --password-stdin
Add --clear-totp to the reset to also disable two-factor for the account (e.g. a lost authenticator device), and --org-id <id> if the same username exists in more than one org. The new password must meet the panel's password policy. LDAP and SSO accounts are rejected — their passwords live in the directory or identity provider — unless you add --make-local (recovery: the account becomes a local password account, re-activated, its LDAP link, SSO identity and the group memberships they added removed). --enable-local-sign-in turns password sign-in for local accounts back on. Every reset also ends a login lockout. Log in with the new password, then change it from your profile. See Sign-in methods → Locked out.
LDAP / AD integration
Federate against an LDAP v3 directory or Active Directory (owner-configured). Passwords for federated users never land in CertAutoPilot's database.
The backend uses search-then-bind: it binds as a service account, searches for the
user with the configured filter (%s = the login name), then rebinds as the found user
to verify the password.
Setup: Settings → Sign-in → LDAP. Server URL (LDAPS preferred), service-account bind DN + password, search base and user filter. Use the Test Connection and filter test tools before enabling. There is one LDAP configuration per installation.
Auto-provisioning: the first successful login creates the user record with
auth_source: ldap and the role chosen in Default role for new LDAP users —
an org-wide viewer (the default) or none. The user's own roles are managed inside
CertAutoPilot after that. LDAP groups can be linked to user groups:
every LDAP sign-in then joins and leaves the linked groups, whose roles and grants apply.
Two rules the directory cannot override:
- A user you disable in CertAutoPilot stays disabled. A later directory login with a still-valid password is refused and does not re-enable the account — only an admin re-enables it.
- A directory identity whose username matches an existing local account (the setup owner, or any password user) is never attached to that account. A sign-in with that name is always checked against the local password — the directory is not asked — so the local account keeps its source, password and roles. If you want that person federated, delete or rename the local account first.
AD specifics: prefer (userPrincipalName=%s) or (sAMAccountName=%s) as the user filter.
Full field reference, TLS notes, and troubleshooting: LDAP / Active Directory.
Single sign-on (OIDC, SAML, GitHub)
SSO providers are set up on Settings → Sign-in from a catalogue of provider types. An SSO account is created at its first sign-in (when the provider allows it) with the provider's default role, its groups can be synced to user groups, and it is never merged with an existing account. Details: Sign-in methods and SSO providers.
Two-factor authentication (TOTP)
RFC 6238 time-based codes. Seeds are envelope-encrypted; validation accepts ±1 30-second window for clock skew. Works with both local and LDAP users — the directory never sees the OTP code.
Org policy (two modes, owner-set):
- Optional — users may enroll if they want.
- Must — every user without TOTP is forced to enroll at their next login before any session is issued (there is no grace login).
Enrollment: scan a QR code with any RFC 6238 authenticator app (Google Authenticator, Authy, 1Password, Bitwarden), enter the current code to confirm sync, then save the 8 one-shot recovery codes shown — they are the backstop for a lost device and the backend only stores hashes.
If you didn't save them, regenerate from Profile → Regenerate recovery codes (requires a current TOTP code) — all previous codes are invalidated. There is no admin-side OTP reset.
Login failure returns generic "invalid credentials" — no distinction between wrong password and wrong code. Repeated failures trigger a progressive account lockout. A wrong second-factor code counts toward that lockout exactly like a wrong password, and the failure counter is reset only when a login fully succeeds (password and code), so starting a new login does not hand out a fresh budget of code guesses. Each OTP session allows 5 attempts in total, no matter how many are sent at once.
Policy details, session limits, and disable flows: OTP policy.
Programmatic access
There is no separate API-key credential. Scripts, CI/CD, and Terraform authenticate as a regular user and carry a JWT bearer token:
POST /api/v1/auth/loginwith{username, password}→ anaccess_token(Bearer, 15 min TTL) plus arefresh_token(7 days). MFA users completePOST /api/v1/auth/otp/verifyfirst.- Send
Authorization: Bearer <access_token>on each request. Header/bearer auth bypasses CSRF — a browser can't attach anAuthorizationheader cross-site, so it is CSRF-immune. - When the access token expires,
POST /api/v1/auth/refreshwith{refresh_token}mints a fresh pair.
A programmatic caller has exactly the identity, org role, and project roles of its user — there is no distinct key role or key scope. To limit blast radius, create a dedicated user with a minimal role (e.g. an operator scoped to one project) for automation.
Full walkthrough, wire shapes, and cookie details: Programmatic access.
Sessions, JWT & CSRF
Browser logins use JWT in httpOnly cookies. There are three tokens in play:
- Access token — JWT signed HS256.
httpOnly,SameSite=Lax— the double-submitX-CSRF-Tokenheader, not the cookie attribute, is what blocks cross-site mutations. Default TTL 15 min (jwt.access_token_ttl). - Refresh token — opaque 32-byte random, SHA-256-hashed in the DB.
httpOnly, scoped to/api/v1/auth. Default TTL 7 days. - CSRF token — random 32 bytes in a JS-readable cookie, required in
X-CSRF-Tokenon every mutation (double-submit). GETs are exempt.
Refresh flow: the frontend's HTTP client intercepts a 401, calls POST /auth/refresh, gets a new pair, retries the original request. Refresh tokens rotate — every successful refresh mints a new refresh and marks the old one used.
If an attacker steals your refresh token and races you, one of you refreshes first — that marks the token used. When the other tries, the server sees "already used" and revokes every refresh token in the user's family. One caveat: a replay landing within 5 seconds of the first is treated as a concurrent-tab race and is rejected without revoking the family, so detection covers replays from roughly five seconds onward. A used token is kept for 24 hours for this check; a replay after that is still refused, but no longer raises the alarm. A token revoked because an owner ended the session (sign-in method moved, account deactivated, password changed or reset) is not reuse: the refresh says the session ended.
CSRF compares header vs cookie on every mutation; mismatch → 403. Cross-origin requests can't read cookies, so only same-origin JS can produce matching pairs.
Admin disable evicts the session at the next refresh: disabling revokes the user's whole refresh-token family and the refresh endpoint refuses a disabled account, so the browser is signed out within one access-token lifetime (15 minutes at most). Delete and a forced password reset revoke the family the same way. There is currently no per-session list / per-device revoke surface in the UI — disable-the-user is the wholesale action.
Tuning:
jwt:
access_token_ttl: 15m
refresh_token_ttl: 168h # 7 days
Don't push access TTL above an hour — it defeats the quick-revocation pattern. Long refresh TTL is fine because rotation + reuse-detection bound the damage; pin shorter (e.g. 24 h) if compliance requires it.
Audit trail
Every auth-relevant action is captured in the audit log: login (success / failure), logout, role changes, admin-forced password resets and self-service password changes, OTP enrolment, disabling and recovery-code regeneration, refresh-token reuse detection and refused token refreshes (a successful refresh is not recorded: it continues a sign-in that is). An account auto-provisioned from LDAP is not recorded as a creation event — it appears only as a successful login. Failed-login bursts trigger a notification rule if you've configured one (Notifications).
Troubleshooting
"Forbidden" on an action you expected to work
Check your role for that project (not just org). The page header shows Project role: <role>. The action may require admin, but you're operator.
If your role in the project is limited to granted resources, the action also needs a grant on that resource with a high enough role — ask an admin of the project or of the resource to add you on its Access tab. A resource you have no grant on is shown as not found (Resource grants → troubleshooting).
"Account locked"
Too many failed logins. The backend applies a progressive lockout: 10 consecutive failures → 1 minute, 20 → 5 minutes, 30 → 15 minutes, 40 → 1 hour — values are server-side defaults and not currently exposed in the UI. Wait out the window or restart the user's session via Settings → Users → menu.
LDAP service bind fails with "invalid credentials"
Service DN or password is wrong, or the account is disabled in the directory. Test bind in the form isolates the issue.
"Code invalid" right after enrollment
Clock skew. The authenticator device must be on NTP; so must the backend host. Most phones are fine; desktop authenticators sometimes drift.
Bearer token 401
An access token lives 15 minutes — if it's older than that, refresh it (POST /api/v1/auth/refresh) and retry. Otherwise check the header itself: Authorization: Bearer <access_token> (note the space), and watch for copy-paste whitespace or a stray newline on the token.
403 missing CSRF cookie / missing X-CSRF-Token header / CSRF token mismatch
Missing or stale X-CSRF-Token. The frontend HTTP client sets it automatically; if you're calling the API directly from a script, prefer a Bearer access token (Authorization header, no CSRF) over cookie auth.
"I was suddenly logged out everywhere"
Refresh-reuse detection fired. Either a real compromise (check your other devices and the audit log) or a browser replaying an old refresh after sleep. Log in again; the event is audit-logged.
See also
Video tutorial
Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →