SSO with OpenID Connect

Firezone supports authenticating users with a universal OIDC connector that works with any authentication service offering a standard OIDC authentication mechanism. Use this connector to enable authenticating users and admins to Firezone for any OIDC-capable identity provider that supports the authorization_code grant.

For Firezone-specific instructions for a given provider, select your provider in the list below:

• Fusion Auth

Fo others, consult your provider's documentation for setting up an OpenID Connect client. Here's a list of popular providers with links to their OIDC documentation for convenience:

• Auth0
• Onelogin
• Keycloak
• Ory
• Authentik
• Zitadel

For more detailed guides specific to each provider, see the Firezone legacy documentation. Firezone 1.0 uses the same OIDC connector under the hood as our legacy version, so the steps should similar.

Setting up the universal OIDC connector

To set up the universal OIDC connector, go to Settings -> Identity Providers -> Add Identity Provider and select OpenID Connect as the identity provider.

In general, you'll need three pieces of information to set up the connector:

• 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 URIs: These are unique to each provider in your Firezone account and are used to complete the authentication process. These are configured in your identity provider's OAuth app settings.
• Client ID and secret: These are used to authenticate Firezone with your identity provider. These are configured in Firezone.
• 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 settings and is configured in Firezone.

Scopes

Firezone requires the following scopes to be added on the connector at a minimum:

• openid: Required by all OpenID Connect integrations and used to identity this user in Firezone
• profile: Required for providing the user's name
• email: Required for authentication

Redirect URIs

When setting up the connector, you'll need to provide two redirect URIs in the connector's allowlist. These are shown in the setup form and are unique to each provider in your Firezone account. They allow Firezone to receive authentication tokens from your identity provider to complete the authentication process.

Client ID and secret

You'll also need to provide the client ID and secret from your identity provider when setting up the connector. These are used to authenticate Firezone with 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

The universal OIDC connector requires the 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 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.

Provisioning users and groups

Users must be created in Firezone before they can sign in with the universal OIDC connector. 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 universal OIDC connector. You can create groups manually in the admin portal or use the REST API to create groups programmatically.