import Image from "next/image";

# Enable SSO with Auth0 (OIDC)

Firezone supports Single Sign-On (SSO) using Auth0 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. `auth0`)
1. **Label**: The button label text that shows up on your Firezone login screen.
   (e.g. `Auth0`)
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` 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.

## Step 1: Obtain OIDC configuration parameters

In the Auth0 dashboard, create an application. Select **Regular Web
Application** as the application type.

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

Next, visit the settings tab on the application details page. Take note and
modify the following parameters:

1. **Name**: `Firezone`
1. **Domain**: The domain will be used to construct the url to retrieve the OIDC
   discovery document -
   `https://<AUTH0_DOMAIN>/.well-known/openid-configuration`
1. **Icon**: [Firezone icon](/images/save-link-as-icon.png) (save link as).
1. Set **Allowed Callback URLs** to
   `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
   `https://firezone.example.com/auth/oidc/auth0/callback/`).

<Image className="mx-auto"
  alt="auth0 settings 1"
  src="/images/auth0-settings-1.png"
  width={960}
  height={540}
/>
<Image className="mx-auto"
  alt="auth0 settings 2"
  src="/images/auth0-settings-2.png"
  width={960}
  height={540}
/>
<Image className="mx-auto"
  alt="auth0 settings 3"
  src="/images/auth0-settings-3.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 Auth0` button on the sign in page.

## Step 3 (optional): Restrict access to specific users

Auth0 supports setting access policies to control which users can access the
Firezone application. See Auth0's
[Documentation](https://auth0.com/docs/manage-users/user-accounts/manage-user-access-to-applications)
for details.
