Secure user access to cloud resources based on WireGuard VPN
In this tutorial, we will set up WireGuard VPN
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 |
For more information, see the project repository
To set up and test Firezone:
- Get your cloud ready.
- Set up your resource environment.
- Register your domain.
- Set up Firezone and Keycloak.
- Set up Keycloak integration with Firezone.
- Configure Firezone.
- 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:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_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
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
-
If do not have the Yandex Cloud CLI yet, install it and sign in as a user.
-
Create a service account:
Management consoleCLI- In the management console
, select the folder where you want to create your service account. - In the list of services, select Identity and Access Management.
- Click Create service account.
- Specify the service account name, e.g.,
sa-firezone
. - Click Create.
The folder specified in the CLI profile is used by default. You can specify a different folder through 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
- In the management console
-
Assign the administrator role for the folder to the service account:
Management consoleCLI- On the management console home page
, select a folder. - Navigate to the Access bindings tab.
- Find the
sa-firezone
account in the list and click . - Click Edit roles.
- In the dialog that opens, click
Add role and select theadmin
role.
Run this command:
yc resource-manager folder add-access-binding <folder_ID> \ --role admin \ --subject serviceAccount:<service_account_ID>
- On the management console home page
-
Set up a CLI profile to run operations on behalf of the service account:
CLI-
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
-
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
-
Configure the profile:
yc config set service-account-key key.json
Where
service-account-key
is the service account authorized key file name. -
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 theyc-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 useexample.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
andimage_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********" }
- In the
Set up Keycloak integration with Firezone
-
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
, wherefirezone_url
is the Firezone admin web UI URL you saved earlier. To get it again, navigate to themain
directory and runterraform output firezone_url
. In our example, the address ishttps://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 runterraform 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
andMTU
settings. For example, you can increaseMTU
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 thekeycloak-config
and runterraform 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 thekeycloak-config
and runterraform 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.
- Config ID:
- 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
, wherefirezone_url
is the Firezone web UI URL you saved earlier. To get it again, navigate to themain
directory and runterraform 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 runterraform 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 thefirezone
cloud subnet. Ifping
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:
- On your remote PC, navigate to the
keycloak-config
directory and run theterraform destroy
command. - Next, navigate to the
main
directory and runterraform destroy
again.