Secure user access to cloud resources based on WireGuard VPN

Written by

Updated at May 7, 2025

Get your cloud ready
- Required paid resources
Set up your resource environment
Register your domain
Set up Firezone and Keycloak
Set up Keycloak integration with Firezone
Configure Firezone
Test Firezone
How to delete the resources you created

In this tutorial, we will set up WireGuard VPN access to your cloud resources with Firezone: an open-source VPN solution supporting various identity providers for single sign-on. We will also use the Keycloak access management software.

In our scenario, we will create a Yandex Cloud infrastructure and set up a WireGuard VPN access as shown in the diagram below:

Diagram elements:

Name	Description
Firezone VM	VM running Firezone WireGuard VPN software
Database cluster	Managed Service for PostgreSQL supporing Firezone and Keycloak VMs
Keycloak VM	VM running the Keycloak single sign-on operator supporting authentication of different identity providers, e.g., Active Directory

For more information, see the project repository.

To set up and test Firezone:

If you no longer need the resources you created, delete them.

Get your cloud ready

Navigate to the management console and log in to Yandex Cloud or register a new account.
On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Required paid resources

The infrastructure support costs include:

Fee for continuously running VMs (see Yandex Compute Cloud pricing).
Fee for IP addresses and outbound traffic (see Yandex Virtual Private Cloud pricing).
Fee for using Managed Service for PostgreSQL (see Yandex Managed Service for PostgreSQL pricing).
Fee for public DNS queries and DNS zones (see Cloud DNS pricing).

Set up your resource environment

Install Terraform.
If do not have the Yandex Cloud CLI yet, install it and sign in as a user.
Create a service account:
Management console

CLI
1. In the management console, select the folder where you want to create your service account.
2. In the list of services, select Identity and Access Management.
3. Click Create service account.
4. Specify the service account name, e.g., sa-firezone.
5. Click Create.
The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To create a service account, run the command below and specify the sa-firezone name:
```
yc iam service-account create --name sa-firezone
```
Where --name is the service account name.

Result:
```
id: ajehr0to1g8b********
folder_id: b1gv87ssvu49********
created_at: "2023-07-06T09:00:00.665153755Z"
name: sa-firezone
```
Assign the administrator role for the folder to the service account:
Management console

CLI
1. On the management console home page, select a folder.
2. Navigate to the Access bindings tab.
3. Find the sa-firezone account in the list and click .
4. Click Edit roles.
5. In the dialog that opens, click Add role and select the admin role.
Run this command:
```
yc resource-manager folder add-access-binding <folder_ID> \
  --role admin \
  --subject serviceAccount:<service_account_ID>
```
Set up a CLI profile to run operations on behalf of the service account:
CLI
1. Create an authorized key for the service account and save it to the file:
  yc iam key create \ --service-account-id <service_account_ID> \ --folder-id <ID_of_folder_with_service_account> \ --output key.json
  Where:
  - --service-account-id: Service account ID.
  - --folder-id: Service account folder ID.
  - --output: Authorized key file name.
  Result:
  id: aje8nn871qo4******** service_account_id: ajehr0to1g8b******** created_at: "2023-07-06T09:03:00.479156798Z" key_algorithm: RSA_2048
2. Create a CLI profile to run operations on behalf of the service account:
  yc config profile create sa-firezone
  Result:
  Profile 'sa-firezone' created and activated
3. Configure the profile:
  yc config set service-account-key key.json
  Where service-account-key is the service account authorized key file name.
4. Export the access key to the environment variable:
  export YC_TOKEN=$(yc iam create-token)

Register your domain

To use Firezone and Keycloak, you need to register a domain. Make sure to delegate this domain to Yandex Cloud by specifying the ns1.yandexcloud.net and ns2.yandexcloud.net server addresses in the NS records of your domain zone registrar.

Set up Firezone and Keycloak

On your PC, clone the yandex-cloud-examples/yc-remote-acess-vpn-with-wireguard-firezone repository from Yandex Cloud Security Solution Library and navigate to the yc-remote-acess-vpn-with-wireguard-firezone directory:
```
git clone https://github.com/yandex-cloud-examples/yc-remote-acess-vpn-with-wireguard-firezone.git

cd yc-remote-acess-vpn-with-wireguard-firezone
```

Describe the resources you plan to create in the variables.tf file:

In the domain section, specify your domain’s first and second levels separated by a dot for the Firezone and Keycloak VMs. In this example, we will use example.com as a domain.
In the folder_id section, specify your resource folder ID, e.g., b1grj7grr1kn********.
In the vpc_id section, specify your cloud network ID, e.g., enp48c1ndilt********.
In the trusted_ip_for_mgmt section, list public and subnet IP addresses allowed to access the Firezone and Keycloak VMs over SSH, e.g., ["A.A.A.A/32", "B.B.B.0/24"].
In the admin_email section, specify the admin email address that will be used to log in to the Firezone admin web UI, e.g., admin@example.com.
In the email section specify the test user email address that will be added to Firezone after Keycloak authentication, e.g., user@example.com.
You can leave other properties unchanged or edit them as you see fit, except for image_folder_id and image_name.

Warning

Using this configuration, you are going to deploy a resource-heavy infrastructure.
Make sure you have sufficient quotas in Yandex Cloud.

See the required resource reference

Resource	Amount
Virtual machines	2
VM vCPUs	4
VM RAM	12 GB
Disks	2
SSD size	110 GB
Subnets	2
Static public IP addresses	2
Security groups	2
Certificate Manager certificate	1
DNS zone	1
Managed Service for PostgreSQL cluster	1
SSD storage capacity for PostgreSQL cluster	10 GB
Number of vCPUs for PostgreSQL cluster	2
Amount of RAM for PostgreSQL cluster	8

Terraform

Navigate to the main directory:
```
cd main
```
Initialize Terraform:
```
terraform init
```
Preview the list of new cloud resources:
```
terraform plan
```
Create resources:
```
terraform apply
```
Wait for the process to complete. It may take up to 30 minutes to process a request for a Let's Encrypt certificate.

Once the process is complete, you will see Firezone and Keycloak web UI URL addresses and admin credentials. You can also see this information by running the terraform output command.

Outputs:

firezone_admin_credentials = <sensitive>
firezone_url = "https://vpn.example.com"
keycloak_admin_credentials = <sensitive>
keycloak_url = "https://kc.example.com:8443/admin"

To display sensitive information, such as passwords, specify the required variable name in the terraform output command, for example:

terraform output firezone_admin_credentials

Result:

{
   "admin_email" = "admin@example.com"
   "admin_password" = "7fVN********"
}

Set up Keycloak integration with Firezone

Terraform

Once you set up the Firezone and Keycloak VMs, navigate to the keycloak-config directory.
```
cd ../keycloak-config
```
Initialize Terraform:
```
terraform init
```
Preview the list of new cloud resources:
```
terraform plan
```
Create resources:
```
terraform apply
```
Once the process is complete, you will see the Firezone and Keycloak integration information and test user credentials you will need to test Keycloak single sign-on and the VPN connection. You can also see this information by running the terraform output command.
```
Outputs:

keycloak_config_for_firezone = <sensitive>
test_user_credentials = <sensitive>
```
To display sensitive information, such as passwords, specify the required variable in the terraform output command.

Configure Firezone

In your browser, navigate to https://firezone_url, where firezone_url is the Firezone admin web UI URL you saved earlier. To get it again, navigate to the main directory and run terraform output firezone_url. In our example, the address is https://vpn.example.com.
Log in to the Firezone admin web UI using admin credentials you saved earlier. To get them again navigate to the main directory and run terraform output firezone_admin_credentials.
Navigate to the SETTINGS / Defaults section.
In the Allowed IPs field, specify the comma-separated list of cloud subnets (in the IP address/mask format) accessible through the VPN. Example: 192.168.1.0/24, 192.168.2.0/24.
In the DNS Servers field, specify the DNS server addresses that your VPN clients will use.
Example: 192.168.1.2, 192.168.2.2.
If your clients will not use these DNS addresses, delete information in this field.
You can also change your clients keepalive and MTU settings. For example, you can increase MTU to 1440 bytes from the default 1280 bytes.
Click Save to apply the changes.
Navigate to the SETTINGS / Security section.
Disable Allow unprivileged device configuration to keep users from changing VPN client network settings via the Firezone web UI.
Activate Auto disable VPN. This will automatically close VPN connections of users removed from the identity provider, e.g., Keycloak.
Click Add OpenID Connect Provider and add Keycloak.
In the OIDC Configuration section, specify the following settings:
- Config ID: keycloak
- Label: Keycloak
- OIDC scopes: openid email profile offline_access
- Client ID: firezone
- Client secret: client_secret you saved earlier. To get it again, navigate to the keycloak-config and run terraform output keycloak_config_for_firezone. Enter the value without quotes.
- Discovery Document URI: discovery_document_uri you saved earlier. To get it again, navigate to the keycloak-config and run terraform output keycloak_config_for_firezone. Enter the value without quotes.
- Redirect URI: Leave it blank.
- Enable Auto-create users to automatically add authenticated Keycloak users to Firezone.
Click Save in the OIDC Configuration section to apply the changes.

Test Firezone

Install the WireGuard client on your remote PC.

In our example, we will use Windows WireGuard client. For other operating systems, the client UI names may differ.
In your browser, navigate to https://firezone_url, where firezone_url is the Firezone web UI URL you saved earlier. To get it again, navigate to the main directory and run terraform output firezone_url. If you already logged in as admin, Log Out first. Click Sign in with Keycloak. You will be redirected to the Keycloak login page.
Log in with test user credentials you saved earlier. To get them again, navigate to the keycloak-config directory and run terraform output test_user_credentials.
Once you logged in Firezone as a test user, add your VPN client device by clicking Add Device.
In the window that opens, you can change the device name and add its description. Click Generate Configuration.
You will see a window with your device's VPN configuration. Click Download WireGuard Configuration to download the configuration file. The window also contains a QR code you can scan to add a VPN tunnel on Android or iOS.

Warning

Do not close the window before you download the configuration file or scan the QR code because, once you close it, you will not be able to get this information again.
Click Import tunnel(s) from file in the WireGuard client to add a new VPN tunnel using the configuration file you downloaded.
Click Activate to activate the tunnel.
Run ping 192.168.1.1 on your remote PC to check whether the gateway is accessible from the firezone cloud subnet. If ping is successful, it means you are now connected to your cloud infrastructure through the VPN tunnel.
```
Pinging 192.168.1.1 with 32 bytes of data:
Reply from 192.168.1.1: bytes=32 time=67ms TTL=53
```

How to delete the resources you created

To stop paying for the resources you created:

Terraform

On your remote PC, navigate to the keycloak-config directory and run the terraform destroy command.
Next, navigate to the main directory and run terraform destroy again.

Secure user access to cloud resources based on WireGuard VPN

Get your cloud readyGet your cloud ready

Required paid resourcesRequired paid resources

Set up your resource environmentSet up your resource environment

Register your domainRegister your domain

Set up Firezone and KeycloakSet up Firezone and Keycloak

Set up Keycloak integration with FirezoneSet up Keycloak integration with Firezone

Configure FirezoneConfigure Firezone

Test FirezoneTest Firezone

How to delete the resources you createdHow to delete the resources you created

Was the article helpful?

Get your cloud ready

Required paid resources

Set up your resource environment

Register your domain

Set up Firezone and Keycloak

Set up Keycloak integration with Firezone

Configure Firezone

Test Firezone

How to delete the resources you created