Skip to main content

Zitadel

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. discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.
  2. client_id: The client ID of the application.
  3. client_secret: The client secret of the application.
  4. redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/).
  5. response_type: Set to code.
  6. 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.
  7. label: The button label text that shows up on your Firezone login screen.

Firezone Zitadel SSO Login

Requirements

More information about these steps: 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. Click New. Start adding a new application in the project site

Give the application a name (i.e. "Firezone") and select the application type WEB. Name the applicaiton and select type WEB

Select CODE for the authentication method. Select authentication method CODE

Specify the redirect URI and post logout URI. The redirect URI will be of the form EXTERNAL_URL + /auth/oidc/zitadel/callback/. The post logout URI can just be the EXTERNAL_URL. Specify the redirect URI and post logout URI

Check all the overview of the configuration and clich on Create. Configuratin Overview

Copy the ClientId and ClientSecret as it will be used for the firezone configuration. image

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

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

Integrate With Firezone

Edit /etc/firezone/firezone.rb to include the options below. Your discovery_document_url will be /.well-known/openid-configuration appended to the end of your zitadel instance domain. You can find this domain for example in the application under Urls.

# Using Zitadel as the SSO identity provider
default['firezone']['authentication']['oidc'] = {
zitadel: {
discovery_document_uri: "https://<ZITADEL_INSTANCE_DOMAIN>/.well-known/openid-configuration",
client_id: "<CLIENT_ID>",
client_secret: "<CLIENT_SECRET>",
redirect_uri: "https://vpn.example.com/auth/oidc/zitadel/callback/",
response_type: "code",
scope: "openid email profile offline_access",
label: "Zitadel"
}
}

Run firezone-ctl reconfigure to update the application. You should now see a Sign in with Zitadel button at the root Firezone URL. Sign in with Zitadel

Restricting Access to only Users with Roles

Zitadel can limit the users with access to the Firezone app. To do this, go to the project where your created your application in. In General you can find Check authorization on Authentication which allows only user to login, and thus use firezone, if they have assigned at least one role. Zitadel check authorization on authentication