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.

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

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

Setting up the OIDC provider

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

In general, you'll need four pieces of information to set 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.

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.

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.