import Image from "next/image";

# 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`)
1. **Label**: The button label text that shows up on your Firezone login screen.
   (e.g. `Okta`)
1. **Scope**:
   [OIDC scopes](https://openid.net/specs/openid-connect-basic-1_0.html#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.
1. **Response type**: Set to `code`.
1. **Client ID**: The client ID of the application.
1. **Client secret**: The client secret of the application.
1. **Discovery Document URI**: The
   [OpenID Connect provider configuration URI](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig)
   which returns a JSON document used to construct subsequent requests to this
   OIDC provider.

<Image className="mx-auto"
  alt="firezone okta sso login"
  src="/images/firezone-okta-sso-login-2.gif"
  width={960}
  height={540}
/>

## Step 1: Create Okta app integration

_This section of the guide is based on
[Okta's documentation](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)._

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**.

<Image className="mx-auto"
  alt="okta create options"
  src="/images/okta-create-options.png"
  width={960}
  height={540}
/>

On the following screen, configure the following settings:

1. **App Name**: `Firezone`
1. **App logo**: [save link as](/images/save-logo.png).
1. **Proof Key for Code Exchange (PKCE)**: Check
   `Require PKCE as additional verification` if you're running Firezone 0.6.8 or
   higher. [PKCE](https://oauth.net/2/pkce) is recommended for increased
   security whenever possible.
1. **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.
1. **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.
1. **Assignments**: Limit to the groups you wish to provide access to your
   Firezone instance.

<Image className="mx-auto"
  alt="okta settings"
  src="/images/okta-settings.png"
  width={960}
  height={540}
/>

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.

<Image className="mx-auto"
  alt="okta credentials"
  src="/images/okta-credentials.png"
  width={960}
  height={540}
/>

## 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.

<Image className="mx-auto"
  alt="okta assignments"
  src="/images/okta-assignments.png"
  width={960}
  height={540}
/>
