import { TabsGroup, TabsItem } from "@/components/DocsTabs";

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

<TabsGroup>
<TabsItem title="Docker" active>

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/legacy/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.

</TabsItem>
<TabsItem title="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.

</TabsItem>
</TabsGroup>

## 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.
