import Alert from "@/components/DocsAlert";
import Image from "next/image";

# Enable SSO with JumpCloud (SAML 2.0)

<Alert
  color="info"
  html={`
This guide assumes you have completed the prerequisite steps (e.g. generate
self-signed X.509 certificates) outlined
<a href="/docs/authenticate/saml#prerequisites">here</a>.
`}
/>

Firezone supports Single Sign-On (SSO) using JumpCloud through the generic SAML
2.0 connector. This guide will walk you through how to configure the
integration.

## Step 1: Create a SAML connector

In the JumpCloud admin portal, create a new App under the SSO tab. At the bottom
of the popup window, click `Custom SAML App`.

After entering your desired value for `Display Label`, click the `SSO` tab, then
use the following configuration values:

| Setting                   | Value                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| IdP Entity ID             | Any unique string will work, e.g. `firezone-jumpcloud`.                                                                                    |
| SP Entity ID              | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`.                                    |
| ACS URL                   | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id`, e.g. `https://firezone.company.com/auth/saml/sp/consume/jumpcloud`.  |
| SAMLSubject NameID        | `email`                                                                                                                                    |
| SAMLSubject NameID Format | Leave at the default.                                                                                                                      |
| Signature Algorithm       | `RSA-SHA256`                                                                                                                               |
| Sign Assertion            | **Checked**.                                                                                                                               |
| Login URL                 | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id`, e.g. `https://firezone.company.com/auth/saml/auth/signin/jumpcloud` |

Leave the rest of the settings unchanged, then click the `activate` button at
the bottom-right.

Your JumpCloud configuration should now resemble the following:

<Image
  className="mx-auto"
  alt="jumpcloud saml"
  width={960}
  height={540}
  src="/images/jumpcloud-saml.png"
/>

Now, download the IdP Metadata document by selecting the App you just created
and then clicking the `export metadata` button in the upper-right. You'll need
to copy-paste the contents of this document into the Firezone portal in the next
step.

## Step 2: Add SAML identity provider to Firezone

In the Firezone portal, add a SAML identity provider under the Security tab by
filling out the following information:

| Setting                   | Value            | Notes                                                                                                                                       |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Config ID                 | `jumpcloud`      | Firezone uses this value to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).      |
| Label                     | `JumpCloud`      | Appears on the sign in button for authentication.                                                                                           |
| Base URL                  | Leave unchanged. |                                                                                                                                             |
| Metadata                  | see note         | Copy-paste the contents of the SAML metadata document you downloaded in the previous step from JumpCloud.                                   |
| Sign assertions           | Checked.         |                                                                                                                                             |
| Sign metadata             | Checked.         |                                                                                                                                             |
| Require signed assertions | Checked.         |                                                                                                                                             |
| Require signed envelopes  | **Unchecked.**   |                                                                                                                                             |
| Auto create users         | Default `false`  | Enable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users. |

Your Firezone configuration should now resemble the following:

<Image
  className="mx-auto"
  alt="firezone saml"
  width={960}
  height={540}
  src="/images/firezone-saml.png"
/>

After saving the SAML config, you should see a `Sign in with JumpCloud` button
on your Firezone portal sign-in page.
