SSO with Okta

STARTERTEAMENTERPRISE

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.

Directory sync is supported for the Enterprise plan only.

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.

Dashboard

Click Create App Integration.

Applications

Select OIDC - OpenID Connect as the application type.

OIDC app

Select Web Application as the application type and click Next.

Application type

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.

App name and grant type

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.

Redirect URIs

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

The user setting up this connector must have access to the Okta application being created. If you choose to "skip group assignment for now", please make sure your user is assigned to this Okta app before finishing the setup in Firezone.

Then click Save.

Group assignment

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.

Client credentials

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

Verify refresh token behavior

Step 4: Assign scopes and groups

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

Assign groups to people

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

Grant groups read scope Grant users read scope Verify scopes

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.

Find Okta account domain

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

If you get successfully redirected back to your Firezone admin portal, 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.

Synced users will be assigned the User role by default, allowing them access to sign in from the Firezone Client only. If you need to grant access to the admin portal, you need to manually promote the user to the Admin role by visiting Actors -> <actor name> -> Edit User and updating their role.


Need additional help?

See all support options or try asking on one of our community-powered support channels:

Or try searching the docs:
Found a problem with this page? Open an issue
Last updated: July 24, 2024