Users, groups and roles

Fadebox has two kinds of role. Global roles are platform-wide and live on the user account. Project roles apply inside one project and are granted through groups.

Global roles

TeamEnterprise

Free covers five people — only active accounts count, so deactivating one frees a seat. See Licensing.

Role	What it allows
user	The baseline every account has. On its own it grants no access to any project — you see only what a project role gives you.
template_admin	Create, edit and delete templates, start template test runs, import catalog entries, and administer catalog sources — global ones and any project's.
admin	Everything. Manages users, groups, identity providers and runtimes; creates and deletes projects; decides per project whether unsafe template configuration is allowed; and bypasses project roles — an admin has full authority in every project.

Admins assign global roles under Users. New accounts — including those auto-provisioned by an OIDC provider — start as user.

Project roles

Inside a project the roles are hierarchical: maintainer ⊃ editor ⊃ deployer ⊃ viewer. Holding maintainer implies everything editor may do, which implies everything deployer may do, which implies everything viewer may do.

	viewer	deployer	editor	maintainer
See the project, its environments and instances	●	●	●	●
Read repositories and registry entries	●	●	●	●
Create, deploy, stop and delete instances		●	●	●
Reset an instance — containers, network and volumes		●	●	●
Set values on services the environment opened to deployers		●	●	●
Remove images only this project's instances pulled and nothing wants		●	●	●
Read instance status and logs	●	●	●	●
Create, edit, clone and delete environments — services, waves, image tags, shared variables, files			●	●
Decide which services deployers may vary, and in what			●	●
Edit or delete a protected environment; protect and unprotect one				●
Manage git repositories and registry credentials				●
Manage members and API keys				●
Register, sync, switch and remove the project's own catalog sources				●
Import catalog entries into the project, and create, edit and delete the project's own templates				●

The line the two upper rungs draw is between doing the work and holding the keys. An editor composes: services, waves, image tags, shared variables, injected files, the blueprint flag. A maintainer also administers: who is in the project, its git and registry credentials, its catalog sources and templates, its API keys, its audit slice. Handing someone editor is therefore not a step towards handing them the credential store.

Creating a project is a global-admin act — you cannot be a member of a project that does not exist yet. The admin who creates one is seeded into its maintainers, so they can run it afterwards without using their global role.

What you can see follows the same line. The runtime list is narrowed to what you could actually deploy onto: a global admin sees every runtime, and everyone else sees those any of their own projects may use. A runtime row names a Docker daemon's address and the projects granted it, so an unnarrowed list would hand both to someone with no project at all. The daemon address's neighbours — the project allow-list and the ACME contact — are admin-only fields and come back empty for everyone else, on a row they can otherwise see.

Who gets which role

The roles are named after what they let you do, never after a job — the same four rungs have to serve a software team, a sales engineer's demo stacks and a trainer's labs. The translation:

The person	The role, and why
Platform or DevOps engineer running the installation	Global admin, and template_admin for whoever curates the catalog. Runtimes, identity providers, users and projects are platform-wide, so they are not a project role at all.
Tech lead or engineering manager who owns the project	maintainer. They decide who is in it, which repositories and registries it uses, and which of its environments are protected.
Developer	editor. "Run my branch against the rest" is an image tag, and adding a WireMock is a service — both are composing. They never see the member list or the credential store.
QA or tester	editor. The same, plus keeping named stacks like regression and uat configured.
Release manager	editor on the projects whose staging and uat they move — or maintainer, if those environments are protected and you have decided that moving them is an administrative act.
Support engineer reproducing a customer's bug	editor. Versions live on the environment, so "the same stack on 1.3.2" means cloning it and setting the tag on the copy, which is an editor's to do.
Sales engineer, pre-sales	editor. One demo stack per prospect, with the prospect's data image and branding.
Trainer or educator	editor. A lab per attendee, cloned from a base and varied per course.
Data or ML engineer	editor. A test bed pinned to one dataset or model version — again an image tag on an environment of their own.
Product owner, designer, salesperson	deployer. They bring the demo stack up, open its URL and show it; they never change what it is.
Stakeholder, reviewer	viewer.
CI pipeline deploying a per-pull-request instance	deployer. It deploys an environment somebody else defined.
A pipeline that writes definitions — pinning a build's image tags on the environment, or syncing environment definitions from a repository	editor. Writing a definition was never a deployer right, and maintainer would hand the pipeline your credentials and the ability to mint API keys.
Contractor or partner	Whichever of the above their work is, granted through a group scoped to the one project — see groups.
Compliance or security reviewer	Reading the audit log is not a role of its own: the project's own slice is a maintainer read, and the platform-wide log an admin one.

Two of these are worth stating as rules rather than rows. A pipeline gets the role its job needs and no more — deploying and defining are different jobs, and most pipelines only deploy. Nobody needs maintainer in order to build things; if someone is asking for it so they can change a stack, editor is the answer.

Protected environments

An environment can be marked protected, which narrows composing on that one environment back to a maintainer. It is what makes editor safe to hand out widely: everyone can build their own stacks while the shared staging stays in a few hands, instead of the whole team being kept off the composer to protect one environment.

An editor's writes to a protected environment — services, waves, image tags, shared variables, injected files, and deleting it — are refused with 403 and a message naming the flag. Raising and lowering the flag is a maintainer's act, in both directions.

Two things protection deliberately leaves alone. An editor may still clone a protected environment, and the clone is not protected — copying staging and retagging the copy is the daily path, and protection guards the original without withholding what is in it. And instances are untouched: deploying, stopping, extending and deleting instances of a protected environment stay a deployer right, because protection says who may change what the environment is, not whether it may run. See protected environments for the flag itself.

Groups are how project roles are granted

A group is a set of people. What a group grants is a set of edges of the form "every member of this group holds role in project". Users are never granted a project role directly — the grant always runs through a group, which is what makes an org-wide directory usable as the source of truth.

Membership comes from one of two places:

• Manual — an admin adds the user to the group.
• A claim mapping — an OIDC sign-in whose group claim carried a value the group maps.

Two ways to work with the same machinery

From the project — Project → Settings → Members. The table lists each person once, with every role they hold here and the group each role comes from, and a search box narrows it by username or email (since 1.1.2). A maintainer starts typing a name, email or group and picks from the matches, then chooses a role — no need to know a username or a group slug by heart. The search runs on the server and reaches accounts and groups that are not in the project yet, which is why it is a maintainer's to use rather than any member's. Behind the scenes the member is added to one of the project's project groups, and you never have to think about groups to run a project. Rows that came from a shared org group or from an SSO sync appear here read-only — revoking them belongs where they were granted.

Every project is born with one project group per role — acme-viewers, acme-deployers, acme-editors and acme-maintainers for a project acme — each granting exactly that role there. They appear under Access → Groups with a Project group badge. A project group is created with its project and deleted with it; it cannot be deleted by hand, and its one grant is fixed. Everything else works as for any group: an admin can add members to it directly, and can attach a claim mapping to it, which is the shortest route from a directory group to a project role (see below). Because the names belong to the project, creating a group of your own under a project-group name is refused, and creating a project whose group names a hand-made group already holds is refused with a message naming the group — rename or delete it first. On upgrade, projects that predate this gain their missing project groups at startup; a project whose name a hand-made group holds is skipped and logged.

From the platform — Access → Groups, as an admin. This is where you create groups that span projects (platform-team, qa), give them roles in several projects at once, and attach claim mappings — to those groups, or to a project group when a directory group maps onto one role in one project.

Passwords

A password the account holder did not choose is temporary. That covers the generated bootstrap password, an account an admin creates with a password typed into the form, and an admin resetting somebody's password. Until it is replaced, the account can reach exactly one thing — the password form — and everything else answers 403; the create-user form says as much, so an admin knows what they are handing over.

Replacing it needs the current password, and clearing the flag frees the session already open, so nobody has to sign in twice. A user who cannot produce the current password can still sign out from that screen rather than being stuck on a dead session.

Changing your own password lives at Settings → Account. It appears only for accounts that have a password here at all: a federated user's credentials belong to their identity provider, and a service account has none, so both see a sentence saying where the credential lives instead of a form that could not work.

An account locked this way also cannot authenticate with an API key, and cannot create one — which makes forcing a reset a way to contain an account without deleting it.

Sessions

A signed-in session expires when it is idle for thirty minutes, whichever way it was signed in. Any request slides the window forward, so somebody working is never interrupted, while a tab left open overnight is signed out.

• Form sign-in. The session lives in an encrypted cookie, and the browser stops presenting it at exactly the moment the server stops accepting it — so an idle tab comes back to the sign-in page rather than to a 401 on a cookie the server had already written off.
• Single sign-on. The same window, held by renewing with the provider behind the scenes. The session is no longer capped at the life-span of the provider's ID token, which is what used to sign everyone out every few minutes behind a provider issuing the customary five-minute one. Renewal happens on a request rather than on a clock, so the window measured from a user's last request runs from thirty minutes to thirty minutes plus one token life-span — an approximation of the form side, not a match.
• The identity provider has the last word. Its own policy — Keycloak's SSO Session Idle, for instance — is a ceiling Fadebox cannot raise: once the provider stops honouring the renewal, the session is over. That dial belongs at the provider.

"Idle" means no HTTP request, not nobody at the keyboard. A page that polls — an environment page watching instances come up — renews the session for as long as it is open.

The form side's window is configurable; the SSO side is fixed at thirty minutes, so an installation that lengthens the form window lengthens only that one.

An API key is not a session and never idles out. It lives until it expires or is revoked.

Mapping identity-provider groups

Enterprise

A claim mapping puts everyone whose token carries a given value into a Fadebox group. Attaching claim mappings is an Enterprise feature; everything else on this page — groups, project roles, manual membership — is available on every tier.

A mapping always names which provider asserted the value. This matters: a bare claim value would be global, so engineering emitted by a contractor's directory would land in the same group as engineering from your corporate one — and that group carries project role grants. Scoping the match to the provider the token was verified against means an outside directory administrator cannot mint membership in your groups.

A group with no claim mappings can only be filled by hand. A project group takes a mapping like any other group: map your directory's acme-developers onto acme-deployers and its members hold deployer in acme on their next sign-in, with nothing else to set up. A directory group that should hold roles in several projects maps onto a regular group with a grant per project instead — a claim value maps to exactly one group. The invariant throughout: a claim can only place you in a group an admin defined, and only an admin decides what that group grants.

note

Group membership from a sign-in is recomputed on each request of a signed-in SSO user, so removing someone from a directory group takes effect on their next request — you do not have to wait for a session to expire.

Service accounts

TeamEnterprise

Free covers three service accounts, an allowance separate from the one for people. See Licensing.

CI pipelines authenticate as service accounts: accounts with roles and memberships like anyone else, but with no password and no interactive sign-in. They hold API keys instead.

A key is not only a service-account thing: you can issue one for your own account too, and it carries exactly your roles and projects. Only you can create or revoke it — see Your own keys.