Firezone is a self-hosted VPN server and Linux firewall

• Manage remote access through an intuitive web interface and CLI utility.
• Deploy on your own infrastructure to keep control of your network traffic.
• Built on WireGuard® to be stable, performant, and lightweight.

Get Started

Follow our deploy guide to install your self-hosted instance of Firezone.

Or, if you’re on a supported platform, try our one-line install script :

sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”

Features

• Fast: Uses WireGuard® to be 3-4 times faster than OpenVPN.
• SSO Integration: Authenticate using any identity provider with an OpenID Connect (OIDC) connector.
• No dependencies: All dependencies are bundled thanks to Chef Omnibus.
• Simple: Takes minutes to set up. Manage via a simple CLI.
• Secure: Runs unprivileged. HTTPS enforced. Encrypted cookies.
• Firewall included: Uses Linux nftables to block unwanted egress traffic.

Anti-features

Firezone is not:

• An inbound firewall
• A tool for creating mesh networks
• A full-featured router
• An IPSec or OpenVPN server

Deploy

Get started with Firezone in a few minutes by self-hosting on a supported platform​

Firezone can be self-hosted on a server running a supported Linux distribution in a few minutes. This guide will walk you through the steps to get started.

Step 1: Environment Setup​

Supported operating systems​

Start by checking if your environment is listed on supported platforms. A kernel upgrade may be required to ensure WireGuard® is available.

Security settings​

Ensure port forwarding is enabled on your firewall. The default Firezone configuration requires the following ports to be open:

• 443/tcp: To access the web UI.
• 51820/udp: The VPN traffic listen-port.

NOTE

Firezone modifies the kernel netfilter and routing tables. Other programs that modify the Linux routing table or firewall may interfere with Firezone’s operation. For help troubleshooting connectivity issues, see the troubleshooting guide.

Production deployments​

Firezone requires the setup of a DNS record and matching SSL certificate for production deployments. See instructions here.

Step 2: Server Install Script​

The easiest way to get started using Firezone is via the automatic installation script below.

sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”

This will ask you a few questions regarding your install, install the latest release for your platform, then create an administrator user and print to the console instructions for logging in to the web UI.

By default, the web UI can be reached at the IP or domain name of your server. You can regenerate the admin credentials using the firezone-ctl create-or-reset-admin command.

If the script fails, follow instructions for manual installation.

Step 3: Install Client Apps​

Once successfully deployed, users and devices can be added to connect to the VPN server:

• Add Users: Add users to grant them access to your network.
• Client Instructions: Instructions to establish a VPN session.

After Setup​

Congrats! You have completed the setup, but there’s a lot more you can do with Firezone.

• Integrate your identity provider for authenticating clients
• Using Firezone to establish a static IP
• Create tunnels between multiple peers with reverse tunnels
• Only route certain traffic through Firezone with split tunneling

Support us by:

• Star our repo on Github
• Follow us on Twitter at @firezonehq
• Follow us on LinkedIn at @firezonehq

Supported Platforms

Firezone currently supports the following platforms:

OS	Architectures	Status	Notes
AmazonLinux 2	amd64 arm64	Fully-supported	See AmazonLinux 2 Notes
CentOS 7	amd64	Fully-supported	See CentOS 7 Notes
CentOS 8	amd64 arm64	Fully-supported	See CentOS 8 Notes
CentOS Stream 9	amd64 arm64	Fully-supported	Works as-is
Red Hat Enterprise Linux 7	amd64	Fully-supported	See RHEL 7 Notes
Red Hat Enterprise Linux 8	amd64 arm64	Fully-supported	See RHEL 8 Notes
Red Hat Enterprise Linux 9	amd64 arm64	Fully-supported	See RHEL 9 Notes
Debian 10	amd64 arm64	Fully-supported	See Debian 10 Notes
Debian 11	amd64 arm64	Fully-supported	Works as-is
Fedora 33	amd64 arm64	Fully-supported	See Fedora Notes
Fedora 34	amd64 arm64	Fully-supported	See Fedora Notes
Fedora 35	amd64 arm64	Fully-supported	See Fedora Notes
Ubuntu 18.04	amd64 arm64	Fully-supported	See Ubuntu 18.04 Notes
Ubuntu 20.04	amd64 arm64	Fully-supported	Works as-is
Ubuntu 22.04	amd64 arm64	Fully-supported	Works as-is
openSUSE Leap 15.3	amd64	Fully-supported	See openSUSE Notes

If your distro isn’t listed here please try using a package for the closest distro first. For example, since Raspberry Pi OS is based on Debian, try using the Debian Firezone package.

If that doesn’t work, please open an issue and let us know. New distros are being supported on a regular basis and there’s a good chance yours will be added soon.

Note that we only support RPM and DEB based packaging systems. Others, like Arch Linux are currently being investigated in this issue.

AmazonLinux 2 Notes​

Kernel upgrade required:

sudo amazon-linux-extras install -y kernel-5.10

CentOS 7 Notes​

Kernel upgrade to 5.6+ required. To upgrade to the latest mainline kernel and select it as the default boot kernel:

sudo rpm –import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
sudo yum install -y https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm
sudo yum install -y elrepo-release
sudo yum –enablerepo=elrepo-kernel install -y kernel-ml
sudo grub2-set-default 0
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
sudo reboot

CentOS 8 Notes​

The WireGuard kernel module needs to be installed:

yum install elrepo-release epel-release
yum install kmod-wireguard

RHEL 7 Notes​

Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone package for CentOS 7 should work just fine for RHEL 7. You’ll still need to upgrade your kernel to 5.6+ however. To do so, follow the steps for CentOS 7 Notes above.

RHEL 8 Notes​

Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone package for CentOS 8 should work just fine for RHEL 8. You’ll still need to install the WireGuard kernel module, however. See CentOS 8 Notes above.

RHEL 9 Notes​

Use the package for CentOS 9.

Fedora Notes​

On fresh Fedora installations you’ll probably need to install a cron implementation to support the logrotate functionality, otherwise you may receive errors about a missing /etc/cron.hourly directory.

yum install cronie-anacron

Ubuntu 18.04 Notes​

Kernel upgrade to 5.4+ required:

sudo apt install linux-image-generic-hwe-18.04

Debian 10 Notes​

Kernel upgrade to 5.6+ required. See this guide for an example.

openSUSE Notes​

Firezone requires the setcap utility, but some recent openSUSE releases may not have it installed by default. To fix, ensure libcap-progs is installed:

sudo zypper install libcap-progs

Prerequisites

Firezone requires the setup of a DNS record and matching SSL certificate for production deployments.

Create a DNS record​

Firezone requires a fully-qualified domain name (e.g. firezone.company.com) for production use. You’ll need to create the appropriate DNS record at your registrar to achieve this. Typically this is either an A, CNAME, or AAAA record depending on your requirements.

Create an SSL certificate​

While Firezone generates a self-signed SSL certificate for you on install, you’ll need a valid SSL certificate to use Firezone in a production capacity.

We recommend using Let’s Encrypt to generate a free SSL cert for your domain. Starting with Firezone 0.5.0 you have the option to auto-provision Let’s Encrypt SSL certificates for your instance using the ACME protocol. This is disabled by default to maintain backwards compatibility for existing installations.

To enable this, you must ensure the following conditions are met:

• 80/tcp is allow inbound
• The bundled Firezone nginx service is enabled and functioning
• You have a valid DNS record assigned to this instance’s public IP
• The following 3 settings are configure in the configuration file:
  • default['firezone']['external_url']: The FQDN for the server.
  • default['firezone']['ssl']['email_address']: The email that will be used for the issued certificates.
  • default['firezone']['ssl']['acme']['enabled']: Set this to true to enable it.

Security Group and Firewall Settings​

By default, Firezone requires ports 443/tcp and 51820/udp to be accessible for HTTPS and WireGuard traffic respectively. These ports can change based on what you’ve configured in the configuration file. See the configuration file reference for details.

Resource Requirements​

We recommend starting with 1 vCPU and 1 GB of RAM and scaling up as the number of users and devices grows.

For Omnibus-based deployments on servers with less than 1GB of memory, we recommend turning on swap to prevent the Linux kernel from killing Firezone processes unexpectedly. When this happens, it’s often difficult to debug and results in strange, unpredictable failure modes.

For the VPN tunnels themselves, Firezone uses in-kernel WireGuard, so its performance should be very good. 1 vCPU should be more than enough to saturate a 1 Gbps network link.

Install Server

Important: Ensure you’ve satisfied the prerequisites before following this guide.

Installation Instructions​

Assuming you’re running a supported Linux kernel on one of the supported platforms, use one of the methods below to get started:

Automatic Install​

The easiest way to get started using Firezone is via the automatic installation script:

sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”

This will ask you a few questions regarding your install, install the latest release for your platform, then create an administrator user and print to the console instructions for logging in to the web UI.

Install from our Debian or RedHat repositories​

If the automatic install script fails, try these steps to install Firezone from our Cloudsmith repository.

• Install WireGuard for your distro. If using Linux kernel 5.6 or higher, skip this step.
• Install our package repository for your distro’s package format:
  • deb packages:

curl -1sLf \
‘https://dl.cloudsmith.io/public/firezone/firezone/setup.deb.sh’ \
| sudo -E bash

See the Debian setup docs for more options if the script fails to setup the repo.

• rpm packages:

curl -1sLf \
‘https://dl.cloudsmith.io/public/firezone/firezone/setup.rpm.sh’ \
| sudo -E bash

• See the RedHat setup docs for more options if the script fails to setup the repo.
• Install Firezone with your distro’s package manager:

Using apt
sudo apt install firezone
Using dnf
sudo dnf install firezone
Using yum
sudo yum install firezone
Using zypper
sudo zypper install firezone

• Follow the bootstrap instructions to setup Firezone.

Manual Install​

If all else fails, try these steps to install Firezone manually.

• Install WireGuard for your distro. If using Linux kernel 5.6 or higher, skip this step.
• Download the relevant package for your distribution from the releases page.
• Install with sudo rpm -i firezone*.rpm or sudo dpkg -i firezone*.deb depending on your distro.
• Follow the bootstrap instructions to setup Firezone.

Bootstrap Firezone​

• Bootstrap the application with sudo firezone-ctl reconfigure. This will initialize config files, set up needed services and generate the default configuration.
• Edit the default configuration located at /etc/firezone/firezone.rb. We’ve chosen sensible defaults that should be a good starting point for most installations. For production installations, you’ll want to specify a valid external URL and enable ACME for certificate issuance and renewal:

• See the complete configuration file reference for more details.
• Reconfigure the application to pick up the new changes: sudo firezone-ctl reconfigure.
• Finally, create an admin user with sudo firezone-ctl create-or-reset-admin. The login credentials will be printed to the console output.
• Now you should be able to sign in to the web UI at the URL you specified in step 5 above, e.g. https://firezone.example.com

Custom Reverse Proxy

Introduction​

Firezone comes with a bundled Nginx reverse proxy, however, in some cases you might want to deploy your own server such as when using behind your own load balancer.

Prerequisites​

Below you will find the requirements in order to setup Firezone with a custom reverse proxy.

Firezone configuration requirements​

• Disable the bundled Nginx by setting default['firezone']['nginx']['enabled'] to false in the config file.
• If you have any immediate proxies between your primary reverse proxy and the Firezone web app, add their IPs to default['firezone']['phoenix']['external_trusted_proxies']. Because of the way the X-Forwarded-For header works, this is needed to parse the actual client’s IP address to prevent IP spoofing.

Proxy requirements​

• All your proxies need to configure the X-Forwarded-For header as explained here
• Your proxy should also set the X-Forwarded-Proto to https.
• Your proxy (or another downstream proxy) must terminate SSL since we enforce secure cookies.
• Firezone requires the use of WebSockets to establish realtime connections. We recommended following your proxy’s specific documentation for supporting WebSockets as each proxy varies. In general, your proxy needs to be able to proxy HTTP 1.1 connections, and the Firezone web app expects the following headers to be set:
  • Connection: upgrade
  • Upgrade: websocket

Security considerations​

In addition to the headers above, we recommend adding the following headers for security purposes:

• X-XSS-Protection: 1; mode=block
• X-Content-Type-Options nosniff
• Referrer-Policy no-referrer-when-downgrade
• Content-Security-Policy: default-src 'self' ws: wss: http: https: data: blob: 'unsafe-inline'; frame-ancestors 'self';
• Permissions-Policy: interest-cohort=()

Since the upstream Firezone web app expects plain HTTP traffic, any requests the proxy forwards is sent over HTTP and thus is not encrypted. In most cases, the reverse proxy is installed in a trusted network, and this is not an issue. But the connection between your trusted proxy and the Firezone web app spans an untrusted network (such as the Internet), you may want to leave the bundled nginx proxy enabled for SSL termination, and set up your custom reverse proxy to proxy to that instead.

Example configurations​

• Apache
• Traefik
• HAProxy

These configurations are written to be as simple as possible. They’re designed to function as a simple template which you can customize further to suit your needs.

If you have a working configuration for a different reverse proxy or a different version of an existing one we appreciate any contribution to expand the examples for the community.

Apache

The following are example apache configurations with and without SSL termination.

These expect the apache to be running on the same host as Firezone and default['firezone']['phoenix']['port'] to be 13000.

Without SSL termination​

Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.

<server-name> needs to be replaced with your domain name.

This configuration needs to be placed in /etc/sites-available/<server-name>.conf

and activated with a2ensite <server-name>

LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so
ServerName ProxyPassReverse “/” “http://127.0.0.1:13000/” ProxyPass “/” “http://127.0.0.1:13000/” RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) “ws://127.0.0.1:13000/$1” [P,L]

With SSL termination​

This configuration builds on the one above and uses Firezone’s auto-generated self-signed certificates.

LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so
LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so
LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so
Listen 443
ServerName RequestHeader set X-Forwarded-Proto “https” ProxyPassReverse “/” “http://127.0.0.1:13000/” ProxyPass “/” “http://127.0.0.1:13000/” RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) “ws://127.0.0.1:13000/$1” [P,L] SSLEngine On SSLCertificateFile “/var/opt/firezone/ssl/ca/acme-test.firez.one.crt” SSLCertificateKeyFile “/var/opt/firezone/ssl/ca/acme-test.firez.one.key”

Traefik

The following are examples for configuring the Traefik proxy as a reverse proxy for Firezone.

In these examples, we assume Traefik is deployed using Docker on the same host as Firezone. For this to work, you’ll need to make sure Firezone’s phoenix app is bound to port 13000 on the Docker interface address and external_trusted_proxies is set properly:

Without SSL termination​

Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.

Use the following docker-compose.yml and rules.yml files to configure Traefik:

docker-compose.yml

version: ‘3’
services:
reverse-proxy:
#network_mode: “host”
# The official v2 Traefik docker image
image: traefik:v2.8
# Enables the web UI and tells Traefik to listen to docker
command:
– “–providers.docker”
– “–providers.file.filename=rules.yml”
– “–entrypoints.web.address=:80”
– “–entrypoints.web.forwardedHeaders.insecure”
– “–log.level=DEBUG”
extra_hosts:
– “host.docker.internal:host-gateway”
ports:
# The HTTP port
– “80:80”
volumes:
# So that Traefik can listen to the Docker events
– /var/run/docker.sock:/var/run/docker.sock
– “./rules.yml:/rules.yml”

rules.yml

http:
routers:
test:
entryPoints:
– “web”
service: test
rule: “Host(44.200.42.78)”
services:
test:
loadBalancer:
servers:
– url: “http://host.docker.internal:13000”

Now you should be able to start the Traefik proxy with docker compose up.

With SSL termination​

This configuration uses Firezone’s auto-generated self-signed certificates.

SSL docker-compose.yml

services:
reverse-proxy:
#network_mode: “host”
# The official v2 Traefik docker image
image: traefik:v2.8
# Enables the web UI and tells Traefik to listen to docker
command:
– “–providers.docker”
– “–providers.file.filename=rules.yml”
– “–entrypoints.web.address=:443”
– “–entrypoints.web.forwardedHeaders.insecure”
– “–log.level=DEBUG”
extra_hosts:
– “host.docker.internal:host-gateway”
ports:
# The HTTP port
– “443:443”
volumes:
# So that Traefik can listen to the Docker events
– /var/run/docker.sock:/var/run/docker.sock
– “./rules.yml:/rules.yml”
– /var/opt/firezone/ssl/ca:/ssl:ro

HAProxy

The following is an example reverse proxy configuration for HAProxy proxy. We assume default['firezone']['phoenix']['port'] to be 13000 and the proxy running on the same host as the Firezone app.

Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.

You can also configure HAProxy to handle the SSL termination as explained here but take into account that the pem file expected by ssl crt option needs to contain both the crt and key file.

Authenticate

Firezone can be configured to require authentication before users can generate or download device configuration files. Optionally, periodic re-authentication can also be required for users to maintain their VPN session.

Firezone supports the following authentication methods:

• Local email/password: Enabled by default. A time-based one time password (TOTP) can optionally be configured to add an additional authentication factor.
• Single Sign-On (SSO): Enables users to sign in using their credentials from Okta, Google, Azure AD, or any service supporting the OpenID Connect (OIDC) protocol.

Integrate A SSO Provider​

We’ve included instructions on how to set up Firezone with several popular identity providers:

• Okta
• Azure Active Directory
• Google
• Onelogin

If your identity provider is not listed above, but has a generic OIDC connector, please consult their documentation to find instructions on obtaining the config settings required. Instructions on setting up Firezone with a generic OIDC provider can be found here.

Open a Github Issue to request documentation or submit a pull request to add documentation for your provider. If you require assistance in setting up your OIDC provider, please join the Firezone Slack group.

The OIDC Redirect URL​

For each OIDC provider a corresponding URL is created for redirecting to the configured provider’s sign-in URL. The URL format is https://firezone.example.com/auth/oidc/PROVIDER where PROVIDER is the OIDC key for that particular provider.

For example, the OIDC config below

default[‘firezone’][‘authentication’][‘oidc’] = {
google: {
# …
},
okta: {
# …
}

would generate the following URLs:

• https://firezone.example.com/auth/oidc/google
• https://firezone.example.com/auth/oidc/okta

These URLs could then be distributed by an Admin directly to end users to navigate to the appropriate identity provider login page to authenticate to Firezone.

Enforce Periodic Re-authentication​

Periodic re-authentication can be enforced by changing the setting in settings/security. This can be used to ensure a user must sign in to Firezone periodically in order to maintain their VPN session.

You can set the session length to a minimum of 1 hour and maximum of 90 days. Setting this to Never disables this setting, allowing VPN sessions indefinitely. This is the default.

Re-authentication​

To re-authenticate an expired VPN session, a user will need to turn off their VPN session and sign in to the Firezone portal (URL specified during deployment ).

See detailed Client Instructions on how to re-authenticate your session here.

VPN Connection Status​

A user’s connection status is shown on the Users page under the table column VPN Connection. The connection statuses are:

• ENABLED – The connection is enabled.
• DISABLED – The connection is disabled by an administrator or OIDC refresh failure.
• EXPIRED – The connection is disabled due to authentication expiration or a user has not signed in for the first time.

Local Authentication

By default, Firezone will use local email / password for authenticating users to the Firezone portal. Administrators can add users and assign their passwords on /users page.

Multi-Factor Authentication

Multi-factor authentication (MFA) can be added directly through Firezone or by adding an additional factor directly through your identity provider.

MFA with Firezone​

Firezone currently supports using a time-based one time password (TOTP) as an additional factor. This is supported with the local authentication method only; for SSO authentication we recommend enabling your provider’s MFA functionality as described below.

Admins can visit /settings/account/register_mfa in the admin portal to generate a QR code to be scanned by your authenticator app.

Unprivileged users can visit /user_account/register_mfa after logging into the user portal.

MFA with Identity Provider​

Most identity providers support additional authentication factors in addition to email/password. Consult your provider’s documentation to enforce an additional factor. We have included links to a few common providers below:

• Okta
• Azure AD
• Google
• Onelogin

Okta

Firezone supports Single Sign-On (SSO) using Okta through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:

• discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.
• client_id: The client ID of the application.
• client_secret: The client secret of the application.
• 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/).
• response_type: Set to code.
• 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.
• label: The button label text that shows up on your Firezone login screen.

Step 1 – Create Okta App Integration​

This section of the guide is based on Okta’s documentation.

In the Admin Console, go to Applications > Applications and click Create App Integration. Set Sign-in method to OICD – OpenID Connect and Application type to Web application.

On the following screen, configure the following settings:

• App Name: Firezone
• App logo: Firezone logo (save link as).
• Grant Type: Check the Refresh Token box. This ensures Firezone syncs with the identity provider and VPN access is terminated once the user is removed.
• Sign-in redirect URIs: Add your Firezone EXTERNAL_URL + /auth/oidc/okta/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/) as an entry to Authorized redirect URIs.
• Assignments: Limit to the groups you wish to provide access to your Firezone instance.

Once settings are saved, you will be given a Client ID, Client Secret, and Okta Domain. These 3 values will be used in Step 2 to configure Firezone.

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 okta_domain.

Using Okta as the SSO identity provider

default[‘firezone’][‘authentication’][‘oidc’] = {
okta: {
discovery_document_uri: “https:///.well-known/openid-configuration”,
client_id: “”,
client_secret: “”,
redirect_uri: “https://firezone.example.com/auth/oidc/okta/callback/”,
response_type: “code”,
scope: “openid email profile offline_access”,
label: “Okta”
}
}

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

Restricting Access to Certain Users​

Okta can limit the users with access to the Firezone app. To do this, go to the Assignments tab of the Firezone App Integration in your Okta Admin Console.

Azure Active Directory

Firezone supports Single Sign-On (SSO) using Azure Active Directory 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/azure/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.

Obtain Config Settings​

This guide is adapted from the Azure Active Directory documentation.

Navigate to the Azure Active Directory page on the Azure portal. Select the App registrations link under the Manage menu, click New Registration, and register after entering the following:

1. Name: Firezone
2. Supported account types: (Default Directory only - Single tenant)
3. Redirect URI: This should be your firezone EXTERNAL_URL + /auth/oidc/azure/callback/ (e.g. https://firezone.example.com/auth/oidc/azure/callback/). Make sure you include the trailing slash. This will be the redirect_uri value.

After registering, open the details view of the application and copy the Application (client) ID. This will be the client_id value. Next, open the endpoints menu to retrieve the OpenID Connect metadata document. This will be the discovery_document_uri value.

Next, select the Certificates & secrets link under the Manage menu and create a new client secret. Copy the client secret – this will be the client_secret value.

Lastly, select the API permissions link under the Manage menu, click Add a permission, and select Microsoft Graph. Add email, openid, offline_access and profile to the required permissions.

Integrate With Firezone​

Edit /etc/firezone/firezone.rb to include the options below.

Using Azure Active Directory as the SSO identity provider

default[‘firezone’][‘authentication’][‘oidc’] = {
azure: {
discovery_document_uri: “https://login.microsoftonline.com//v2.0/.well-known/openid-configuration”,
client_id: “”,
client_secret: “”,
redirect_uri: “https://firezone.example.com/auth/oidc/azure/callback/”,
response_type: “code”,
scope: “openid email profile offline_access”,
label: “Azure”
}
}

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

Restricting Access to Certain Members​

Azure AD allows admins to restrict app access to a subset of users within your organization. See Microsoft’s documentation for more information on how to do this.

Google

Firezone supports Single Sign-On (SSO) using Google Workspace and Cloud Identity 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/google/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 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

Obtain Config Settings​

Step 1 – OAuth Config Screen​

If this is the first time you are creating a new OAuth client ID, you will be asked to configure a consent screen.

IMPORTANT: Select Internal for user type. This ensures only accounts belonging to users in your Google Workspace Organization can create device configs. DO NOT select External unless you want to enable anyone with a valid Google Account to create device configs.

On the App information screen:

1. App name: Firezone
2. App logo: Firezone logo (save link as).
3. Application home page: the URL of your Firezone instance.
4. Authorized domains: the top level domain of your Firezone instance.

Step 2 – Create OAuth Client IDs​

This section is based off Google’s own documentation on setting up OAuth 2.0.

Visit the Google Cloud Console Credentials page page, click + Create Credentials and select OAuth client ID.

On the OAuth client ID creation screen:

1. Set Application Type to Web application
2. Add your Firezone EXTERNAL_URL + /auth/oidc/google/callback/ (e.g. https://firezone.example.com/auth/oidc/google/callback/) as an entry to Authorized redirect URIs.

After creating the OAuth client ID, you will be given a Client ID and Client Secret. These will be used together with the redirect URI in the next step.

Onelogin

Firezone supports Single Sign-On (SSO) using OneLogin 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/onelogin/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 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.

Obtain Config Settings​

Step 1 – Configure Custom Connector​

Create a new OIDC connector by visiting Appliances > Custom Connectors.

1. App name: Firezone
2. Icon: Firezone logo or Firezone icon (save link as).
3. Sign on method: select OpenID Connect
4. Redirect URI: Add your Firezone <EXTERNAL_URL> + /auth/oidc/onelogin/callback/ (e.g. https://firezone.example.com/auth/oidc/onelogin/callback/

Step 2 – Configure the OIDC Application​

Next, click Add App to Connector to create an OIDC application. Visit the SSO tab, then change the token endpoint authentication method to POST.

You will find the values for the config settings required by Firezone on this page as well.

Generic OIDC Provider

The example below details the config settings required by Firezone to enable SSO through a generic OIDC provider. The configuration file can be found at /etc/firezone/firezone.rb. To pick up changes, run firezone-ctl reconfigure to update the application.

The following config settings are 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/google/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 or openid email profile offline_access depending on the provider.
7. label: The button label text that shows up on your Firezone login screen.

Configure

Firezone leverages Chef Omnibus to handle release packaging, process supervision, log management, and more.

The main configuration file is written in Ruby and can be found at /etc/firezone/firezone.rb. Changing this file requires re-running sudo firezone-ctl reconfigure which triggers Chef to pick up the changes and apply them to the running system.

For an exhaustive list of configuration variables and their descriptions, see the configuration file reference.

Manage Installation

Your Firezone installation can be managed via the firezone-ctl command, as shown below. Most subcommands require prefixing with sudo.

root@demo:~# firezone-ctl
I don’t know that command.
omnibus-ctl: command (subcommand)
General Commands:
cleanse
Delete all firezone data, and start from scratch.
create-or-reset-admin
Resets the password for admin with email specified by default[‘firezone’][‘admin_email’] or creates a new admin if that email doesn’t exist.
help
Print this help message.
reconfigure
Reconfigure the application.
reset-network
Resets nftables, WireGuard interface, and routing table back to Firezone defaults.
show-config
Show the configuration that would be generated by reconfigure.
teardown-network
Removes WireGuard interface and firezone nftables table.
force-cert-renewal
Force certificate renewal now even if it hasn\’t expired.
stop-cert-renewal
Removes cronjob that renews certificates.
uninstall
Kill all processes and uninstall the process supervisor (data will be preserved).
version
Display current version of Firezone
Service Management Commands:
graceful-kill
Attempt a graceful stop, then SIGKILL the entire process group.
hup
Send the services a HUP.
int
Send the services an INT.
kill
Send the services a KILL.
once
Start the services if they are down. Do not restart them if they stop.
restart
Stop the services if they are running, then start them again.
service-list
List all the services (enabled services appear with a *.)
start
Start services if they are down, and restart them if they stop.
status
Show the status of all the services.
stop
Stop the services, and do not restart them.
tail
Watch the service logs of all enabled services.
term
Send the services a TERM.
usr1
Send the services a USR1.
usr2
Send the services a USR2.

Upgrade

Upgrading Firezone will disconnect all VPN sessions and require shutting down the Web UI. We recommend a maintenance window of about an hour in case anything goes wrong during the upgrade.

To upgrade Firezone, follow these steps:

1. If not setup already, install our package repository based on your distro’s package format:
   • deb packages
   • rpm packages
2. Upgrade the firezone package using your distro’s package manager.
3. Run firezone-ctl reconfigure to pick up the new changes.
4. Run firezone-ctl restart to restart services.

Occasionally problems arise. If you hit any, please let us know by filing an issue.

Upgrading from < 0.5.0 to >= 0.5.0​

0.5.0 introduces a few breaking changes and configuration updates that will need to be addressed. Read more below.

Bundled Nginx non_ssl_port (HTTP) requests removed​

0.5.0 and above removes the force_ssl and non_ssl_port settings for Nginx. SSL is required for Firezone to function; if you’re using (or would like to use) your own reverse proxy, we recommend disabling the bundle Nginx service by setting default['firezone']['nginx']['enabled'] = false and pointing your reverse proxy directly to the Phoenix app on port 13000 (by default).

Read more about setting up a custom reverse proxy here.

ACME protocol support​

0.5.0 introduces ACME protocol support for automatically renewing SSL certificates with the bundled Nginx service. To enable,

• Make sure default['firezone']['external_url'] contains a valid FQDN that resolves to your server’s public IP address.
• Ensure port 80/tcp is reachable
• Enable ACME protocol support with default['firezone']['ssl']['acme']['enabled'] = true in your config file.

Overlapping egress rule destinations​

Firezone 0.5.0 removes the ability to add rules with overlapping destinations. When upgrading to 0.5.0, our migration script will automatically detect these cases and keep only the rules whose destination encompasses the other rule. If this is OK, there is nothing you need to do.

Otherwise, we recommend modifying your ruleset to eliminate these cases before upgrading.

Preconfigured Okta and Google SSO​

Firezone 0.5.0 removes support for the old-style Okta and Google SSO configuration in favor of the new, more flexible OIDC-based configuration. If you have any configuration under the default['firezone']['authentication']['okta'] or default['firezone']['authentication']['google'] keys, you need to migrate these to our OIDC-based configuration using the guide below.

Existing Google OAuth configuration​

Remove these lines containing the old Google OAuth configs from your configuration file located at /etc/firezone/firezone.rb

default[‘firezone’][‘authentication’][‘google’][‘enabled’]
default[‘firezone’][‘authentication’][‘google’][‘client_id’]
default[‘firezone’][‘authentication’][‘google’][‘client_secret’]
default[‘firezone’][‘authentication’][‘google’][‘redirect_uri’]

Then, follow the instructions here to configure Google as an OIDC provider.

Existing Okta OAuth configuration​

Remove these lines containing the old Okta OAuth configs from your configuration file located at /etc/firezone/firezone.rb

default[‘firezone’][‘authentication’][‘okta’][‘enabled’]
default[‘firezone’][‘authentication’][‘okta’][‘client_id’]
default[‘firezone’][‘authentication’][‘okta’][‘client_secret’]
default[‘firezone’][‘authentication’][‘okta’][‘site’]

Then, follow the instructions here to configure Okta as an OIDC provider.

Upgrading from 0.3.x to >= 0.3.16​

Follow the instructions below based on your current version and setup:

I have an existing OIDC integration​

Upgrading to >= 0.3.16 requires the offline_access scope for some OIDC providers to obtain a refresh token. This ensures Firezone syncs with the identity provider and VPN access is terminated once the user is removed. Previous versions of Firezone do not have this capability. Users who are removed from your identity provider will still have active VPN sessions in some cases.

For OIDC providers that support the offline_access scope, you will need to add offline_access to the scope parameter of your OIDC config. The Firezone configuration file can be found at /etc/firezone/firezone.rb and requires running firezone-ctl reconfigure to pick up the changes.

If Firezone is able to successfully retrieve the refresh token, you will see the OIDC Connections heading in the user details page of the web UI for users authenticated through your OIDC provider.

If this does not work, you will need to delete your existing OAuth app and repeat the OIDC setup steps to create a new app integration .

I have an existing OAuth integration​

Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the instructions here to migrate to OIDC.

I have not integrated an identity provider​

No action needed. You can follow the instructions here to enable SSO through an OIDC provider.

Upgrading from 0.3.1 to >= 0.3.2​

The configuration option default['firezone']['fqdn'] has been removed in favor of default['firezone']['external_url']. Please set this to the publicly-accessible URL of your Firezone web portal. If left unspecified it will default to https:// + the FQDN of your server.

Reminder, the configuration file can be found at /etc/firezone/firezone.rb. For an exhaustive list of configuration variables and their descriptions, see the configuration file reference.

Upgrading from 0.2.x to 0.3.x​

Starting with version 0.3.0, Firezone no longer stores device private keys on the Firezone server. Any existing devices should continue to function as-is, but you will not be able to re-download or view these configurations in the Firezone Web UI.

Upgrading from 0.1.x to 0.2.x​

Firezone 0.2.x contains some configuration file changes that will need to be handled manually if you’re upgrading from 0.1.x. Run the commands below as root to perform the needed changes to your /etc/firezone/firezone.rb file.

Uninstall

To completely remove Firezone and its configuration files, run the uninstall.sh script:

sudo /bin/bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/uninstall.sh)”