Enable SSO with Okta (OIDC)

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. Config ID: The provider's config ID. (e.g. okta)
2. Label: The button label text that shows up on your Firezone login screen. (e.g. Okta)
3. 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.
4. Response type: Set to code.
5. Client ID: The client ID of the application.
6. Client secret: The client secret of the application.
7. Discovery Document URI: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.

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: save link as.
3. Proof Key for Code Exchange (PKCE): Check Require PKCE as additional verification if you're running Firezone 0.6.8 or higher. PKCE is recommended for increased security whenever possible.
4. 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.
5. Sign-in redirect URIs: Add your Firezone EXTERNAL_URL + /auth/oidc/<Config ID>/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/) as an entry to Authorized redirect URIs.
6. 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.

Step 2: Integrate with Firezone

Navigate to the /settings/security page in the admin portal, click "Add OpenID Connect Provider" and enter the details you obtained in the steps above.

Enable or disable the Auto create users option to automatically create an unprivileged user when signing in via this authentication mechanism.

And that's it! The configuration should be updated immediately. You should now see a Sign in with Okta button on the sign in page.

Step 3 (optional): Restrict Access to specific 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.