import Image from "next/image";

# Enable SSO with Zitadel (OIDC)

Firezone supports Single Sign-On (SSO) using Zitadel 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. `zitadel`)
1. **Label**: The button label text that shows up on your Firezone login screen.
   (e.g. `Zitadel`)
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 zitadel sso login"
  src="/images/firezone-zitadel-sso-login.gif"
  width={960}
  height={540}
/>

## Requirements

- Setup your own [Zitadel Cloud](https://zitadel.cloud) account.
- Create your first Zitadel instance in the
  [Zitadel Customer portal](https://zitadel.cloud/admin/instances)
- Login to your Zitadel instance and create a project (i.e. "Internal")

More information about these steps can be found in
[Zitadel's documentation](https://docs.zitadel.com/docs/guides/start/quickstart#try-out-zitadel-cloud).

## Create Zitadel Application

In the Instance Console, go to **Projects** and select the project you want,
then click **New**.

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

Give the application a name (e.g. "Firezone") and select **WEB** for the
application type.

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

Select **CODE** for the authentication method.

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

Specify the redirect URI and post logout URI.

1. **Redirect URIs**: `EXTERNAL_URL + /auth/oidc/<Config ID>/callback/` (e.g.
   `https://vpn.example.com/auth/oidc/zitadel/callback/`)
1. **Post Logout URIs**: `EXTERNAL_URL` (e.g. `https://vpn.example.com`)

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

Double-check the configuration, then click **Create**.

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

Copy the **ClientId** and **ClientSecret** as it will be used for the Firezone
configuration.

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

In the application **Configuration** click **Refresh Token** and then on
**Save**. The refresh token is optional for some features of Firezone.

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

In the application **Token Settings** select **User roles inside ID Token** and
**User Info inside ID Token**. Save it with a click on **Save**.

<Image className="mx-auto"
  alt="zitadel token settings"
  src="/images/zitadel-token-settings.png"
  width={960}
  height={540}
/>
![Application Token Settings]()

## 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 Zitadel` button on the sign in page.

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

Zitadel can limit which users have access to Firezone. To do this, go to the
project where your created your application. In **General** you can find **Check
Authorization on Authentication** which allows only users with at least one role
to login to Firezone.

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