Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Secure user access to cloud resources based on WireGuard VPN

Written by
Updated at August 14, 2025

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:

  1. Get your cloud ready.
  2. Set up your resource environment.
  3. Register your domain.
  4. Set up Firezone and Keycloak.
  5. Set up Keycloak integration with Firezone.
  6. Configure Firezone.
  7. Test Firezone.

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

Get your cloud ready

Sign up for Yandex Cloud and create a billing account:

  1. Navigate to the management console and log in to Yandex Cloud or create a new account.
  2. 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.

Learn more about clouds and folders here.

The infrastructure support costs include:

Set up your resource environment

  1. Install Terraform.

  2. If do not have the Yandex Cloud CLI yet, install it and sign in as a user.

  3. Create a service account:

    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.

    By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command 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

  4. Assign the administrator role for the folder to the service account:

    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>

  5. Set up a CLI profile to run operations on behalf of the service account:

    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

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

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

    1. Navigate to the main directory:

      cd main

    2. Initialize Terraform:

      terraform init

    3. Preview the list of new cloud resources:

      terraform plan

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

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

  1. Once you set up the Firezone and Keycloak VMs, navigate to the keycloak-config directory.

    cd ../keycloak-config

  2. Initialize Terraform:

    terraform init

  3. Preview the list of new cloud resources:

    terraform plan

  4. Create resources:

    terraform apply

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

  1. 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.
  2. 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.
  3. Navigate to the SETTINGS / Defaults section.
  4. 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.
  5. 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.
  6. You can also change your clients keepalive and MTU settings. For example, you can increase MTU to 1440 bytes from the default 1280 bytes.
  7. Click Save to apply the changes.
  8. Navigate to the SETTINGS / Security section.
  9. Disable Allow unprivileged device configuration to keep users from changing VPN client network settings via the Firezone web UI.
  10. Activate Auto disable VPN. This will automatically close VPN connections of users removed from the identity provider, e.g., Keycloak.
  11. Click Add OpenID Connect Provider and add Keycloak.
  12. 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.
  13. Click Save in the OIDC Configuration section to apply the changes.

Test Firezone

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

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

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

  4. Once you logged in Firezone as a test user, add your VPN client device by clicking Add Device.

  5. In the window that opens, you can change the device name and add its description. Click Generate Configuration.

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

  7. Click Import tunnel(s) from file in the WireGuard client to add a new VPN tunnel using the configuration file you downloaded.

  8. Click Activate to activate the tunnel.

  9. 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:

  1. On your remote PC, navigate to the keycloak-config directory and run the terraform destroy command.
  2. Next, navigate to the main directory and run terraform destroy again.
Previous
Creating a tunnel between two subnets with OpenVPN Access Server
Next
Configuring a secure GRE tunnel over IPsec