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.
| Provider | Support Status | Notes |
|---|---|---|
| Okta | Tested and supported | |
| Google Workspace | Tested and supported | Uncheck Require signed envelopes |
| OneLogin | Tested and supported | |
| JumpCloud | Tested and supported | Uncheck 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.
Set the following attributes in your /etc/firezone/firezone.rb configuration
file:
default['firezone']['authentication']['saml']['key'] = '/path/to/your/saml.key'
default['firezone']['authentication']['saml']['cert'] = '/path/to/your/saml.crt'
and run firezone-ctl reconfigure to pick up the changes.
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.