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

# Enable SSO with Okta (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 Okta 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 Okta admin portal, create a new app integration under the Application
tab. Select `SAML 2.0` as the authentication method. Use the following config
values during setup:

| Setting                        | Value                                                                                                                                  |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| App name                       | Firezone                                                                                                                               |
| App logo                       | [save link as](/images/save-logo.png)                                                                                                  |
| Single sign on URL             | This is your Firezone `EXTERNAL_URL/auth/saml/sp/consume/:config_id` (e.g., `https://firezone.company.com/auth/saml/sp/consume/okta`). |
| Audience (EntityID)            | This should be the same as your Firezone `SAML_ENTITY_ID`, defaults to `urn:firezone.dev:firezone-app`.                                |
| Name ID format                 | EmailAddress                                                                                                                           |
| Application username           | Email                                                                                                                                  |
| Update application username on | Create and update                                                                                                                      |

[Okta's documentation](https://help.okta.com/oie/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm)
contains additional details on the purpose of each configuration setting.

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

After creating the SAML connector, visit the `View SAML setup instructions` link
in the Sign On tab to download the metadata document. 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                 | Okta            | Used to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).                          |
| Label                     | Okta            | 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 Okta.                                             |
| 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="firezone saml"
  width={960}
  height={540}
  src="/images/firezone-saml-2.png"
/>

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