Sign in to OPNsense with your identity provider

Use the account you already trust at Microsoft, Google, Okta, Keycloak, authentik or another OpenID Connect provider to access the OPNsense WebGUI. Your normal local OPNsense login remains available as the recovery path.

This plugin is for WebGUI administration. It does not change Captive Portal or OPNWAF authentication and it does not replace OPNsense core files.

What this gives you

If you run…	You can…
a HomeLab	use one familiar login, require MFA at your provider and keep a local break-glass account
a small team	approve each identity, stop future sign-ins centrally and keep OPNsense permissions local
a security-conscious environment	require verified MFA or phishing-resistant authentication, limit provider-controlled groups and use provider logout or security events where supported
several firewalls or identity systems	start from provider-specific profiles while keeping the same conservative validation rules

The provider proves who the person is. OPNsense still decides which local account and permissions that identity receives. Unknown identities are refused by default or wait for explicit administrator approval.

See the safety checks before enabling sign-in

The familiar local password form remains available beside the identity-provider button. An unavailable or misconfigured provider therefore does not remove the normal recovery path.

Connection health checks the current form values against the live provider. Each result says whether OPNsense, the browser or the identity provider is involved and distinguishes a live request from metadata or configuration.

Test sign-in completes the real browser authorization, code exchange, token and claim validation without creating a WebGUI session or changing a local account, identity binding or group membership.

Keep identity admission explicit

Every accepted external identity is durably bound by its exact issuer and subject to a local OPNsense account. Administrators can review, add, edit or remove those bindings without exposing their storage in the ordinary server form.

With administrator approval, a valid but unknown identity receives no session. Its verified stable identity waits in a private queue until an administrator chooses an existing or new local account, or denies the request.

Is it a good fit?

Choose this plugin when:

• administrators should sign in through OpenID Connect;
• local OPNsense accounts and privileges should remain authoritative;
• the local password form must remain available during an IdP outage;
• you want strict defaults without operating a separate OIDC proxy.

It is not intended for:

• Captive Portal or OPNWAF users;
• replacing OPNsense authorization with cloud-managed roles;
• providers that offer only social OAuth login and no OpenID Connect flow;
• eliminating every local emergency administrator account.

Providers

Named profiles are available for common hosted, self-hosted and social identity providers, including Microsoft Entra ID, Google Workspace, Okta, Auth0, Keycloak, authentik, Authelia, ZITADEL, GitLab and many others. A Generic OpenID Connect profile covers standards-compatible providers without a named preset.

Provider documentation, retained live interoperability tests and standards conformance are deliberately shown as different confidence levels. Check the security and conformance report before choosing a provider or depending on a specific security feature. The provider guides contain the matching setup steps and known limitations.

A safe first setup

1. Install the package.
2. Open System > Access > Servers and add an OpenID Connect server.
3. Select the provider profile and copy the displayed redirect addresses into a confidential web application at the provider.
4. Keep the server disabled while running Test discovery and Test sign-in.
5. Approve or bind the verified identity to a local OPNsense account.
6. Enable the server only after the local password login has been tested in a separate browser session.

The step-by-step setup guide explains each step without assuming prior OpenID Connect knowledge. The settings reference is available when you need to go deeper.

Security without guesswork

The plugin uses the Authorization Code flow, PKCE, exact issuer validation, asymmetric token signatures and one-time login transactions. A selected OPNsense signing certificate can replace a static client secret through private_key_jwt. Optional features such as signed JWT-secured authorization requests (JAR), signed JARM authorization responses, mutual-TLS client authentication, certificate-bound access tokens, PAR, provider-initiated logout, MFA evidence and Shared Signals stream management or push/poll delivery remain subject to provider support.

The generated security and conformance report is the single source for:

• supported, partial and intentionally unsupported standards;
• provider capability and interoperability evidence;
• the verified security comparison between providers;
• threats, controls and accepted residual risks;
• implementation properties backed by the required test tiers.

A feature is not marked conformant merely because it appears to work. Green requires the complete applicable normative inventory and traceable evidence.

Current maturity

The package supports OPNsense Community Edition 26.1 and 26.7. It is installed manually and does not register an automatic package repository. The package includes a watchdog for relevant OPNsense core changes, but upgrades should still be tested before they reach the only administrative firewall.

Keep at least one tested local administrator account. Removing the plugin does not remove its saved settings and does not disable local password login.

Learn more

• Documentation index
• Architecture and trust boundaries
• Troubleshooting and recovery
• Support and security reporting
• Contributing

BSD-2-Clause, see LICENSE.