You're viewing documentation for the legacy version of Firezone, now End-of-Life. View the latest docs here.

Integrate your identity provider using SAML 2.0

Firezone supports Single Sign-On (SSO) via SAML 2.0.

Supported identity providers

In general, most identity providers that support SAML 2.0 should work with Firezone.

ProviderSupport StatusNotes
OktaTested and supported
Google WorkspaceTested and supportedUncheck Require signed envelopes
OneLoginTested and supported
JumpCloudTested and supportedUncheck Require signed envelopes

Occasionally, providers that don't implement the full SAML 2.0 standard or use uncommon configurations may be problematic. If this is the case, contact us about a custom integration.

Custom SAML cert and keyfile

SAML 2.0 requires a set of private and public keys using the RSA or DSA algorithms along with an X.509 certificate that contains the public key.

Firezone automatically generates these for on both Docker and Omnibus-based deployments. If you'd like to use your own cert and key, however, you can generate them with openssl:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout saml.key -out saml.crt

Then use them with your Firezone installation:

Set the SAML_KEYFILE_PATH and SAML_CERTFILE_PATH environment variables to the path containing your saml.key and saml.crt above. If using our example docker compose file, which includes a volume for mapping configuration, save these files to $HOME/.firezone/firezone on the Docker host and set the SAML_KEYFILE_PATH=/var/firezone/saml.key and SAML_CERTFILE_PATH=/var/firezone/saml.crt environment variables for the Firezone container.

General setup instructions

Once you've configured Firezone with an X.509 certificate and corresponding private key as shown above, you'll need a few more things to set up a generic SAML integration.

IdP metadata document

You'll need to get the SAML Metadata XML document from your identity provider. In most cases this can be downloaded from your IdP's SAML App configuration dashboard.

ACS URL

Firezone constructs the ACS URL based on the Base URL and Configuration ID entered in the Firezone SAML configuration, defaulting to: EXTERNAL_URL/auth/saml/sp/consume/:config_id, e.g. https://firezone.company.com/auth/saml/sp/consume/okta.

Entity ID

The Firezone Entity ID can be configured with the SAML_ENTITY_ID environment variable and defaults to urn:firezone.dev:firezone-app if not set.

See the environment variable reference for more information.