Enterprise sign-in methods (SSO) & multi-factor authentication (MFA)
Configuration location
Enterprise administrators access these settings via Settings → Enterprise, in the Sign-in methods and Multi-factor authentication tabs.
If your users sign in behind a VPN, a corporate proxy or a firewall performing SSL inspection, some SSO flows may be blocked or altered (state cookie stripped, identity domains unreachable). The typical symptom is a sign-in that fails or loops — while SSO works without the VPN. Share the network flow matrix with your network team to allow the required domains without SSL inspection or cookie rewriting.
Available sign-in methods
FoxPlan supports multiple authentication approaches:
- Password-based login
- Google Sign-in
- Microsoft Sign-in
- Enterprise SSO (OIDC)
Enterprise administrators always keep password sign-in, even when it is disabled for the enterprise. This prevents being locked out of FoxPlan if the identity provider becomes unavailable.
Exceptions: keeping password sign-in for specific users
When moving your organization to SSO, you can disable password sign-in for everyone except a designated list of users.
Clear the Password checkbox: an "Exceptions: users keeping password sign-in" picker appears below the checkboxes. Select the relevant users there, then save.
Those users keep seeing the password field on the sign-in screen, while everyone else must use SSO or Google/Microsoft sign-in.
Typical use cases:
- Break-glass accounts in case of an identity provider outage
- Contractors or external users who are not in your corporate directory
- Phased migration: moving teams to SSO in waves
The picker only appears when the Password method is unchecked: while it is enabled, it already applies to everyone and no exception is needed.
Multi-factor authentication options
Organizations can select from these MFA approaches:
- TOTP (compatible with Google Authenticator, Microsoft Authenticator, Okta, Keycloak)
- Email-based verification
- No MFA
Scope: who multi-factor authentication applies to
As soon as a method is selected (TOTP or Email), an "Applies to" section lets you choose the target population:
| Option | Effect |
|---|---|
| All users | Multi-factor authentication is enforced across the whole enterprise (default behaviour). |
| Only the listed users | Only the selected users go through multi-factor authentication. |
| All users except the listed ones | Multi-factor authentication applies everywhere, except for the selected users. |
For the last two modes, a picker lets you designate the users concerned.
Typical use cases:
- Phased rollout: start with "Only the listed users" and a pilot team, then switch to "All users".
- Targeted hardening: require multi-factor authentication only for administrators and sensitive profiles.
- Technical exclusions: exempt accounts that cannot answer an MFA challenge (service accounts, shared kiosks) via "All users except the listed ones".
The scope is enforced server-side: a user outside the scope signs in directly, with no MFA challenge, even when a method is active for the enterprise.
In "All users except the listed ones" mode, every excluded user weakens your security posture. Review that list regularly.
Login flow process
- User provides email and proceeds
- FoxPlan identifies the associated enterprise
- Available authentication methods display for that organization
- User selects Password or SSO based on enabled options
For password-based flows, MFA challenges apply. SSO flows delegate authentication assurance to the identity provider.
Enterprise SSO (OIDC) setup
FoxPlan supports OIDC providers including Okta, Keycloak, Google, Microsoft, and custom implementations.
Identity provider configuration:
- Create a Web-type OIDC application
- Redirect URI:
{origin}/login/oauth2/code/{registrationId} - Collect Client ID, Client Secret (or certificate, see below), and Issuer URI
FoxPlan SSO form fields:
- Provider selection
- Display Name
- Client ID
- Client authentication: shared secret or certificate
- Issuer URI
- Scopes:
openid,profile,email - Username attribute (typically
suboremail) - Enable toggle
Client authentication: secret or certificate
Exchanging the authorisation code for a token is the only call FoxPlan makes directly to the identity provider, server to server. FoxPlan must identify itself there, and the Client authentication field offers two ways of doing so.
Client secret (default). A shared secret, entered on both sides. This is the historical mode, and nothing changes for existing configurations: without an explicit choice, they stay on it.
Certificate (private key). FoxPlan signs a JWT assertion with a private key, and the provider
verifies it with the public certificate you declared there (private_key_jwt, RFC 7523). The
secret then never travels over the network — which is why many IT departments now forbid client
secrets.
Two fields then appear:
- Client certificate: the X.509 certificate in PEM format. This is the public half, to be uploaded to your identity provider as well (in Entra ID: Certificates & secrets → Certificates).
- Private key: in unencrypted PKCS#8 format, the one starting with
-----BEGIN PRIVATE KEY-----. A PKCS#1 key (BEGIN RSA PRIVATE KEY) or a passphrase-protected one is rejected, along with the conversion command to run.
To produce a pair:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out certificate.pem -days 730 -nodes -subj "/CN=foxplan-sso"
openssl pkcs8 -topk8 -nocrypt -in key.pem -out key-pkcs8.pem
Declare certificate.pem with the provider and paste key-pkcs8.pem into FoxPlan.
The private key is encrypted at rest, never returned by the API and never displayed again: when editing, leaving the field empty keeps the stored key. The certificate is public and stays visible.
Unlike a secret, a certificate carries an end date. Once it passes, SSO stops dead.
The deadline is therefore always on display: the configuration list carries an Authentication column showing, for each SSO, whether it authenticates with a secret or a certificate — and in the latter case the expiry date, in orange during the month before it and in red once passed. That date is never typed in: it is read from the certificate itself every time it is displayed, the only source that cannot drift from reality. Check configuration gives the full detail, fingerprint included.
Provider-specific configuration
Google — Issuer URI: https://accounts.google.com
Microsoft / Azure — Issuer pattern: https://login.microsoftonline.com/{tenantId}/v2.0
Okta — Web app type with proper assignment and access policies
Keycloak — Realm issuer URI with Authorization Code flow configured
Being warned before expiry
Displaying the date assumes someone goes and looks. FoxPlan therefore warns on its own: an email is sent to the enterprise administrators at three points — thirty days, seven days, then the day the certificate has expired. The message names the provider concerned, gives the date, and links back to the configuration screen.
Each stage is announced only once: the sweep remembers what it has already sent. As soon as the certificate is renewed — the deadline moving back beyond thirty days — the counter re-arms by itself for the next certificate. Nothing needs to be done.
If no enterprise administrator is declared, no email goes out: one more reason to keep that list up to date in the enterprise members.
When sign-in fails
A user whose SSO sign-in fails returns to the login screen with a sentence naming the cause, rather than a code returned by the identity provider:
| What the user sees | What to do |
|---|---|
| The sign-in certificate has expired | Renew the certificate and upload it on both sides |
| The certificate cannot be used | Check that the private key matches the certificate |
| The provider rejected FoxPlan's credentials | The secret was changed at the provider, or the certificate is not declared there |
| No active SSO connection | The configuration is disabled or missing |
| The provider denied access | The account is not allowed on the application at the provider |
The technical detail — the provider's exact message, the full trace — stays in the server logs, for support. The user gets a sentence telling them who to turn to.
Checking the configuration before testing
Each configuration in the list carries a Check configuration button. It opens a report that stays on the screen and attempts no connection:
- the URLs to declare with the identity provider, each with a copy button: the redirect URL and the sign-in launch URL. These are exactly the ones the application will use, so there is no need to piece them together by hand;
- the consistency checks: required fields filled in, discovery document read from the server, issuer and endpoints matching what the provider publishes. With certificate authentication, the report also verifies that the private key matches the certificate, shows the SHA-1 fingerprint — the one displayed by the provider's console — and flags a certificate that has expired or is about to.
Three levels: green when compliant, orange for a point worth a look, red for what will prevent sign-in. The detail shown to the right of each line is the raw data — URL, HTTP status, provider message — the one you pass on to support.
A check may be reported as "URL not probed": the server only calls public https addresses, and
the configuration is not at fault.
This report is read-only: it never changes the configuration.
Troubleshooting
Verify these elements when experiencing authentication issues:
- Redirect URI matches exactly between IdP and FoxPlan
- SSO configuration is enabled
- User email belongs to the correct enterprise
- For Okta/Azure/Keycloak, confirm user assignment and policy compliance
- For Password+MFA users, verify valid enrollment (TOTP secret or email)