Documentation

Users, roles and SSO

Roles, password and two-factor policy, single sign-on with OpenID Connect, SCIM provisioning and the break-glass account.

Roles

Every user has one of three roles. The server enforces them on every request; the dashboard only hides what a role can't use.

Role	Can
Admin	Everything in the organisation: users, single sign-on, system settings, enrolment-token rotation, agent update policy and threat-intelligence installs, plus everything a Security Engineer can do.
Security Engineer	Launch and delete scans, triage and retest findings, edit assets, approve, revoke and update agents, run compliance baselines and dispatch remediation scripts.
Auditor	Read-only access to everything, plus reading and exporting the audit log.

Managing users

Admins manage accounts under Settings → Users. A new user gets a temporary password and must choose their own at first sign-in. For each user an Admin can:

Reset password: sets a new temporary password and signs the user out everywhere;
Reset 2FA: for a lost phone and lost recovery codes (Admins can't reset their own);
Disable or Enable: a disabled user is signed out at once and can't sign in by any route; their history is kept;
Sign out: ends all of the user's sessions.

Each email address can belong to one organisation only.

Passwords and sessions

Rule	Detail	Set under
Password strength	At least 12 characters, and not the email address. No forced mix of character types.	Fixed
Password expiry	Default 90 days. After that the user can only change their password.	Settings → System
Account lockout	Default 5 failed attempts (passwords and two-factor codes), then locked for 15 minutes.	Settings → System
Session length	Default 7 days from sign-in, however active. Sessions are never silently extended.	Settings → System

Changing your password, turning two-factor authentication on or off, or Sign out everywhere (under Settings → Profile) ends your other sessions.

Holistra supports authenticator-app codes (TOTP) such as Microsoft Authenticator, Google Authenticator or 1Password. To set it up, open Settings → Profile, enter your password, scan the QR code and confirm with a code. You then get 10 one-time recovery codes, shown once: store them somewhere safe.

Under Settings → System, Admins can require two-factor authentication for Admins or for everyone. Users it applies to who haven't set it up can only reach the setup page until they do. Two-factor authentication covers password sign-in; people who sign in through single sign-on use their identity provider's own MFA.

Single sign-on (OpenID Connect)

Each organisation can connect one OpenID Connect identity provider, such as Microsoft Entra ID or Okta. SAML-only providers (for example ADFS without OIDC) are not supported yet. Configure it under Settings → Single sign-on.

Verify your email domain. Add your domain; Holistra shows a DNS TXT record to publish. Once it is published, click Verify. Only verified domains are sent to your identity provider, so nobody else can claim your domain.
Register Holistra at your identity provider as a web application using the authorization-code flow, with scopes openid email profile and the redirect URI shown on the Single sign-on page. It has this form:

https://<your-server>/api/auth/sso/callback

Enter the provider's details: issuer URL (for Entra ID, https://login.microsoftonline.com/<tenant-id>/v2.0), client ID and, if it has one, the client secret. The secret is stored encrypted and never shown again.
Choose how roles are assigned. Set a default role for new users (Auditor unless you change it), and optionally map your provider's groups to roles. With mappings, the groups decide the role at every sign-in, and the most privileged match wins.
Decide who can sign in. Turn on Create accounts on first sign-in to let anyone in your verified domains in with the default role, or leave it off so only existing accounts can use SSO.
Test, then turn it on. People with an email in your domain then see Continue with SSO on the sign-in page.

Require SSO stops password sign-in for everyone except Admins, so that an Admin can still get in if the provider is down. Users are matched to their account by the provider's issuer and subject, not by email alone, so a provider can't take over an account by asserting someone's address.

Provisioning with SCIM

SCIM 2.0 lets your identity provider create and deactivate Holistra accounts as people join and leave. It syncs users only; roles come from the group mapping at SSO sign-in.

Mark a break-glass account (below). The SCIM token can't be generated without one.
Under Settings → Single sign-on → Provisioning, generate a token. It is shown once; generating another revokes the old one.
In your identity provider, set the base URL shown there (https://<your-server>/api/scim/v2), the token as the secret, and userName to the user's email.

Provisioned emails must be in one of your verified domains. Removing a person in your provider deactivates their account rather than deleting it, so their audit history stays; it can be re-enabled.

The break-glass account

When sign-in depends on your identity provider, an outage or misconfiguration there could lock every Admin out. A break-glass account is a local Admin account the provider can't touch:

it always signs in with its password, and two-factor authentication is mandatory for it;
SCIM can't deactivate, delete or rename it, and it can't be disabled while marked;
every sign-in with it is recorded in the audit log.

Another Admin marks it on Settings → Users. SCIM and Require SSO can only be turned on while one exists.

Looking after the break-glass account

Give it an address your identity provider doesn't manage, keep its password and recovery codes in a vault with a named custodian, use it only when SSO has failed, and review every use in the audit log.

Audit log

Settings → Audit (Admins and Auditors) records every change made by a signed-in user: who, when, and which action. It can be exported as CSV, and Verify integrity checks the log's hash chain for edited or missing entries. See also Reports and exports.