From 470ff9702c88eabf3bdeb60cb8701377d8c22e04 Mon Sep 17 00:00:00 2001 From: Ad Schellevis Date: Thu, 29 Jun 2023 19:08:14 +0200 Subject: [PATCH] OpenVPN - add new Instances module --- .../how-tos/sslvpn_instance_roadwarrior.rst | 216 +++++++++++++++++ source/manual/how-tos/sslvpn_instance_s2s.rst | 224 ++++++++++++++++++ source/manual/vpnet.rst | 107 ++++++++- 3 files changed, 535 insertions(+), 12 deletions(-) create mode 100644 source/manual/how-tos/sslvpn_instance_roadwarrior.rst create mode 100644 source/manual/how-tos/sslvpn_instance_s2s.rst diff --git a/source/manual/how-tos/sslvpn_instance_roadwarrior.rst b/source/manual/how-tos/sslvpn_instance_roadwarrior.rst new file mode 100644 index 00000000..8fdeda55 --- /dev/null +++ b/source/manual/how-tos/sslvpn_instance_roadwarrior.rst @@ -0,0 +1,216 @@ +================================= +Setup SSL VPN Road Warrior +================================= + +.. image:: images/sslvpn_image_new.png + :width: 100% + +Road Warriors are remote users who need secure access to the companies infrastructure. +OPNsense uses OpenVPN for its SSL VPN Road Warrior setup and offers OTP (One Time Password) +integration with standard tokens and Googles Authenticator. + +.. Tip:: + + Did you know that OPNsense offers two-factor authentication throughout the entire + system? See for more information: :doc:`/manual/two_factor` + +.. Note:: + + For the sample we will use a private IP for our WAN connection. + This requires us to disable the default block rule on wan to allow private traffic. + To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks". + *(Dont forget to save and apply)* + + .. image:: images/block_private_networks.png + + +.. contents:: Index + +---------------- +Before you start +---------------- +Before starting with the configuration of an OpenVPN SSL tunnel you need to have a +working OPNsense installation with a unique LAN IP subnet for each side of your +connection (your local network needs to be different than that of the remote +network). + +.. Note:: + + For the sample we will use a private IP for our WAN connection. + This requires us to disable the default block rule on WAN to allow private traffic. + To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks". + *(Don't forget to save and apply)* + + .. image:: images/block_private_networks.png + + +-------------------------------- +Network topology +-------------------------------- + +The schema below describes the situation we are implementing. One client using an "external" ip address of :code:`10.0.8.2/24` +a firewall we are connecting to at :code:`10.0.8.1/24` constructing a tunnel using :code:`10.2.8.0/24` to reach :code:`192.168.8.0/24`. + +.. nwdiag:: + :scale: 100% + + nwdiag { + + span_width = 90; + node_width = 180; + network { + address = "10.0.8.0/24"; + pclana [label="Roadwarrior\n10.2.8.2",shape="cisco.pc"]; + fw [shape = "cisco.firewall", address="10.0.8.1/24"]; + } + network Ext { + address = "192.168.8.0/24"; + fw [shape = "cisco.firewall", address="192.168.8.1/24"]; + pclanb [label="Server\n192.168.8.20",shape="cisco.pc"]; + } + + } + + + +-------------------------------- +Preparations +-------------------------------- + +..................... +Trust +..................... + + +In order to setup a tunnel on both ends, we need to configure certificates to warrant trust between the client and this server. + +* First we need an **Authority** which we are going to create in :menuselection:`System --> Trust --> Authorities` + + * Select `Create an internal Certificate Authority` + * Choose cryptographic settings and a lifetime (you may want to increase the default as after this time you do need to redistribute certificates to both server and client). + * Add descriptive information for this CA (`Descriptive name`, `City`, `Email`, ..`) + * Set the `Common Name` to something descriptive for this certificate, like "Office-ovpn" + + +* Next generate a **Certficate** for the server using :menuselection:`System --> Trust --> Certificates` + + * Select `Create an internal Certificate` + * Choose the just created authority in `Certificate authority` + * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA) + * Set Type to `Server` + * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here + * Set the `Common Name` to the fqdn of this machine. + +* For the client pc we will create a user and a certificate, from the :menuselection:`System --> Access --> Users` menu. + + * Hit the [+] sign to create a new user, for this test we will call it :code:`test1` + * Check the "Certificate -> Click to create a user certificate" option and hit "save" + * Next step in the certificate window, select "`Create an internal Certificate`" and "save" + + +.. Note:: + + It's a best practice to offer each user it's own certificate using the same common name as the username, although + it is also possible to clients to share a certificate. When adding a certificate from the user manager the CN is automatically + set to its name. In this example we will only authenticate using the certificate, no additional user or password will be required. + + +..................... +Static keys +..................... + +We create a static key and define it's use in :menuselection:`VPN --> OpenVPN --> Instances --> Static Keys`, for this example +select `auth` as mode and click the gear button to generate one. Provide a description for this key. + + + +------------------------------------ +Create a server instance +------------------------------------ + +Now the generic setup is done, we can configure a new server type instance via :menuselection:`VPN --> OpenVPN --> Instances` + +=============================================================== + +======================= ======================================= +Property site B +======================= ======================================= +Role Server +Description MyServer +Protocol UDP (IPv4) +Port number 1194 +Bind address 10.10.8.1 :sup:`1` +Server (IPv4) 10.1.8.0/24 (the tunnel network used) +Certificate choose the prepared server certificate +TLS static key choose the prepared static key +Authentication Local Database :sup:`2` +Strict User/CN Matching [V] :sup:`3` +Local Network 192.168.8.0/24 +======================= ======================================= + +.. admonition:: Note :sup:`1` + + Leave empty to bind to all addresses assigned to this machine or use a loopback address combined with a port forward when + the external address is not static. + +.. admonition:: Note :sup:`2` + + When users are also required to use a one-time-password, just select an authentication server that supports the additional + token. + +.. admonition:: Note :sup:`3` + + Selecting the "Strict User/CN Matching" option warrants only matching user/certificate can login, when sharing a single + vertificate between clients this option needs to be deselected. + + +Next go to :menuselection:`Firewall --> Rules --> WAN` and add a rule to allow traffic on port :code:`1494/UDP` from the other +host. At minimum we should add a rule similar to this one: + +=============================================================== + +======================= ======================================= +Property site B +======================= ======================================= +Interface WAN +Protocol UDP +Destination port range 1194 +======================= ======================================= + +Finally we are going to allow traffic on the tunnel itself by adding a rule to :menuselection:`Firewall --> Rules --> OpenVPN`, +for this example we keep it simple and add one to allow all, in which case we can save the defaults when adding a rule. + + +------------------------------------ +Export client profile +------------------------------------ + +With the server in place it's time to setup the client on OPNsense, for this we go to :menuselection:`VPN --> OpenVPN --> Client Export` +and export a profile for the remote client. + +=================================================================== + +======================= =========================================== +Property Value +======================= =========================================== +Remote Access Server select the Roadwarrior server "MyServer" +Export type File Only :sup:`1` +Hostname 10.10.8.1 +======================= =========================================== + +.. admonition:: Note :sup:`1` + + Most clients support the standard :code:`ovpn` format, when using a tool like Viscosity from Sparklabs (https://www.sparklabs.com/viscosity/) + you can also choose the proper type here. + +Next client on the certificate with link user in the grid below and install the certificate on the client. + + +-------------------------------- +Test connectivity +-------------------------------- + +After connecting the client, use the :menuselection:`VPN: OpenVPN: Connection Status` page to watch the status of the connected +client. It should show the client with byte counters. + +Now try to ping from Site A (:code:`10.0.8.20`) to Site B (:code:`192.168.8.20`). diff --git a/source/manual/how-tos/sslvpn_instance_s2s.rst b/source/manual/how-tos/sslvpn_instance_s2s.rst new file mode 100644 index 00000000..eac0f67f --- /dev/null +++ b/source/manual/how-tos/sslvpn_instance_s2s.rst @@ -0,0 +1,224 @@ +================================= +Setup SSL VPN site to site tunnel +================================= + +Site to site VPNs connect two locations with static public IP addresses and allow +traffic to be routed between the two networks. This is most commonly used to +connect an organization's branch offices back to its main office, so branch users +can access network resources in the main office. + +.. contents:: Index + +---------------- +Before you start +---------------- +Before starting with the configuration of an OpenVPN SSL tunnel you need to have a +working OPNsense installation with a unique LAN IP subnet for each side of your +connection (your local network needs to be different than that of the remote +network). + +.. Note:: + + For the sample we will use a private IP for our WAN connection. + This requires us to disable the default block rule on WAN to allow private traffic. + To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks". + *(Don't forget to save and apply)* + + .. image:: images/block_private_networks.png + + +-------------------------------- +Network topology +-------------------------------- + +The schema below describes the situation we are implementing. Two networks (A,B) and a transit network (10.10.8.0/24) +to peer both firewalls. We will create a tunnel network :code:`10.1.8.0/24` between both sites. + +.. nwdiag:: + :scale: 100% + + nwdiag { + + span_width = 90; + node_width = 180; + network A { + address = "10.0.8.0/24"; + pclana [label="PC Site A\n10.0.8.20",shape="cisco.pc"]; + fwa [shape = "cisco.firewall", address="10.0.8.1/24"]; + } + network Ext { + address = "10.10.8.0/24"; + label = "Tunnel net 10.1.8.0/24"; + fwa [shape = "cisco.firewall", address="10.10.8.1/24"]; + fwb [shape = "cisco.firewall", address="10.10.8.2/24"]; + } + network B { + address = "192.168.8.0/24" + fwb [shape = "cisco.firewall", address="192.168.8.20"]; + pclanb [label="PC Site B\n192.168.8.20",shape="cisco.pc"]; + } + + + } + + + +-------------------------------- +Preparations +-------------------------------- + +..................... +Trust +..................... + + +In order to setup a tunnel on both ends, we need to configure certificates to warrant trust between both machines. +We have chosen to setup the server on "Site B", so we start with Trust configuration there. + +* First we need an **Authority** which we are going to create in :menuselection:`System --> Trust --> Authorities` + + * Select `Create an internal Certificate Authority` + * Choose cryptographic settings and a lifetime (you may want to increase the default as after this time you do need to redistribute certificates to both server and client). + * Add descriptive information for this CA (`Descriptive name`, `City`, `Email`, ..`) + * Set the `Common Name` to something descriptive for this certificate, like "Office-ovpn" + + +* Next generate a **Certficate** for the server using :menuselection:`System --> Trust --> Certificates` + + * Select `Create an internal Certificate` + * Choose the just created authority in `Certificate authority` + * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA) + * Set Type to `Server` + * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here + * Set the `Common Name` to the fqdn of this machine. + +* As the client (Site A) will also need a **Certificate**, we need to create a certificate, also using :menuselection:`System --> Trust --> Certificates` + + * Select `Create an internal Certificate` + * Choose the just created authority in `Certificate authority` + * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA) + * Set Type to `Server` + * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here + * Set the `Common Name` to username the other end will use for identification. For this example we use :code:`test-client` + +.. Note:: + + It's a best practice to offer each user it's own certificate using the same common name as the username, although + it is also possible to clients to share a certificate. When adding a certificate from the user manager the CN is automatically + set to its name. In this example we will only authenticate using the certificate, no additional user or password will be required. + + +..................... +Static keys +..................... + +We create a static key and define it's use in :menuselection:`VPN --> OpenVPN --> Instances --> Static Keys`, for this example +select `auth` as mode and click the gear button to generate one. Provide a description for this key. + +.......................................... +Prepare Site A +.......................................... + +* Copy the public part of the certificate authority to the firewall at Site a (use the download button and copy the contents into a new CA on this host) +* Copy the public and private part of the client certificate into a new one on Site A +* Copy the contents of the static key to a new entry and select the same type + + +------------------------------------ +Create a server instance (Site B) +------------------------------------ + +Now the generic setup is done, we can configure a new server type instance via :menuselection:`VPN --> OpenVPN --> Instances` + +=============================================================== + +======================= ======================================= +Property site B +======================= ======================================= +Role Server +Description MyServer +Protocol UDP (IPv4) +Port number 1194 +Bind address 10.10.8.1 :sup:`1` +Server (IPv4) 10.1.8.0/24 (the tunnel network used) +Certificate choose the prepared server certificate +TLS static key choose the prepared static key +Local Network 192.168.8.0/24 +Remote Network 10.0.8.0/24 :sup:`2` +======================= ======================================= + +.. admonition:: Note :sup:`1` + + Leave empty to bind to all addresses assigned to this machine or use a loopback address combined with a port forward when + the external address is not static. + +.. admonition:: Note :sup:`2` + + The network(s) served by this openvpn instance, after startup routes will be created. In order to bind + the network to the correct client a `Client Specific Overwrite` is also needed. + + +Hit the apply button when the instance is configured and add a client specific overwrite in :menuselection:`VPN --> OpenVPN --> Client Specific Overrides` + +=============================================================== + +======================= ======================================= +Property site B +======================= ======================================= +Servers leave empty or select our server +Common name test-client +Remote Network 10.0.8.0/24 :sup:`1` +======================= ======================================= + +.. admonition:: Note :sup:`1` + + The remote network bound to this common name, without this entry the traffic will not be routed between hosts. + + +Next go to :menuselection:`Firewall --> Rules --> WAN` and add a rule to allow traffic on port :code:`1494/UDP` from the other +host. At minimum we should add a rule similar to this one: + +=============================================================== + +======================= ======================================= +Property site B +======================= ======================================= +Interface WAN +Protocol UDP +Destination port range 1194 +======================= ======================================= + +Finally we are going to allow traffic on the tunnel itself by adding a rule to :menuselection:`Firewall --> Rules --> OpenVPN`, +for this example we keep it simple and add one to allow all, in which case we can save the defaults when adding a rule. + + +------------------------------------ +Create a client instance (Site A) +------------------------------------ + +With the server in place it's time to setup the client on OPNsense, for this we go to :menuselection:`VPN --> OpenVPN --> Instances` +and add a new instance using the following settings. + +=============================================================== + +======================= ======================================= +Property site A +======================= ======================================= +Role Client +Description MyClient +Protocol UDP (IPv4) +Remote 10.10.8.1 +Certificate choose the prepared client certificate +TLS static key choose the prepared static key +Remote Network 192.168.8.0/24 +======================= ======================================= + + +-------------------------------- +Test connectivity +-------------------------------- + +Use the :menuselection:`VPN: OpenVPN: Connection Status` page to watch the status of both server and client, when +passing traffic over the link on both ends the counters should increase. + +Now try to ping from Site A (:code:`10.0.8.20`) to Site B (:code:`192.168.8.20`). diff --git a/source/manual/vpnet.rst b/source/manual/vpnet.rst index bf98d481..81b42aa7 100644 --- a/source/manual/vpnet.rst +++ b/source/manual/vpnet.rst @@ -353,37 +353,120 @@ One of the main advantages of OpenVPN in comparison to IPsec is the ease of conf and it's quite simple to export settings for clients. ................................. -Site 2 Site +General context ................................. -OpenVPN on OPNsense can also be used to create a tunnel between two locations, similar to what IPsec offers. Generally -the performance of IPsec is higher which usually makes this a less common choice. - -.. toctree:: - :maxdepth: 2 - :titlesonly: +The OpenVPN module incorporates different functions to setup secured networks for roadwarriors and side to side connections. +Since the start of our project we organized the openvpn menu section into servers and clients, which actually is a role +for the same OpenVPN process. As our legacy system has some disadvantages which are difficult to fix in a migration, we have chosen +to add a new component named :code:`Instances` in version 23.7 which offers access to OpenVPN's configuration in a similar way as +the upstream `documentation `__ describes it. +This new component will eventually replace the existing client and server options in a future version of OPNsense, leaving +enough time to migrate older setups. - how-tos/sslvpn_s2s +.. Tip:: + When upgrading into a new major version of OPNsense, always make sure to read the release notes to check if your setup + requires changes. .. Note:: - When using the site to site example with :code:`SSL/TLS` instead of a shared key, make sure to configure "client specific overrides" - as well to correctly bind the remote networks to the correct client. + OpenVPN on OPNsense can also be used to create a tunnel between two locations, similar to what IPsec offers. Generally + the performance of IPsec is higher which usually makes this a less common choice. + Mobile usage is really where OpenVPN excells, with various (multifactor) authentication options and + a high flexibility in available network options. + + +The following functions are available in the menu (as of OPNsense 23.7): + +* Instances + + * New instances tool offering access to server and client setups + +* Servers + + * Legacy server configuration tool + +* Clients + + * Legacy client configuration tool + +* Client Specific Overrides + + * Set client specific configurations based on the client’s X509 common name. + +* Client Export + + * Export tool for client configurations, used for server type instances + +* Connection Status + + * Show tunnel statusses + +* Log File + + * Inspect log entries related to OpenVPN + + +.................................... +Public Key Infrastructure (X.509) +.................................... + +OpenVPN is most commonly used in combination with a public key infrastructure, where we use a certificate autority which +signs certificates for both server and clients (Also know as TLS Mode). +More information about this topic is available in our :doc:`Trust section `. ................................. -Road Warriors / Mobile users +Firewall rules ................................. -Mobile usage is really where OpenVPN excells, with various (multifactor) authentication options and a high flexibility in available network options. +To allow traffic to the tunnel on any interface, a firewall rule is needed to allow the tunnel being established. +The default port for OpenVPN is :code:`1194` using protocol :code:`UDP`. + +After communication has been established, it's time to allow traffic inside the tunnel. All OpenVPN interfaces defined in +OPNsense are :doc:`grouped ` as `OpenVPN`. + +.. Tip:: + + In order to use features as policy based routing or manual routes, you can :doc:`assign ` the underlying + devices and use them in a similar fashion as physical interfaces. + + +................................. +Examples +................................. + +This paragraph offers examples for some commonly used implementation scenarios. + +.. Note:: + + When using a site to site example with :code:`SSL/TLS` instead of a shared key, make sure to configure "client specific overrides" + as well to correctly bind the remote networks to the correct client. + + +Legacy (:menuselection:`VPN -> OpenVPN -> Client|Server`) +------------------------------------------------------------------------------ .. toctree:: :maxdepth: 2 :titlesonly: + how-tos/sslvpn_s2s how-tos/sslvpn_client +New (:menuselection:`VPN -> OpenVPN -> Instances`) +------------------------------------------------------------------------------ + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + how-tos/sslvpn_instance_s2s + how-tos/sslvpn_instance_roadwarrior + + + ................................. Client Specific Overrides .................................