Authentication & SSO

The management panel signs users in with email and password by default. An administrator can additionally enable single sign-on (SSO) against your own identity provider — OpenID Connect (OIDC), SAML 2.0, or both. SSO is optional and additive: until it is configured the login page is unchanged, the SSO endpoints are not exposed, and password sign-in always keeps working alongside it.

Single sign-on never grants administrator access. Accounts are linked or created only by the identity provider's verified email address, and every SSO user is a plain customer account until an administrator assigns them more (see Roles (RBAC) below).

OpenID Connect (OIDC)

OIDC works with any standards-compliant provider — for example Google Workspace, Microsoft Entra ID, Okta, or Keycloak. The panel discovers the provider's endpoints automatically from its OIDC discovery document ({issuer}/.well-known/openid-configuration), so you supply only a handful of values.

Turn it on

1. In your identity provider, register the panel as an OIDC confidential client (web application). Note its client ID and client secret, and add the panel's callback URL — path /auth/sso/callback, shown in full on the settings page — as an allowed redirect URI.
2. As a full administrator, open SSO settings (/admin/sso-settings) in the panel's System area.
3. Enter the provider details described below, tick Enable SSO sign-in, and save.

The fields on the settings page:

The "Sign in with …" button appears on the login page only once SSO is enabled and the issuer, client ID, and client secret are all present — a partial configuration never shows a broken button.

What a sign-in looks like

A user clicks the SSO button, authenticates at your provider, and is returned to the panel, which then:

• requires the provider to assert a verified email — a missing or unverified email claim is refused;
• cross-checks the returned ID token's issuer and audience when one is present, and confirms the discovery document's issuer matches the one you configured;
• links the identity to an existing account with that verified email, or creates a new customer account if none exists.

The authorization-code exchange happens server-to-server over TLS, and the OAuth state parameter (CSRF protection) is managed for you. If SSO is momentarily unavailable, the user is returned to the login page and can sign in with a password.

SAML 2.0

SAML 2.0 is an independent, parallel option to OIDC — configure either, both, or neither. It works with providers such as Microsoft Entra ID, Okta, OneLogin, Google Workspace, Shibboleth, and ADFS.

Turn it on

1. As a full administrator, open SAML settings (/admin/saml-settings) in the panel's System area. The page shows this panel's service-provider (SP) details: the SP Entity ID, the Assertion Consumer Service (ACS) URL (path /auth/saml/acs), and an SP metadata URL (path /auth/saml/metadata).
2. Register the panel as a service provider at your identity provider: use the ACS URL as the SP's Assertion Consumer Service (HTTP-POST binding). Many providers can import all of the SP details automatically from the metadata URL.
3. Collect your provider's IdP details, enter them below, tick Enable SAML sign-in, and save.

The fields on the settings page:

The SAML button appears on the login page only once SAML is enabled and the IdP entity ID, SSO URL, and signing certificate are all present.

What a sign-in looks like

From the login page a user clicks the SAML button and is redirected to your provider (SP-initiated). Provider-initiated (IdP-initiated) sign-in is also supported, so a user can also start from your provider's app portal. Either way the provider posts a signed SAML response to the ACS URL, and the panel links or creates the account by the asserted email — taken from the NameID or a standard email attribute.

Every response is validated strictly before anyone is signed in:

• the assertion must carry a valid XML signature over your configured IdP certificate — an unsigned or altered assertion is rejected;
• the time conditions (not-before / not-on-or-after) must be current;
• the assertion must be audience-restricted to this panel — a response carrying no audience restriction is refused, not accepted;
• each assertion is single-use — a replayed response is rejected.

Roles (RBAC)

Beyond the customer / administrator split, the panel supports optional finer-grained operator roles. Every account has a role that, when left unset, derives from whether it is an administrator — so existing accounts behave exactly as before and no migration is needed.

A full administrator assigns roles from a user's page under Users (/admin/users):

Roles are additive and only ever restrict access — an operator role can never exceed what a full administrator already has. The System area (user management, keys, panel settings, and the SSO/SAML configuration itself) stays full-administrator-only. Assigning a role sets the account's administrator flag in code; you cannot change your own role or remove the last full administrator.

Because SSO and SAML always create plain customer accounts, granting someone operator access is a deliberate, separate step an administrator takes here — it never happens automatically at sign-in.

Security notes

• Off by default, and safe when off. With nothing configured the login page is unchanged, password sign-in is untouched, and the SSO and SAML endpoints return 404 — they add no surface area until an administrator turns them on.
• SSO never elevates privilege. The administrator flag and role are set only inside the panel (in code or by an administrator), never from an OIDC or SAML response. A first-time SSO user is always a customer.
• Linked strictly by verified email. If an account already exists for the provider's verified email, the SSO identity is linked to it — no duplicate account, and no change to its existing privileges; otherwise a new customer account is created.
• Secrets are protected. The OIDC client secret is encrypted at rest and is never displayed again after saving. The SAML IdP certificate is public by nature and is stored as entered.
• OIDC checks. A verified-email claim is required; the discovery document's issuer must match the one you configured; the ID token's issuer and audience are cross-checked when one is returned; and the OAuth state (CSRF) is enforced during the exchange.
• SAML checks. Responses are validated in strict mode: assertion signature, time window, audience restriction, and single-use replay protection. The ACS endpoint is exempt from the panel's CSRF token — an identity provider cannot carry it on a cross-site POST — and that exemption is scoped to only that one route; the signed, single-use, audience-bound assertion is the integrity guard.
• Password sign-in remains. SSO is always additive to password login, so a brief SSO outage never locks anyone out.

Next steps

• TLS/SSL & License Operations — node certificates and license activation.
• Licensing — plans, enforcement, and offline use.