Enable SSO with Okta (SAML 2.0)

This guide assumes you have completed the prerequisite steps (e.g. generate self-signed X.509 certificates) outlined here.

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:

App nameFirezone
App logosave link as
Single sign on URLThis 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 formatEmailAddress
Application usernameEmail
Update application username onCreate and update

Okta's documentation contains additional details on the purpose of each configuration setting.

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:

Config IDOktaUsed to construct endpoints required in the SAML authentication flow (e.g., receiving assertions, login requests).
LabelOktaAppears on the sign in button for authentication.
Metadatasee notePaste the contents of the SAML metadata document you downloaded in the previous step from Okta.
Sign assertionsChecked.
Sign metadataChecked.
Require signed assertionsChecked.
Require signed envelopesChecked.
Auto create usersDefault falseEnable this setting to automatically create users when signing in with this connector for the first time. Disable to manually create users.
firezone saml

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