SSO with Okta

Firezone integrates with Okta using a custom connector that supports both authentication and directory sync. Use this guide if you're looking to setup SSO with Okta for your Firezone account and optionally sync users and groups from Okta to Firezone.

Overview

The Firezone Okta connector integrates with Okta's APIs to support user authentication and directory sync.

On Enterprise plans, users and groups are synced every few minutes to ensure that your Firezone account remains up-to-date with the latest identity data from Okta. Read more about how sync works.

Setup

Setting up the Okta connector is similar to the process of setting up a universal OIDC connector. The main difference is the addition of a few extra read-only scopes needed to enable directory sync.

Follow the steps below to setup the Okta connector.

Step 1: Start the Okta provider setup in Firezone

In your admin portal, go to Settings -> Identity Providers and click Add Identity Provider. Then, select Okta from the list of identity providers.

You'll be shown a summary of the steps you need to complete to setup the Okta provider. Keep this page open as you'll need to refer to it in the following steps.

Step 2: Create a new OIDC app in Okta

In your Okta admin portal, go to Applications -> Applications in the left sidebar.

Click Create App Integration.

Select OIDC - OpenID Connect as the application type.

Select Web Application as the application type and click Next.

Fill in the App integration name field with Firezone Connector.

Download the Firezone logo to use for the app integration and upload it to Okta (optional).

Ensure both the Authorization Code and Refresh Token grant types are selected.

In the Sign-in redirect URIs field, enter the redirect URIs shown in the setup form in your Firezone admin portal.

In the Sign-out redirect URIs field, enter https://app.firezone.dev.

In the Assignments tab, assign the app to the groups you want to have access to Firezone.

Then click Save.

Step 3: Configure the Okta provider in Firezone

In the app integration settings in Okta, you'll find the Client ID and Client secret. Copy these values and paste them into the setup form in your Firezone admin portal.

Optionally, enable the Require PKCE as additional verification setting for added security.

Scroll down to Refresh Token and ensure Use persistent token is selected.

Step 4: Assign scopes and groups

In the app integration settings in Okta, click Assignments and then the Assign button.

For Enterprise plans, ensure the okta.groups.read and okta.users.read scopes are granted.

Step 5: Complete the Okta provider setup in Firezone

Go back to the General tab in the app integration settings in Okta and copy your Okta account domain shown in the top-right corner.

Enter this value into the setup form in your Firezone admin portal.

Ensure all fields are filled out, and click Connect Identity Provider.

If you get successfully redirected back to your Firezone admin dashboard, you're done! Your Okta provider is now successfully configured. If directory sync is enabled, the first sync will occur within about 10 minutes. After that, users will be able to authenticate to Firezone using their Okta accounts.