SSO with OpenID Connect

Firezone supports authenticating users with a universal OIDC connector that works with any authentication service supporting the OIDC standard and authorization_code grant type.

Directory sync is not supported with the OIDC provider. See the Google, Entra, or Okta guides for setting up directory sync with those providers. You'll need to manually create and manage users and groups for use with the OIDC provider.

You'll need to create an OAuth application with your identity provider. OIDC documentation for popular providers:

Setting up the OIDC provider

To set up the OIDC provider, go to Settings → Authentication → Add Provider and select OIDC.

In general, you'll provide the following when setting up the provider:

Scopes: These control what information Firezone can access from your identity provider. At a minimum, you'll need to provide the openid, profile, and email scopes. These are configured in your identity provider's OAuth app settings.
Redirect URI: Firezone uses a single callback URL for all OIDC authentication:

https://app.firezone.dev/auth/oidc/callback

Client ID and secret: These are used to authenticate Firezone with your identity provider. You'll get these values when you create the OAuth app in your identity provider.
Discovery document URI: This is the URL to your identity provider's OIDC discovery document. This is used to automatically configure the connector with your identity provider's cryptographic and endpoint settings.
Email verification: How Firezone confirms a user owns the email address returned by your provider before linking their OIDC identity.

Scopes

Firezone requires the following OAuth scopes in order to authenticate users via the OIDC provider:

email: Provides the email claim used for identifying users by email on the first sign-in
openid: Provides the iss and sub claims used for identifying users on subsequent sign-ins
profile: Provides the name and other profile claims used for displaying user information in the admin portal

Additional scopes are allowed but unused by Firezone.

Redirect URIs

Firezone uses a common redirect URI for all OIDC authentication:

https://app.firezone.dev/auth/oidc/callback

Make sure to add this URI to the list of allowed redirect URIs in your identity provider's OAuth app settings.

Client ID and secret

Provide the client ID and secret from the OAuth app you created in your identity provider.

Discovery document URI

The discovery document URI is the URL to your identity provider's OIDC discovery document. This document contains all the information needed to configure the connector with your identity provider's settings. You can usually find this URL in your identity provider's OAuth app settings or in their OIDC documentation.

It typically looks something like this (Okta example given):

https://your-tenant.okta.com/.well-known/openid-configuration

PKCE

Firezone's OIDC authentication provider requires your identity provider to support PKCE (Proof Key for Code Exchange). PKCE is a security feature that helps prevent certain types of attacks and is supported by nearly every OIDC identity provider today.

If your provider does not support PKCE, authentication will fail with an error message similar to this:

You may not authenticate to this account.

If you believe this to be in error, please contact support for assistance.

Email verification

Because the universal OIDC connector works with any provider, Firezone lets you choose how it confirms that a user owns the email address the provider returns before linking that OIDC identity to a Firezone user. Firezone matches an OIDC identity to a user by email on the first sign-in (see Scopes), so this setting controls how much it trusts that email.

Choose one of three methods when configuring the provider:

Claim (default) — Trust the email address only when the provider returns email_verified=true in the ID token or userinfo response. If the claim is missing or false, sign-in fails. Use this whenever your provider reliably sets email_verified.
Proof — Before linking a new OIDC identity, Firezone emails a one-time passcode to the claimed address, and the user must enter it to complete the link. This challenge happens only the first time an identity is linked; subsequent sign-ins go straight through. Use this when your provider can't reliably send email_verified=true.
None — Don't confirm email ownership at all; Firezone trusts the email claim as-is. Not recommended — a provider that lets users set an unverified email could allow one user to sign in as another.

Prefer Claim or Proof unless you fully trust your provider's email handling. None disables a key protection against account takeover via spoofed email claims.

Provisioning users and groups

Users must be created in Firezone before they can sign in with the OIDC provider. You can create users in the admin portal or programmatically via the REST API.

Similarly, groups used for access control must also be created in Firezone before they can be used with users associated with the OIDC provider. You can create groups manually in the admin portal or use the REST API to create groups programmatically.

Firezone accounts with the Google, Entra, or Okta directories enabled will have their users and groups automatically provisioned.

Need help? See all support options.