Users, roles and access

This page covers who can sign in to Spitfire, who can see and run what, and how that is managed: users, roles, groups, workspaces, SSO (OIDC and LDAP), forgotten passwords, API tokens, the audit log, the mobile app and gate, and system events.

#What it is for

• You open a separate account for each member of your team; whatever someone does is written to the audit log under their name.
• With Groups you decide which tests are visible to whom and who may run them; editing tests stays with admins.
• With SSO users sign in with their corporate identity; roles and group memberships can come from your identity provider's groups.
• API tokens let CI pipelines run tests on your behalf.

#When to use it

• After installation and the license, when adding the team.
• When a user cannot see or run a test.
• When your organisation wants central identity management (Entra ID, Okta, Google, Keycloak, Active Directory…).
• When setting up a CI pipeline (API token).
• When someone forgot their password.

#Roles

In an installation with a single workspace (every installation not on the Agency plan) "admin" means installation admin; the workspace admin distinction does not show.

#Adding a user

The Users page and the New user dialog: Email, Name, Role, Sign-in method, Password and the "They choose their own password at the first sign-in" option

1. Open Infrastructure → Users in the menu (installation admins only).
2. Click Add user at the top right; the New user dialog opens.
3. Enter Email and Name.
4. Choose a Role:
   • User — sees only tests shared with its groups; runs those marked "may run"
   • Admin — creates, edits and runs tests; manages everything
5. Choose the Sign-in method: Password (a Spitfire password), OIDC or LDAP (accounts that sign in with SSO; they have no Spitfire password, and the first sign-in binds the account to the provider identity or directory entry).
6. For a password account, type a Password (at least 8 characters). To let the user pick their own password at the first sign-in, tick They choose their own password at the first sign-in.
7. Save. Pass the password to the user over a safe channel.
8. If the role is user, add them to a group (Groups); otherwise they see no tests.

Users are not deleted; edit the account of someone who left and tick Disabled. A disabled account cannot sign in, its API tokens stop working, and it does not count towards the license's user limit. Changing the password signs the user out of all open sessions.

In the list, the Sign-in column shows each account's sign-in method and the Groups column its groups ("all tests" for admins); hovering a row shows the last sign-in.

#Groups

Accounts with the user role only see tests assigned to their groups.

The Groups page: the Members list in the New group dialog and the Visible and May run boxes next to tests

1. Open Infrastructure → Groups in the menu.
2. Click New group and type the group's name.
3. Pick users from the Members list (search with Filter). Adding admins changes nothing; they already see every test.
4. In the Tests list, for each test:
   • Visible — members see the test, its runs and results.
   • May run — they can also start and stop runs (implies Visible).
5. Save. The list shows "N visible · M may run" for each group.

Deleting a group deletes neither users nor tests; members no longer see the group's tests (unless another group shares them). With Sync group memberships on in SSO, users join the Spitfire groups named like their provider groups automatically.

#Workspaces

On the Agency plan one installation can hold several client workspaces. Tests, connections and their secrets, data files, environments, schedules, synthetic monitors, mock services, notification channels, groups, budgets and results belong to exactly one workspace and are invisible across workspaces. Runners and installation settings (SSO, e-mail, OTLP, license, retention, updates) are shared by the whole installation.

The Workspaces page: the New workspace form and the list with the Default and demo workspaces

1. Open Infrastructure → Workspaces in the menu (shown only when the license allows several workspaces).
2. Type the name under New workspace (e.g. {workspace:demo}) and click Create.
3. Click Settings on the workspace's row. On the Members card, add people who have an account by their e-mail and give them a role: Workspace admin or User. The installation admin creates accounts on the Users page.
4. Optionally, in the Report branding section of the same place, set a company name, a logo (PNG or JPEG, at most 512 KB) and an accent colour; they replace the Spitfire mark in PDF/HTML reports.
5. Switch between workspaces with the Workspace switcher in the top bar. The choice is remembered per user.

Archive makes an unused workspace read-only (nothing is deleted; Restore brings it back). The Default workspace cannot be archived. If the license allows fewer workspaces, the extra ones are not deleted but become read-only.

#SSO

The Single sign-on page (installation admin; Infrastructure → Single sign-on) lets users sign in with their corporate identity. It is part of the paid plans.

The Single sign-on page: the Password sign-in option and the Redirect URI in the General card, the OpenID Connect and LDAP / Active Directory cards below

#General settings

• Password sign-in: Everyone or Admins only. With admins only, everyone else signs in with SSO; an admin password stays as break-glass access.
• Redirect URI: <Spitfire's public address>/api/v1/auth/oidc/callback. Add it to the application registration at your identity provider.

#OpenID Connect

1. At your identity provider (Entra ID, Okta, Google, Keycloak…) create an application (web, authorization code) and add the Redirect URI above.
2. On the OpenID Connect card tick On.
3. Enter the Issuer URL (discovery appends /.well-known/openid-configuration) and check it with Test discovery; "Provider found." must appear.
4. Enter the Client ID and, for a confidential client, the Client secret.
5. The Button name shows on the sign-in page as "Sign in with …".
6. If needed, set Scopes, the Groups claim and Allowed e-mail domains (empty allows any domain).
7. Set the group rules (below) and Save.

Spitfire uses PKCE and a nonce and verifies the ID token's signature with the provider's keys. In Entra ID, group object ids come instead of group names.

Once saved, the sign-in page shows a "Sign in with …" button named after the Button name:

ScreenshotThe sign-in page: the identity provider's "Sign in with …" button above the e-mail and password form

#LDAP / Active Directory

The LDAP / Active Directory card of the Single sign-on page: Server URL, StartTLS, service account, base DN, user filter, attributes and the Try button

1. On the LDAP / Active Directory card tick On.
2. Server URL (ldap:// or ldaps://); with ldap://, StartTLS is recommended. Don't verify the certificate is for test setups only.
3. Service account (bind DN) and Service account password (empty searches anonymously).
4. User search base (base DN) and User filter ({login} is replaced by what was typed).
5. Attributes and group search: E-mail, Name, Group attribute; for directories without memberOf, Group search base and Group filter.
6. Before saving, use Try to bind as a user and see what Spitfire would do ("May sign in · role: …").
7. Save.

Users type their directory user name (or e-mail) and directory password in the sign-in form; the password is never stored.

#Group rules (for both)

• Groups that may sign in — empty lets in everyone the provider authenticates.
• Admin groups — members are admins, everyone else a user; updated at every sign-in. Empty leaves roles to Spitfire.
• Create the account on first sign-in — when off, an admin opens the account first (Users → Sign-in method).
• Sync group memberships — the user joins the Spitfire groups named like their provider groups and leaves them when that stops; memberships added by hand are left alone.

#Forgotten passwords

The user's side:

The Forgot password page: the e-mail field and the Send button

1. On the sign-in page click Forgot password, type your e-mail address and press Send. The answer is the same for every address; it never says whether an account exists.
2. If e-mail is configured on the installation (Integrations → E-mail (SMTP) and Spitfire's public address), a one-time link valid for 30 minutes arrives. The link lets you choose a new password; every session of the account ends.
3. Without e-mail, the request goes to the administrator.

The administrator's side (no e-mail):

1. On the Users page the account that asked shows the asks for a password reset tag.
2. Edit the account, type a temporary password, keep They choose their own password at the first sign-in ticked and Save. (To close the request without action: Close the request.)
3. Pass the temporary password on; at the first sign-in the user picks their own password before anything else.

Users change their own password from the user menu with Change password. SSO accounts have no Spitfire password.

If nobody can sign in (the only admin forgot their password), on the controller's server:

cd ~/spitfire && docker compose -p spitfire -f deploy/docker/docker-compose.yml exec controller spitfire-controller reset-password admin@example.com
kubectl -n spitfire exec -it deploy/spitfire-controller -- spitfire-controller reset-password admin@example.com

It asks for the new password twice; --generate prints a random password (changed at the next sign-in), --enable also re-enables a disabled account. The action is written to the audit log.

#Managing API tokens

Your CI pipelines (GitHub Actions, GitLab CI, Jenkins…) use an API token to list, validate, run and stop tests and read results on your behalf.

The API tokens page and the New API token dialog: name, Expires choice and the token shown once

1. Open API tokens from the user menu at the top right.
2. Click Create token; in the New API token dialog give a name (e.g. "GitHub Actions — shop") and choose Expires (30, 90, 365 days or Never).
3. In an installation with several workspaces the token is bound to the workspace it was created in; an installation admin can create a token that works in every workspace with For every workspace (the CI request picks one with --workspace).
4. The token is shown only now. Copy it into your CI's secret variable (SPITFIRE_TOKEN) (GitHub: Settings → Secrets and variables → Actions; GitLab: Settings → CI/CD → Variables, Masked), then Copied, close.

On every call the token has its owner's current role and groups; a token cannot manage tokens, users, tests or settings. If the account is disabled, its tokens stop working too. A user can have at most 50 active tokens. Revoke invalidates a token at once (pipelines using it get 401; it cannot be undone). Admins see everyone's tokens with All users' tokens. Pipeline examples: CI/CD.

#Audit log

The Audit log (Infrastructure → Audit log, admin) answers who did what, and when: sign-ins, tests, runs, confirmed data writes, users, groups, connections, runners and registration keys, the license… Entries can only be added — never changed or deleted (only the daily pass of the Data retention setting deletes rows older than 30 days, and that deletion is audited too).

The Audit log page: From, To, Action and Search filters, the Download CSV button and the list of entries

1. Choose From / To dates and the Action type, or type a user, target or IP in Search.
2. Filter; to reset, Clear filters.
3. Download CSV to export it as evidence (the export is logged too).

The audit log is kept on every plan, but reading and exporting it is in the paid plans. In an installation with several workspaces the log is per workspace; the installation admin can choose to see every workspace's entries.

#Mobile app and gate

The Spitfire mobile app (Android, iOS) brings run events to the phone as notifications; it also lets you abort a run from the phone and confirm a data-writing run with a biometric check. A user is only told about tests they can see.

Installation admin, once:

The Mobile & Gate page: Turn on mobile notifications, the two delivery modes and, in Gate mode, the Gate card

1. Open Infrastructure → Mobile & Gate and tick Turn on mobile notifications.
2. Answer How do notifications leave the controller?:
   • Straight from the controller (it has internet access) — nothing else to install; follows HTTPS_PROXY.
   • Through a gate (the controller has no internet access) — a small service (the gate) is installed on a machine with internet access; it only connects outwards.
3. Leave Notification server (relay) empty (Spitfire's server is used) and Save.
4. If you chose the gate, click Create gate token, give it a name (e.g. dmz-gate) and run the Linux (systemd service) or Docker command from the dialog on the gate machine. That machine must reach the controller and relay.spitfire.tr:443. The token is shown only once. When the gate connects, the card shows Connected.

The New gate dialog: the gate token shown once with the Linux (systemd service) and Docker install commands

Every user:

1. Install the Spitfire app on the phone.
2. In the app, sign in with Spitfire's address and your own account (as in the web UI) and allow notifications. This registers the phone with your account.
3. Choose in the app which events you want (by default every event except run started and finished).

Every notification is encrypted with a key only the receiving phone can open; the gate, the notification server and Google/Apple cannot see the test name or the result. The line under the card shows how many phones and users are registered and how many notifications are waiting.

#System events and support bundle

The System events page (installation admin; Infrastructure → System events) lists what the controller noticed: panics, server errors (5xx), runners connecting and dropping, failed runs, the license, the update check, the database, SSO/LDAP and notification channel failures. Events are kept 30 days, at most 20,000. Filter with Level and Source; paste the Error code (request id) you saw in the UI into the search box to find that request's event.

The System events page: Level and Source filters, the event list and the Download support bundle button

Download support bundle first shows the files in the bundle and their sizes, then gives you a zip. Spitfire never sends this bundle anywhere; look inside and, if you choose to, send it to support yourself.

The Support bundle dialog: the files in the bundle and their sizes, what is left out, and the Download button

Details, and getting a bundle from the command line when the UI does not open: Troubleshooting.

#Common problems

Symptom: A user signs in but sees "No tests are shared with you yet". Cause: The account with the user role is in no group, or its group has no tests. Fix: On the Groups page add them to a group and mark tests Visible.

Symptom: The user sees the test, but "view only" instead of Run. Cause: The group made the test Visible only. Fix: Edit the group and mark the test May run.

Symptom: Save shows "Another user cannot be enabled (user 2); the free edition allows up to 1." Cause: The license's user limit is reached. Fix: Move to a paid plan or set an unused account to Disabled.

Symptom: SSO sign-in says "This e-mail belongs to a password account; an admin can switch it to single sign-on." Cause: A Spitfire password account with the same e-mail exists. Fix: Users → edit the account → set Sign-in method to OIDC or LDAP.

Symptom: SSO sign-in says "There is no Spitfire account for this user; ask an admin to create it." Cause: Create the account on first sign-in is off. Fix: Turn it on, or create the account beforehand on the Users page with the right sign-in method.

Symptom: SSO sign-in says "You are not in a group allowed to sign in." or "This e-mail domain may not sign in." Cause: The Groups that may sign in or Allowed e-mail domains rule. Fix: Add the user to the right group at the provider, or widen the rule. In Entra ID, make sure you entered group object ids.

Symptom: SSO sign-in says "The identity provider could not be reached." Cause: The controller cannot reach the provider (proxy, DNS, firewall). Fix: Check with Test discovery; behind a proxy, add the provider's name to NO_PROXY when it is on your internal network (Installation → Proxy).

Symptom: The SSO page says "Single sign-on (OIDC, LDAP) is part of the paid plans (Growth and above)." Cause: The installation is on the free limits; the settings are kept but inactive. Fix: Install a paid license: License.

Symptom: "Too many sign-in attempts. Try again in N s." Cause: The sign-in throttle (30 attempts at once per address; 10 wrong passwords per account). Fix: Wait. When many users sit behind one NAT, SPITFIRE_SIGNIN_BURST can be raised.

Symptom: CI gets "Too many active API tokens". Cause: The user has 50 active tokens. Fix: Revoke unused tokens.

Symptom: Mobile notifications don't arrive; the gate card says "N notifications are waiting for a gate to connect." Cause: Gate mode is chosen but no gate is connected. Fix: Install the gate, or check that its machine reaches the controller and relay.spitfire.tr:443.

#Related pages

• Getting started
• License
• CI/CD
• Scheduling and monitoring
• Troubleshooting