import Image from "next/image";

# Enable SSO with Keycloak (OIDC)

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

## Step 1: Obtain configuration parameters

In the Keycloak Admin Console, make sure the realm you want to use with Firezone
is selected.

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

### Create Firezone OAuth client

Create a new Client for Firezone by navigating to **Clients > Create Client**
and configure the following:

1. **Client type**: `OpenID Connect`
1. **Client ID**: `firezone`
1. **Name**: `Firezone`
1. Click **Next**.

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

1. Toggle **Client authentication** to `On` to generate the client secret.
1. Click **Save**.

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

Click **Access settings** to jump to that section and configure the valid
redirect URI:

1. **Valid Redirect URIs**: This should be your Firezone
   `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
   `https://firezone.example.com/auth/oidc/keycloak/callback/`).
1. Click **Add valid redirect URIs**

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

Click the **Credentials** tab and copy the client secret.

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

Navigate to the **Realm Settings** page to get the **Discovery Document URI** by
copying the **OpenID Endpoint Configuration** link at the bottom of the page.

<Image className="mx-auto"
  alt="keycloak realm settings"
  src="/images/keycloak-realm-settings.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 Keycloak` button on the sign in page.
