Okta

Firezone supports Single Sign-On (SSO) using Okta through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:

1. discovery_document_uri: This URL returns a JSON with information to construct a request to the OpenID server.
2. client_id: The client ID of the application.
3. client_secret: The client secret of the application.
4. redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/).
5. response_type: Set to code.
6. scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile offline_access to provide Firezone with the user’s email in the returned claims.
7. label: The button label text that shows up on your Firezone login screen.

Note: Previously, Firezone used pre-configured Oauth2 providers. We’ve moved to OIDC based authentication, which allows for any OpenID Connect provider (Google, Okta, Dex) to be integrated.

We strongly recommend transitioning your existing Google or Okta-based SSO configuration to the generic OIDC-based configuration format described here. We’ll be removing the Google-specific and Okta-specific SSO functionality in a future release.

To set up SSO, follow the steps below:

Step 1 - Create Okta App Integration

This section of the guide is based on Okta’s documentation.

In the Admin Console, go to Applications > Applications and click Create App Integration. Set Sign-in method to OICD - OpenID Connect and Application type to Web application.

On the following screen, configure the following settings:

1. App Name: Firezone
2. App logo: Firezone logo (save link as).
3. Grant Type: Check the Refresh Token box. This ensures Firezone syncs with the identity provider and VPN access is terminated once the user is removed.
4. Sign-in redirect URIs: Add your Firezone EXTERNAL_URL + /auth/oidc/okta/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/) as an entry to Authorized redirect URIs.
5. Assignments: Limit to the groups you wish to provide access to your Firezone instance.

Once settings are saved, you will be given a Client ID, Client Secret, and Okta Domain. These 3 values will be used in Step 2 to configure Firezone.

Integrate With Firezone

Edit /etc/firezone/firezone.rb to include the options below. Your discovery_document_url will be /.well-known/openid-configuration appended to the end of your okta_domain.

# Using Okta as the SSO identity provider
default['firezone']['authentication']['oidc'] = {
  okta: {
    discovery_document_uri: "https://<OKTA_DOMAIN>/.well-known/openid-configuration",
    client_id: "<CLIENT_ID>",
    client_secret: "<CLIENT_SECRET>",
    redirect_uri: "https://firezone.example.com/auth/oidc/okta/callback",
    response_type: "code",
    scope: "openid email profile offline_access",
    label: "Okta"
  }
}

Run firezone-ctl reconfigureand firezone-ctl restart to update the application. You should now see a Sign in with Okta button at the root Firezone URL.

Restricting Access to Certain Users

Okta can limit the users with access to the Firezone app. To do this, go to the Assignments tab of the Firezone App Integration in your Okta Admin Console.