firezone/www/docs/authenticate/saml

---
title: SAML 2.0
sidebar_position: 11
description: Enforce single sign-on with your identity provider. Integrate
  providers like Okta, Google, OneLogin, and JumpCloud using Firezone's
  SAML 2.0 connector.
---

# 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](okta)               | **Tested and supported** |                                    |
| [Google Workspace](google) | **Tested and supported** | Uncheck `Require signed envelopes` |
| [OneLogin](onelogin)       | **Tested and supported** |                                    |
| [JumpCloud](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](/sales) 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:

<Tabs>
<TabItem value="docker" label="Docker" default>

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](https://github.com/firezone/firezone/blob/master/docker-compose.prod.yml),
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.

</TabItem>
<TabItem value="omnibus" label="Omnibus">

Set the following attributes in your `/etc/firezone/firezone.rb` configuration file:

```ruby
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.

</TabItem>
</Tabs>

## 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](/docs/reference/env-vars) for more information.