Authentication

The self-hosted SCF Controls Platform authenticates with the master API_KEY you set in .env — no external identity provider is required. Optional sign-in methods (OIDC single sign-on, Google Sign-In) can be enabled on top when your team needs individual user accounts.

Authentication methods

Method	Default	When to use
API key (API_KEY + OSS_SINGLE_TENANT=1)	✅ On	Single-tenant self-hosted installs — the quick-start path
OIDC single sign-on	Off	Team installs that want individual accounts via the bundled Keycloak or your own IdP (Okta, Entra ID, Auth0, Google Workspace)
Google Sign-In	Off	Installs that prefer direct Google OAuth without an OIDC broker

API-key authentication (default)

Out of the box (GOOGLE_AUTH_ENABLED=false, OSS_SINGLE_TENANT=1):

• You set a master API_KEY in .env before first start (openssl rand -hex 32), and set VITE_API_KEY to the same value — that is the copy the web app uses, baked into the frontend at build time. Installs made with scripts/install.sh skip both steps: the installer generates API_KEY into the secrets directory and the frontend build reads it from there.
• The web app authenticates to the backend with that key; in single-tenant mode the key acts as the admin of your single organisation, so there is no sign-in screen to configure.
• The same key authorises direct REST API calls — send it as a Bearer token.

Rotating the key

Because VITE_API_KEY is a build-time value, changing the key means updating both variables in .env and rebuilding the frontend: docker compose up -d --build frontend. If the two values ever differ, the app loads but every request returns 401 (empty pages).

Treat the master key like a root credential: store it in a password manager, rotate it if it may have leaked, and don’t embed it in scripts you share.

Single-tenant guard

The backend refuses to start in single-tenant mode if it detects more than one organisation or human member — the mode is safe by construction for genuine single-tenant deploys. For multi-user installs, enable one of the sign-in methods below.

What the master key can do

In single-tenant mode the master key administers your single organisation, and the REST API treats it as a platform administrator:

Area	Master key over the REST API	Shown in the web app
Organisation data — controls, evidence, risks, vendors	Yes	Yes
Organisation settings, members, API keys	Yes	Yes
Platform administration — catalog upgrade, tenant reconciliation	Yes	No — see below
Consultant Portal	Yes, once a consultant profile exists	Only with a profile

Platform administration is API-only in API-key mode

When no sign-in method is enabled (GOOGLE_AUTH_ENABLED=false and VITE_OIDC_ENABLED=false), the web app runs in API-key mode and deliberately hides the Platform section. Those screens perform destructive, cross-organisation operations, so they require a real signed-in session rather than a shared static key.

The endpoints themselves remain reachable with the master key, so automation and CLI workflows are unaffected. To drive catalog upgrades or tenant reconciliation from the UI, enable OIDC sign-in or Google Sign-In and grant your account platform admin: docker compose exec backend python -m cli.admin grant-admin --email you@example.com

Platform admin alone is not enough to see a workspace: a signed-in account also needs an organisation membership, or the app sits on the loading spinner with no error. See After first login: assign an organization.

Outside single-tenant mode the same key is an ordinary automation credential — the platform-admin grant is tied to the single-tenant guard, not to the key itself, so adding a second organisation withdraws it automatically. The guard is evaluated at startup, so restart the backend after changing the number of organisations or members.

Consultant Portal is separate

The Consultant Portal is gated on a consultant profile rather than on an admin role, so it stays hidden until one exists. Register from the app, or run: docker compose exec backend python -m cli.admin grant-consultant --email you@example.com

SSO / OIDC sign-in (optional)

Self-hosted deployments can authenticate through OIDC single sign-on — either the bundled Keycloak (docker compose --profile idp up -d) or your own provider. It is off by default. See Identity Provider for setup.

When OIDC is enabled, the sign-in button redirects to your identity provider:

1. Click Sign in
2. You’re redirected to your identity provider (the bundled Keycloak, or your own IdP)
3. Enter your credentials there — the exchange uses the authorization code flow with PKCE
4. You’re redirected back to the platform and signed in

First login for the bundled admin

The bootstrapped admin (BOOTSTRAP_ADMIN_EMAIL) signs in first with a one-time temporary password, and Keycloak forces a password reset plus a prompt to complete first/last name before landing in the app. See Identity Provider → Setup.

Google Sign-In (optional)

To let users sign in with Google accounts directly, set in .env:

GOOGLE_AUTH_ENABLED=true
VITE_GOOGLE_AUTH_ENABLED=true
GOOGLE_CLIENT_ID=<your-oauth-client-id>
VITE_GOOGLE_CLIENT_ID=<your-oauth-client-id>

You provide your own Google OAuth client (created in your Google Cloud console). When enabled, users click Sign in with Google and grant access to their basic profile and email. The platform receives only email address, display name, and profile picture — never contacts, calendar, email content, or files.

User roles

Access level depends on the assigned role:

Role	Access
Admin	Full access: manage users, configure frameworks, view all data
User	Standard access: view and edit controls, evidence, and risks
Viewer	Read-only access: view controls and reports without editing

Your organisation’s administrator assigns roles via User Management.

Session management

• Sessions remain active while you’re using the platform; after extended inactivity you’ll be prompted to sign in again (when a sign-in method is enabled).
• To sign out, click your profile avatar in the top-right corner and select Sign out.
• Always sign out on shared computers.

Troubleshooting

Sign-in popup closes immediately or is blocked (Google Sign-In)

Allow popups for the site (popup-blocker icon in the address bar), then try again. If the button does nothing, temporarily disable ad blockers or try an incognito window.

“Account not authorised” error

The account has not been provisioned. An administrator needs to invite the user — see User Management.

What that invite has to cover depends on the deployment. On the bundled Keycloak the invite creates the sign-in account as well, so inviting the user is enough. On a bring-your-own OIDC or Google install the platform does not create accounts in the identity provider: the administrator has to create the account there and invite the user here. The badge on the pending invitation says which case applies — see User provisioning.

Signed in but no data appears

The account may not be assigned to an organisation yet. Verify the account setup with your administrator, then sign out and back in.

For deployment-level authentication problems (wrong API_KEY, single-tenant guard refusing to start), see Troubleshooting.

Related guides

• Deployment — install, first sign-in and the installer options
• Identity Provider — enabling OIDC SSO
• User Management — managing team members and roles