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)
  2. Label: The button label text that shows up on your Firezone login screen. (e.g. Keycloak)
  3. 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.
  4. Response type: Set to code.
  5. Client ID: The client ID of the application.
  6. Client secret: The client secret of the application.
  7. Discovery Document URI: The OpenID Connect provider configuration URI 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.

keycloak realm

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
  2. Client ID: firezone
  3. Name: Firezone
  4. Click Next.
create firezone client
  1. Toggle Client authentication to On to generate the client secret.
  2. Click Save.
save firezone client

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/).
  2. Click Add valid redirect URIs
firezone access settings

Click the Credentials tab and copy the client secret.

firezone client secret

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.

keycloak realm settings

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.