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

# Enable SSO with OneLogin (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 OneLogin 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 OneLogin admin portal, add an app under the application tab. Select
`SAML Custom Connector (Advanced)` and provide the appropriate configuration
settings under the under the configuration tab.

The following fields should be filled out on this page:

| Setting                | Value                                                                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Audience (EntityID)    | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`.                                                                                   |
| Recipient              | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`).                                                |
| ACS URL Validator      | This field is regex to ensure OneLogin posts the response to the correct URL. For the sample URL below, we can use `^https:\/\/firezone\.company\.com\/auth\/saml\/sp\/consume\/onelogin` |
| ACS URL                | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`).                                                |
| Login URL              | This is your Firezone `EXTERNAL_URL/auth/saml/auth/signin/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/onelogin`).                                               |
| SAML initiator         | Service Provider                                                                                                                                                                          |
| SAML signature element | Both                                                                                                                                                                                      |
| Encrypt Assertion      | Checked.                                                                                                                                                                                  |

[OneLogin's docs](https://onelogin.service-now.com/support?id=kb_article&sys_id=912bb23edbde7810fe39dde7489619de&kb_category=93e869b0db185340d5505eea4b961934)
provide a good overview of each field's purpose.

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

Once complete, save the changes and download the SAML metadata document found
unde the `More Actions` dropdown. 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                 | `onelogin`      | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).                          |
| Label                     | `OneLogin`      | Appears on the sign in button for authentication.                                                                                           |
| Metadata                  | see note        | Paste the contents of the SAML metadata document you downloaded in the previous step from OneLogin.                                         |
| Sign assertions           | Checked.        |                                                                                                                                             |
| Sign metadata             | Checked.        |                                                                                                                                             |
| Require signed assertions | Checked.        |                                                                                                                                             |
| Require signed envelopes  | Checked.        |                                                                                                                                             |
| 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. |

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

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