Authentication¶
Configure authentication methods for WitFoo Analytics. Open Settings (the gear icon in the page header) > General Settings > Authentication. Requires the settings:manage permission.
SAML and LDAP settings are saved and read only on this page. The general system settings API (PUT /api/v1/settings) neither saves nor returns them.
Encryption Required
LDAP bind passwords and SAML private keys are encrypted at rest with XChaCha20-Poly1305, under a per-organization key derived from AUTH_CONFIG_ENCRYPTION_KEY. Values written by releases before the cipher change were sealed with AES-256-GCM and are still read. On a WFA-managed appliance WFA supplies the key; do not edit it. On Docker Compose or a standalone stack the key is required from 1.2.0: see Upgrading to 1.2.0.
Local Authentication¶
Default method using username/password stored in Cassandra with bcrypt hashing. No external dependencies required.
- Users are created and managed within the WitFoo Admin panel
- Passwords must meet minimum complexity requirements
- Supports password reset via admin action
LDAP¶
Connect to an LDAP directory (Active Directory, OpenLDAP) for centralized authentication.
| Setting | Description |
|---|---|
| Server URL | LDAP server address (ldap:// or ldaps://) |
| Bind DN | Distinguished name for LDAP queries |
| Bind Password | Password for the bind account |
| Search Base | Base DN for user searches |
| User Filter | LDAP filter for matching users (e.g., (uid=%s)) |
Secure LDAP
Use ldaps:// with a valid TLS certificate for production deployments. WitFoo uses ldap.DialURL() which supports TLS configuration.
SAML¶
SAML 2.0 single sign-on integration for enterprise identity providers.
Core Settings¶
| Setting | Description |
|---|---|
| Entity ID | Service provider entity ID (unique identifier for WitFoo) |
| SSO URL | Identity provider SSO endpoint |
| SLO URL | Identity provider Single Logout endpoint (optional) |
| Certificate | IdP X.509 certificate for signature validation |
| SP Private Key | Service provider private key (for signed requests) |
| SP Certificate | Service provider certificate (for signed requests) |
| Attribute Mapping | Map SAML attributes to WitFoo user fields (email, name, role) |
SAML Provider Wizard¶
The SAML configuration wizard guides administrators through a 7-step setup process with provider-specific presets that pre-populate common settings.
Supported Providers¶
| Provider | Pre-populated Settings |
|---|---|
| Azure AD / Entra ID | Entity ID format, claim names (http://schemas.xmlsoap.org/...), logout URL pattern |
| Okta | SSO URL pattern, attribute mapping (firstName, lastName, email), name ID format |
| OneLogin | Issuer URL format, SLO endpoint, certificate location guidance |
| PingIdentity | Connection URL pattern, attribute contract mappings |
| Manual | No defaults -- full manual configuration for any SAML 2.0 IdP |
Each provider preset reduces configuration to entering your organization-specific values (tenant ID, app ID, etc.) while the wizard handles protocol-level defaults.
Wizard Steps¶
- Select Provider -- Choose your identity provider or Manual
- IdP Configuration -- Enter SSO URL, Entity ID, and IdP certificate
- SP Configuration -- Configure service provider settings (auto-generated or manual)
- Attribute Mapping -- Map SAML attributes to WitFoo user fields
- Authentication Mode -- Choose SAML-only or Mixed mode
- Key Pair -- Generate or upload SP signing key pair
- Review & Test -- Validate configuration before saving
Authentication Modes¶
| Mode | Value | Description |
|---|---|---|
| SAML Only | saml | All users authenticate via the identity provider. Local login is hidden. |
| Mixed (SAML + Local) | mixed_saml | SAML is primary, but local authentication remains available as a fallback. Users see both login options. |
Mixed Mode Recommendation
Use mixed_saml mode during initial SAML deployment. This ensures administrators can still log in with local credentials if SAML configuration issues arise.
SP Key Pair Generation¶
WitFoo can automatically generate a service provider key pair for SAML request signing:
- Algorithm: RSA 2048-bit
- Output: PEM-encoded private key and self-signed X.509 certificate
- Endpoint:
POST /api/v1/admin/settings/auth/saml/generate-keypair(the request names theentity_id) - Usage: The generated key pair is used to sign SAML authentication requests sent to the IdP
The generated certificate can be uploaded to your identity provider's service provider configuration.
IdP Metadata Fetch¶
If your identity provider publishes a metadata URL, WitFoo can automatically fetch and parse it:
- Endpoint:
POST /api/v1/admin/settings/auth/saml/fetch-metadata - Input: IdP metadata URL
- Output: Extracted SSO URL, SLO URL, and X.509 certificate
This eliminates manual copy-paste of IdP configuration values.
SAML Configuration Test¶
Before saving, validate your SAML configuration using the built-in test endpoint. The test performs 4 checks:
| Check | Description |
|---|---|
certificate_valid | The IdP certificate is PEM, parses as X.509, and has not expired |
key_pair_match | The SP private key matches the SP certificate (or the IdP certificate when no SP certificate is given) |
metadata_fetchable | The IdP metadata URL answers 200; skipped when no metadata URL is set |
sp_build_successful | A service provider can be built from the configuration |
- Endpoint:
POST /api/v1/admin/settings/auth/saml/test - Response: an overall
status(success,partialorfailed) and a pass/fail result with a message for each check
Test Before Save
Always run the SAML configuration test before saving. A misconfigured SAML setup can lock all users out of the system if running in SAML-only mode.
SAML Auth Fallback¶
WitFoo includes automatic redirect loop detection to prevent SAML misconfigurations from locking users out.
How it works:
- On each failed SAML login attempt, a
saml_redirect_countcookie is incremented (MaxAge: 60 seconds) - After 3 failed redirects within 60 seconds, the system detects a loop
- The user is redirected to the login page with
?auth_fallback=true - When
auth_fallback=trueis present, the local authentication form is displayed regardless of the SAML-only setting
This fallback mechanism is implemented consistently across all three UI backends (analytics UI, conductor-ui, console-ui).
Fallback URL
If SAML is completely broken, navigate directly to:
This forces the local login form to appear, allowing administrators to log in and fix the SAML configuration.
Troubleshooting¶
Common SAML Errors¶
| Error | Cause | Solution |
|---|---|---|
| Redirect loop | IdP rejecting authentication requests | Check IdP certificate expiry; verify Entity ID matches IdP configuration |
| Invalid signature | Certificate mismatch | Re-download IdP certificate; ensure no whitespace corruption in PEM |
| Attribute not found | Missing attribute mapping | Verify IdP sends required attributes (email at minimum); check claim URIs |
| Clock skew | Server time difference > 5 minutes | Synchronize NTP on both WitFoo and IdP servers |
| SP key pair mismatch | Private key doesn't match certificate | Regenerate the key pair using the built-in generator |
| "SAML SSO is not configured properly. Contact your administrator." | The login flow could not load an enabled SAML config for the appliance's organization. Most often: SAML is saved but disabled, the SP secret was overwritten by the redaction placeholder on a re-save, or the appliance predates the org-aware SSO-login resolution | Confirm SAML is enabled (auth mode saml or mixed_saml) and saved; re-save without re-typing the secrets (the ***REDACTED*** placeholder is preserved server-side); run the diagnostic at the bottom of the Authentication page; ensure the appliance is on a build with org-aware SSO login (see the note below) |
| Conductor SSO wizard "Invalid request body" at Test Connection | A freshly-built wizard config sent empty server-managed timestamps (created_at/updated_at) the backend could not parse | Update conductor to a build where the SAML config tolerates empty timestamps, then re-run the wizard |
SSO login binds to the appliance's primary organization
The diagnostic validates the SAML config for the signed-in administrator's organization, while the unauthenticated "Sign in with SSO" button resolves the appliance's primary organization (WF_ORG_ID). On a single-tenant appliance these are the same, so configure SAML while signed in as an administrator of the primary organization. If the diagnostic passes but SSO login reports "not configured", the appliance likely predates the org-aware login resolution — update to the latest build.
Recovering from Lockout¶
If all users are locked out due to SAML misconfiguration:
- Access the login page with
?auth_fallback=trueparameter - Log in with a local administrator account
- Open Settings > General Settings > Authentication
- Switch to
mixed_samlmode or fix the SAML configuration - Run the configuration test to validate before saving
Platform administrators and single sign-on¶
From 1.2.0, an organization's SAML identity provider and LDAP directory cannot sign in a platform administrator by default. A platform administrator is an account with the platform-administrator flag, or with a role that holds a platform: permission, such as the built-in Platform Admin role. A refused SAML sign-in returns to the login page with "Your account cannot sign in right now. Contact your administrator." Local password sign-in is not affected.
The appliance operator can exempt one organization, normally their own, with a file on the node that runs analytics-api-svc:
| Setting | Value |
|---|---|
| File | /witfoo/configs/operator-identity-org |
| Owner and mode | root:root, 0644 |
| Content | One organization ID and nothing else |
| Read | Once, when analytics-api-svc starts |
To set it, as root on that node:
printf '%s\n' <org-id> > /witfoo/configs/operator-identity-org
chown root:root /witfoo/configs/operator-identity-org && chmod 0644 /witfoo/configs/operator-identity-org
docker restart analytics-api-svc
docker logs --since 5m analytics-api-svc 2>&1 | grep 'Operator identity organization'
When the file is valid, the api logs Operator identity organization in force with the organization's ID. A file it cannot use exempts nothing and logs [ERROR] /configs/operator-identity-org cannot be used. To remove the exemption, delete the file and restart analytics-api-svc.
What the exemption allows:
- SAML: the organization's identity provider can sign in its platform administrators, whatever the organization ID is.
- LDAP: only when the organization ID equals the first label of the account's mail domain. For example,
[email protected]signs in to the organizationexample. For any other organization ID, use SAML for these accounts. - While the file names an organization, only a platform administrator can change that organization's SAML or LDAP settings. Anyone else is refused with
403platform_admin_required.
When a person has no account¶
The analytics server does not create accounts at the first SSO sign-in. A person who signs in through SAML and has no account here, or whose identity provider sends a different email address than the account holds, is told that an administrator must create the account first and that the address must match. Create the account under Settings > User Management with the same email address the identity provider sends.
Public self-registration¶
Public self-registration is off by default. Two environment variables on the api control it:
| Variable | Default | Description |
|---|---|---|
AUTH_PUBLIC_REGISTRATION_ENABLED | false | Turns on POST /api/v1/auth/register. It gives the same answer whether or not an account is created, and allows 10 requests an hour per client |
AUTH_PUBLIC_REGISTRATION_DOMAINS | (empty) | Comma-separated <email-domain>=<org_id> pairs, for example example.com=acme,corp.example.org=globex |
How registration behaves in 1.2.0:
- An account is created only when
AUTH_PUBLIC_REGISTRATION_DOMAINSmaps the address's domain to an organization. Domains are matched exactly, with no subdomain or wildcard match. - The organization a registration request names is ignored. The email domain chooses the organization.
- Fail-closed: one malformed entry rejects the whole map. The api logs one
[ERROR]naming the entry's position, and registration creates no account until the map is fixed. - The address is not verified, so every account created this way is inactive. An administrator must enable it (Settings > User Management > Enable) before the person can sign in.