Contact UsGet started

Secure user access to cloud resources based on WireGuard VPN

Written by
Updated at November 14, 2024

To set up secure remote VPN access to your cloud resources over WireGuard VPN, use the open-source Firezone solution. To implement Single Sign-On scenarios for users, the solution supports multiple authentication services (Identity Providers). In the example below, we will use the Keycloak identity and access management solution.

In this scenario, you will deploy a cloud infrastructure in Yandex Cloud to set up a remote access VPN based on WireGuard VPN using the following scenario:

Notes to the chart elements:

Name Description
Firezone VM VM with installed Firezone software based on WireGuard VPN to set up VPN access
Database cluster Managed Service for PostgreSQL to run Firezone and Keycloak VMs
Keycloak VM Open-source Keycloak software for user single sign-on authentication in a corporate user identity federation, such as Active Directory

For more information, see the project repository.

To set up Firezone and test it:

  1. Prepare your cloud.
  2. Prepare an environment for deploying the resources.
  3. Prepare a domain.
  4. Deploy 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.

Prepare your cloud

Sign up for Yandex Cloud and create a billing account:

  1. Go to the management console and log in to Yandex Cloud or create an account if you do not have one yet.
  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.

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

Learn more about clouds and folders.

The infrastructure support costs include:

Prepare an environment for deploying the resources

  1. Install Terraform.

  2. If you do not have the Yandex Cloud command line interface 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 a service account.
    2. In the list of services, select Identity and Access Management.
    3. Click Create service account.
    4. Enter a name for the service account, e.g., sa-firezone.
    5. Click Create.

    The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name or --folder-id parameter.

    Run the command below to create a service account, specifying 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 service account the administrator role for the folder:

    1. On the management console home page, select a folder.
    2. Go to the Access bindings tab.
    3. Find the sa-firezone account in the list and click .
    4. Click Edit roles.
    5. Click Add role in the dialog that opens 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 the 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: ID of the folder in which the service account was created.
      • --output: Name of the file with the authorized key.

      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. Set the profile configuration:

      yc config set service-account-key key.json

      Where service-account-keyis the file with the service account authorized key.

    4. Save the access key to the environment variable:

      export YC_TOKEN=$(yc iam create-token)

Prepare a domain

You will need a domain to use for Firezone and Keycloak VMs. Make sure to first delegate this domain to Yandex Cloud from the domain registrar. To do this, specify the addresses of the ns1.yandexcloud.net and ns2.yandexcloud.net servers in your account on your registrar's website.

Deploy Firezone and Keycloak

  1. On your workstation, clone the yandex-cloud-examples/yc-remote-acess-vpn-with-wireguard-firezone repository from Yandex Cloud Security Solution Library and go to the yc-remote-acess-vpn-with-wireguard-firezone scenario 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. Edit the variables.tf file, specifying the properties of the resources you are deploying:

    • In the domain section, specify your domain name (second and first-level, separated with a period) for the Firezone and Keycloak VMs. In this example, we use example.com as domain.
    • In the folder_id section, specify the ID of the folder to host your resources, such as b1grj7grr1kn********.
    • In the vpc_id section, specify the ID of the cloud network to host your resources, such as enp48c1ndilt********.
    • In the trusted_ip_for_mgmt section, list public IPs/subnets to allow SSH connections to the Firezone and Keycloak VMs from, e.g., ["A.A.A.A/32", "B.B.B.0/24"].
    • In the admin_email section, enter the admin email address (username) to access the Firezone admin web interface, e.g., admin@example.com.
    • In the email section enter the user email address to add to Firezone after successful authentication in Keycloak, e.g., user@example.com.
    • You can leave other properties unchanged or edit them as you see fit, except image_folder_id and image_name.

    Warning

    The values set in the file are intended for deploying resource-intensive infrastructures.
    Check out the cloud quotas to be able to deploy your resources.

    See reference information about the amount of resources
    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. Go to the main directory:

      cd main

    2. Initialize Terraform:

      terraform init

    3. Check the list of cloud resources you are about to create:

      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. When it is over, the command line will output the URL addresses for connection to the Firezone and Keycloak web interfaces, as well as the Firezone and Keycloak admin credentials. Later on, you can view 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 get the sensitive value, specify the parameter name in the terraform output command, such as:

      terraform output firezone_admin_credentials

      Result:

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

Set up Keycloak integration with Firezone

  1. After you deploy the Firezone and Keycloak VMs, go to the keycloak-config directory to set up Keycloak for intergration with Firezone and single sign-on.

    cd ../keycloak-config

  2. Initialize Terraform:

    terraform init

  3. Check the list of cloud resources you are about to create:

    terraform plan

  4. Create resources:

    terraform apply

  5. Once the terraform apply process is complete, the command line will show information for Firezone and Keycloak integration setup and test user credentials to test SSO in Keycloak and connect to the VPN. Later on, you can view this information by running the terraform output command.

    Outputs:

keycloak_config_for_firezone = <sensitive>
test_user_credentials = <sensitive>

    To output the sensitive value, specify it in the terraform output command.

Configure Firezone

  1. In your browser, go to https://firezone_url, where firezone_url is the terraform output firezone_url command output in the main directory (in our case, it is https://vpn.example.com).
  2. Log in to the Firezone admin interface using the admin credentials from the terraform output firezone_admin_credentials command output in the main directory.
  3. Go to the SETTINGS / Defaults section to change the default values.
  4. In the Allowed IPs field, specify the cloud subnet IP addresses (as a comma-separated list of subnet IPs/masks) for VPN clients to route traffic to a VPN tunnel, e.g.: 192.168.1.0/24, 192.168.2.0/24.
  5. In the DNS Servers field, specify the DNS server addresses to be used by the VPN clients, e.g.: 192.168.1.2, 192.168.2.2.
    If these DNS addresses are not to be reassigned on the client side, delete information in this field.
  6. You can also change the default properties for the VPN client keepalive interval and MTU size. The default MTU is 1280 bytes; you can increase it to 1440 bytes.
  7. Click Save to apply the settings.
  8. Go to the SETTINGS / Security section to change the security settings.
  9. Disable the Allow unprivileged device configuration setting so that the users cannot change the VPN client network settings through the Firezone user web interface.
  10. Activate the Auto disable VPN setting. This will allow disabling a user's VPN connections when the user is removed in the Identity Provider (in this case, Keycloak).
  11. Click Add OpenID Connect Provider to add Keycloak.
  12. In the OIDC Configuration section, fill in the following fields:
    • Config ID: keycloak
    • Label: Keycloak
    • OIDC scopes: openid email profile offline_access
    • Client ID: firezone
    • Client secret: client_secret from the terraform output keycloak_config_for_firezone output in the keycloak-config directory (specify the value without quotes).
    • Discovery Document URI: discovery_document_uri from the terraform output keycloak_config_for_firezone output in the keycloak-config directory (specify the value without quotes).
    • Redirect URI: Leave it blank.
    • Enable Auto-create users to automatically add users to Firezone after their successful authentication in Keycloak.
  13. Click Save in the OIDC Configuration section to apply the settings.

Test Firezone

  1. Install the WireGuard client from the WireGuard website on your device.

    For further steps to set up the WireGuard client, we will use Windows as an example. For other operating systems, the names of UI elements may differ.

  2. In your browser, go to https://firezone_url, where firezone_url is the terraform output firezone_url command output in the main directory. If you have an active admin session in the Firezone web interface, Log Out first. Click Sign in with Keycloak. You will be redirected to the Keycloak web page for single sign-on.

  3. Log in using the test user credentials from the terraform output test_user_credentials command output in the keycloak-config directory.

  4. After successful authentication in the Firezone web interface as the test user, add a device to establish a VPN connection from. To do this, click Add Device.

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

  6. This will open a window with the device's VPN configuration. Click Download WireGuard Configuration to download the configuration file. You can also use the WireGuard app for Android or iOS to scan a QR code from this page to add a VPN tunnel.

    Warning

    Do not close the window until you download the configuration file or scan the QR code. You will not be able to view the device's VPN configuration in the Firezone web interface once you close the window.

  7. Add a new VPN tunnel (Import tunnel(s) from file) in the WireGuard app using the configuration file you downloaded.

  8. Click Activate to activate the tunnel.

  9. Use ping 192.168.1.1 in the command line on your device to check whether the gateway is accessible from the firezone cloud subnet. You are now connected to the 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 workstation, go to the keycloak-config directory and run the terraform destroy command.
  2. Next, go to the main directory and run terraform destroy again.
Previous
Creating a tunnel between two subnets using OpenVPN Access Server
Next
Creating and configuring a UserGate gateway in firewall mode