diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js index 63b1d84d3b..767b9cfae9 100644 --- a/.vuepress/docs-sidebar.js +++ b/.vuepress/docs-sidebar.js @@ -54,8 +54,14 @@ module.exports = [ 'installation/armbian', 'installation/docker', 'installation/synology', - ['installation/security', 'Security'], - ['installation/reverse-proxy', 'Reverse Proxy'] + { title: 'Security', + path: '/docs/installation/security', + children: [ + 'installation/reverse-proxy-nginx', + 'installation/reverse-proxy-apache', + 'installation/reverse-proxy-synology' + ] + } ] }, { diff --git a/installation/reverse-proxy-apache.md b/installation/reverse-proxy-apache.md new file mode 100644 index 0000000000..59dadac7da --- /dev/null +++ b/installation/reverse-proxy-apache.md @@ -0,0 +1,150 @@ +--- +layout: documentation +title: Apache Reverse Proxy +--- + +# Apache Reverse Proxy + +These are the steps required to use [**Apache 2.4**](https://www.apache.org/), a HTTP server, although you can use [**NGINX**](reverse-proxy-nginx) server or any other HTTP server which supports reverse proxying. If you are familiar with Apache/basic reverse proxy config and are only interested in OpenHAB specific caveats/directives skip to [OpenHAB settings](#openhab-specific-settings) + +[[toc]] + +## Installation + +Apache runs as a service in most Linux distributions, installation should be as simple as: + +```shell +sudo apt-get update && sudo apt-get install apache2 +sudo service apache2 start +``` + +for Ubuntu/Debian based Linux, or + +```shell +sudo yum install httpd +sudo systemctl enable httpd +sudo systemctl start httpd +``` + +for Fedora/CentOS/Red Hat Enterprise + +Once installed, you can test to see if the service is running correctly by going to `http://mydomain_or_myip`, you should see the apache2 default page. + +## Basic Configuration + +::: warning Security Warning +It is not recommended to expose solely the configuration below to the internet. +::: + +Apache runs based on configuration files. +The location of the default setup is typically `/etc/apache2/sites-available/000-default.conf`. To allow Apache to proxy openHAB, you need to edit or replace this file. Common practice is to use the domain name of the website it serves, appended with ".conf" - for example, "mydomain.conf" + +The configuration below assumes that you run the reverse proxy on the same machine as your openHAB runtime. +If this doesn't fit for you, you just have to replace `localhost` with your openHAB instance hostname or ip. Remember to replace `mydomain` with your actual domain. + +```xml + + ServerName mydomain + + + ProxyPass "http://localhost/" + ProxyPassReverse "http://localhost/" + + + ErrorLog ${APACHE_LOG_DIR}/mydomain-error.log + CustomLog ${APACHE_LOG_DIR}/mydomain-access.log combined + +``` + +The command `apachectl configtest` can be used to verify any config you write. To enable your new website `a2ensite `. Once enabled, you will not have to enable your website again. Configuration can be reloaded with `systemctl reload apache2`. Please make sure to reload and clear browser cookies after every change. + +## Authentication + +Authentication is recommended for additional security. There are many ways to authenticate to a proxy, but basic auth is sufficient **as long as it is over https**. Note the below documentation about [OpenHAB specific auth headers](#authentication-headers). + +### Adding or Removing users + +To add users to your reverse proxy, you must use following command. Use the `-c` modifier only for your first user. It will create a new password file. **Do not** use the `-c` modifier again as this will remove all previously created users. Don't forget to change _username_ to something meaningful! + +```shell +sudo htpasswd -c /etc/apache2/.htpasswd username +``` + +```shell +sudo htpasswd /etc/apache2/.htpasswd username +``` + +and to delete an existing user: + +```shell +sudo htpasswd -D /etc/apache2/.htpasswd username +``` + +### Basic Auth + +The below directives set the auth type to basic, set the auth name, point to our credentials file, and require a user to be authenticated before allowing them to access OpenHAB + +```xml + + AuthType Basic + AuthName "Proxy Auth" + AuthUserFile /etc/apache2/.htpasswd + Require valid-user + +``` + +## Encryption/HTTPS + +In the interest of not duplicating documentation, please see the [nginx encryption documentation](reverse-proxy-nginx#enabling-https) for certificate generation options. The certificate directives for Apache are: + +```xml +SSLEngine on +SSLCertificateFile /path/to/cert +SSLCertificateKeyFile /path/to/key +``` + +For more details, read the [apache mod_ssl docs](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslcertificatefile) + +## OpenHAB Specific Settings + +These settings are required due to the quirks and features of proxies and/or OpenHAB. + +### Authentication Headers + +If you use authentication with your reverse proxy, the following two directives are necessary in OpenHAB 3.0 and later. + +`Header set Set-Cookie "X-OPENHAB-AUTH-HEADER=1"` + +This ensures that OpenHAB uses an alternative auth header, so it does not conflict with your proxy authentication credentials. + +`RequestHeader unset Authorization` + +This ensures that your proxy does not send your proxy authentication credentials to OpenHAB, interfering with login (and potentially sending them in plain text across a network). + +## Putting it All Together + +Below is a minimal configuration for a reverse proxy that listens for https requests only, uses basic auth, and proxies to 8080 (default OpenHAB http port). + +```xml + + ServerName mydomain + SSLEngine on + SSLCertificateFile /path/to/cert + SSLCertificateKeyFile /path/to/key + + Header set Set-Cookie "X-OPENHAB-AUTH-HEADER=1" + RequestHeader unset Authorization + + + ProxyPass "http://localhost:8080/" + ProxyPassReverse "http://localhost:8080/" + AuthType Basic + AuthName "Proxy Auth" + AuthUserFile /etc/apache2/.htpasswd + Require valid-user + + + ErrorLog ${APACHE_LOG_DIR}/mydomain-error.log + CustomLog ${APACHE_LOG_DIR}/mydomain-access.log combined + +``` diff --git a/installation/reverse-proxy.md b/installation/reverse-proxy-nginx.md similarity index 59% rename from installation/reverse-proxy.md rename to installation/reverse-proxy-nginx.md index 2e9200870d..1547ecee49 100644 --- a/installation/reverse-proxy.md +++ b/installation/reverse-proxy-nginx.md @@ -1,21 +1,15 @@ --- layout: documentation -title: Running openHAB Behind a Reverse Proxy +title: NGINX Reverse Proxy --- -# Running openHAB Behind a Reverse Proxy using NGINX +# NGINX Reverse Proxy -::: warning Security Warning -It is vitally important that you MUST NOT directly expose your openHAB instance to the Internet (e.g. by opening a port in your firewall)! -::: +These are the steps required to use [**NGINX**](https://nginx.org), a lightweight HTTP server, although you can use [**Apache**](reverse-proxy-apache) server or any other HTTP server which supports reverse proxying. [[toc]] -## Setting up NGINX - -These are the steps required to use [**NGINX**](https://nginx.org), a lightweight HTTP server, although you can use **Apache HTTP** server or any other HTTP server which supports reverse proxying. - -### Installation +## Installation NGINX runs as a service in most Linux distributions, installation should be as simple as: @@ -26,7 +20,7 @@ sudo apt-get update && sudo apt-get install nginx Once installed, you can test to see if the service is running correctly by going to `http://mydomain_or_myip`, you should see the default "Welcome to nginx" page. If you don't, you may need to check your firewall or ports and check if port 80 (and 443 for HTTPS later) is not blocked and that services can use it. -### Basic Configuration +## Basic Configuration NGINX configures the server when it starts up based on configuration files. The location of the default setup is `/etc/nginx/sites-enabled/default`. To allow NGINX to proxy openHAB, you need to change this file (make a backup of it in a different folder first). @@ -79,12 +73,12 @@ sudo service nginx restart ...and then go to `http://mydomain_or_myip` to see your openHAB server. -## Authentication with NGINX +## Authentication For further security, you may wish to ask for a **username and password** before users have access to openHAB. This is fairly simple in NGINX once you have the reverse proxy setup, you just need to provide the server with a basic authentication user file. -### Creating the First User +### Adding or Removing users You will be using _htpasswd_ to generate a username/password file, this utility can be found in the apache2-utils package: @@ -92,14 +86,23 @@ You will be using _htpasswd_ to generate a username/password file, this utility sudo apt-get install apache2-utils ``` -To generate a file that NGINX can use you use the following command, don't forget to change _username_ to something meaningful! +To add users to your reverse proxy, you must use following command. Use the `-c` modifier only for your first user. It will create a new password file. **Do not** use the `-c` modifier again as this will remove all previously created users. Don't forget to change _username_ to something meaningful! ```shell sudo htpasswd -c /etc/nginx/.htpasswd username ``` -You will receive a prompt to create a password for this username, once finished the file will be created. -You're then free to reference the file to NGINX. +```shell +sudo htpasswd /etc/nginx/.htpasswd username +``` + +and to delete an existing user: + +```shell +sudo htpasswd -D /etc/nginx/.htpasswd username +``` + +Once again, any changes you make to these files **must be followed with restarting the NGINX service** otherwise no changes will be made. ### Referencing the File in the NGINX Configuration @@ -123,28 +126,12 @@ This is not required prior to openHAB 3.0. You must add the following two direct Once done, **test and restart your NGINX service** and authentication should now be enabled on your server! -### Adding or Removing users - -To add new users to your site, you must use following command, **do not** use the `-c` modifier again as this will remove all previously created users: - -```shell -sudo htpasswd /etc/nginx/.htpasswd username -``` - -and to delete an existing user: - -```shell -sudo htpasswd -D /etc/nginx/.htpasswd username -``` - -Once again, any changes you make to these files **must be followed with restarting the NGINX service** otherwise no changes will be made. - ### Use a client certificate based authentication You can find a short tutorial in the community forum on how to do so. [Using NGINX Reverse Proxy for client certificate authentication](https://community.openhab.org/t/using-nginx-reverse-proxy-for-client-certificate-authentication-start-discussion/43064) -## Making Exceptions for Specific IP addresses +### Making Exceptions for Specific IP addresses It is often desirable to allow specific IPs (e.g. the local network) to access openHAB without needing to prompt for a password or to block everyone else entirely. In these cases NGINX can use the `satisfy any` directive followed by `allow` and `deny` lines to make these exceptions. @@ -175,10 +162,10 @@ To generate a trusted certificate, you need to own a domain. To acquire your own Encrypting the communication between client and the server is important because it protects against eavesdropping and possible forgery. The following options are available depending if you have a valid domain: -If you have a **valid domain and can change the DNS** to point towards your IP, follow the [instructions for Let's Encrypt](#using-lets-encrypt-to-generate-trusted-certificates) -If you need to use an internal or external IP to connect to openHAB, follow the [instructions for OpenSSL](#using-openssl-to-generate-self-signed-certificates) +If you have a **valid domain and can change the DNS** to point towards your IP, follow the [instructions for Let's Encrypt](#using-lets-encrypt-to-generate-trusted-certificates). +If you need to use an internal or external IP to connect to openHAB, follow the [instructions for OpenSSL](#using-openssl-to-generate-self-signed-certificates). -## Using OpenSSL to Generate Self-Signed Certificates +### Using OpenSSL to Generate Self-Signed Certificates OpenSSL is also packaged for most Linux distributions, installing it should be as simple as: @@ -201,18 +188,7 @@ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/openha You will be prompted for some information which you will need to fill out for the certificate, when it asks for a **Common Name**, you may enter your IP Address: Common Name (e.g. server FQDN or YOUR name) []: xx.xx.xx.xx -### Adding the Certificates to Your Proxy Server - -The certificate and key should have been placed in `/etc/ssl/`. -NGINX needs to be told where these files are and then enable the reverse proxy to direct HTTPS traffic. -In the NGINX configuration, place the following underneath your `server_name` variable: - -```text - ssl_certificate /etc/ssl/openhab.crt; - ssl_certificate_key /etc/ssl/openhab.key; -``` - -## Using Let's Encrypt to Generate Trusted Certificates +### Using Let's Encrypt to Generate Trusted Certificates ::: tip Skip this step if you have no domain name or have already followed the instructions for OpenSSL @@ -220,7 +196,7 @@ Skip this step if you have no domain name or have already followed the instructi Let's Encrypt is a service that allows anyone with a valid domain to automatically generate a trusted certificate, these certificates are usually accepted by a browser without any warnings. -### Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure +#### Setting up the NGINX Proxy Server to Handle the Certificate Generation Procedure Let's Encrypt needs to validate that the server has control of the domain. The simplest way of doing this is using a **webroot plugin** to place a file on the server, and then access it using a specific url: _/.well-known/acme-challenge_. @@ -240,7 +216,7 @@ Next add the new location parameter to your NGINX config, this should be **place } ``` -### Using Certbot +#### Using Certbot Certbot is a tool which simplifies the process of obtaining secure certificates. The tool may not be packaged for some Linux distributions so installation instructions may vary, check out [their website](https://certbot.eff.org/) and follow the instructions **using the webroot mode**. @@ -252,9 +228,14 @@ sudo certbot certonly --webroot -w /var/www/mydomain -d mydomain ### Adding the Certificates to Your Proxy Server -The certificate and key should have been placed in `/etc/letsencrypt/live/mydomain_or_myip`. +If you followed one of the two guides for OpenSSL or Let's Encrypt above, the certificate and key should have been placed in `/etc/letsencrypt/live/mydomain_or_myip/` or `/etc/ssl/` respectively. NGINX needs to be told where these files are and then enable the reverse proxy to direct HTTPS traffic, using Strict Transport Security to prevent man-in-the-middle attacks. -In the NGINX configuration, place the following underneath your server_name variable: +In the NGINX configuration, place one of the following underneath your server_name variable: + +```text + ssl_certificate /etc/ssl/openhab.crt; + ssl_certificate_key /etc/ssl/openhab.key; +``` ```text ssl_certificate /etc/letsencrypt/live/mydomain_or_myip/fullchain.pem; @@ -262,7 +243,7 @@ In the NGINX configuration, place the following underneath your server_name vari add_header Strict-Transport-Security "max-age=31536000"; ``` -## Setting Your NGINX Server to Listen to the HTTPS Port +### Setting Your NGINX Server to Listen to the HTTPS Port Regardless of the option you choose, make sure you change the port to listen in on HTTPS traffic. @@ -272,10 +253,10 @@ Regardless of the option you choose, make sure you change the port to listen in After restarting NGINX service, you will be using a valid HTTPS certificate. You can check by going to `https://mydomain_or_myip` and confirming with your browser that you have a valid certificate. -**These certificates expire within a few months** so it is important to run the updater in a cron expression (and also restart NGINX) as explained in the Certbot setup instructions. +**Let's Encrypt certificates expire within a few months** so it is important to run the updater in a cron expression (and also restart NGINX) as explained in the Certbot setup instructions. If you want to keep hold of a HTTP server for some reason, just add `listen 80;` and remove the Strict-Transport-Security line. -## Redirecting HTTP Traffic to HTTPS +### Redirecting HTTP Traffic to HTTPS You may want to redirect all HTTP traffic to HTTPS, you can do this by adding the following to the NGINX configuration. This will essentially replace the HTTP url with the HTTPS version! @@ -351,177 +332,6 @@ server { } ``` -## Configuration on Synology DiskStation - -Synology DSM (as of 6.2) has the ability to automatically acquire certificates from Let's Encrypt and renew them every 90 days as required. -The majority of the configuration mentioned above can be completed through the DSM GUI, but SSH access is required to implement authentication (**authentication is essential for remote access to your openHAB instance**). - -Before you continue, make sure you have the below conditions: - -- A working installation of openHAB on your DiskStation (see the [Synology Installation Guide](https://www.openhab.org/docs/installation/synology.html/)) -- Your own domain you can configure the CAA record for (see [Setting up a Domain](#setting-up-a-domain)) -- Access to your DiskStation by SSH ([How to login to DSM with root permission via SSH/Telnet](https://www.synology.com/en-global/knowledgebase/DSM/tutorial/General_Setup/How_to_login_to_DSM_with_root_permission_via_SSH_Telnet/)) -- Ports 80 and 443 forwarded from your router to your DiskStation (make sure you reconfigure the router web UI to a different port first, so you don't lose access!) - -Log into the GUI of your DiskStation as administrator, and open the package center. -Install Apache HTTP Server. -This is needed to generate the password files. - -Go to Control Panel > Application Portal > Reverse Proxy. We will set up two reverse proxies, one for HTTP and one for HTTPS. -The HTTP one can be disabled later if desired (not at all essential if you will only use the app remotely, and never a browser). - -Create two reverse proxies as follows: - -| Parameter | Value | -| :-------------------- | :--------------------------------------------------------- | -| Description: | openHAB HTTPS | -| Source Protocol: | HTTPS | -| Source Hostname: | your-hostname.com | -| Source Port: | 443 | -| Enable HSTS | Unchecked | -| Enable HTTP/2 | Unchecked | -| Enable access control | Unchecked | -| Destination Protocol: | HTTPS | -| Destination Hostname: | localhost | -| Destination Port: | 8443 (or whichever HTTPS port your openHAB instance is on) | - -| Parameter | Value | -| :-------------------- | :-------------------------------------------------------- | -| Description: | openHAB HTTP | -| Source Protocol: | HTTP | -| Source Hostname: | your-hostname.com | -| Source Port: | 80 | -| Enable HSTS | Unchecked | -| Enable HTTP/2 | Unchecked | -| Enable access control | Unchecked | -| Destination Protocol: | HTTP | -| Destination Hostname: | localhost | -| Destination Port: | 8080 (or whichever HTTP port your openHAB instance is on) | - -Verify that the reverse proxy is working as expected - try and - you should end up at the openHAB landing page in both cases, but will get a security warning for the https site. - -Next, acquire certificates from Let's Encrypt using the GUI in DSM. - -Go to Control Panel > Security > Certificate, and click on 'Add'. -Select the option to 'Add a new Certificate'. -Put in a description, something like 'openHAB SSL Cert' (it doesn't matter). -Select 'Get a certificate from Let's Encrypt' and check the box to set it as default. -Click next. -Put in your domain name and email address. -Add a 'Subject Alternative Name' if you want a different topic in the subject line when Let's Encrypt email you about that certificate (not essential). -Click Apply, and wait a few minutes - your certificate is done! - -::: tip Note -Sometimes you may receive an error at the end of the certificate wizard - the first time this happens, click on 'cancel and see if you have a certificate anyway. -If the certificate has been generated, you are good to go. -::: - -Select the certificate that has just been created, and click on 'Configure'. -Ensure that the new certificate is listed next to your-hostname.com in the table - something like the below. -If it's not selected, update it. - -| Services | Certificate | -| :------------------- | :---------------- | -| your-hostname.com | your-hostname.com | -| FTPS | synology.com | -| Cloud Station Server | synology.com | -| etc etc | synology.com | - -Once this is done, update the CAA record for your-hostname.com with your registrar (exact process will vary by registrar). -Within an hour or so, you should not receive the security warning for . - -Next, you must add authentication to the reverse proxy. -There's no GUI way to do this, so we need to create another small NGINX virtual host on the DiskStation. - -Log into your DiskStation by SSH. -Use the admin username and password. -Create a .htpasswd file in your openHAB userdata folder (your userdata location may vary, update accordingly): - -```shell -htpasswd -c /volume1/openHAB/userdata/.htpasswd username -``` - -Next, add a very simple NGINX configuration similar to that created above, but without the SSL parameters. -DSM comes with vi installed by default, but you may wish to [install nano](https://anto.online/other/how-to-install-nano-on-your-synology-nas/) - -```shell -sudo nano /usr/local/etc/nginx/sites-enabled/openHAB-auth -``` - -```json -# openHAB NGINX config - -server { - listen 2020; #This is simply an unused port, it can be any number - - server_name your_domain.com; - - return 301 https://$server_name$request_uri; -} - -server { - listen 7443 ssl; #This is simply an unused port, it can be any number - server_name your_domain.com; - - add_header 'Access-Control-Allow-Origin' '*' always; - add_header 'Access-Control-Allow_Credentials' 'true' always; - add_header 'Access-Control-Allow-Headers' 'Authorization,Accept,Origin,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range' always; - add_header 'Access-Control-Allow-Methods' 'GET,POST,OPTIONS,PUT,DELETE,PATCH' always; - add_header Set-Cookie X-OPENHAB-AUTH-HEADER=1; - - location / { - proxy_http_version 1.1; - proxy_pass https://localhost:8443/; #Update the port number if needed - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "Upgrade"; - proxy_set_header Authorization ""; - satisfy any; - allow 192.168.1.0/24; - allow 127.0.0.1; - deny all; - auth_basic "Username and Password Required"; - auth_basic_user_file /volume1/openHAB/userdata/.htpasswd; #Update with your userdata folder if different - } - -} -``` - -Once you are done, save the file, restart and test NGINX: - -```shell -sudo nginx -s reload && sudo nginx -t -``` - -As above, the first part of the file redirects any HTTP queries to HTTPS directly. -If you don't get any errors, update the reverse proxy settings in the DSM GUI to point to these new endpoints. -Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make the updates below: - -| Parameter | Value | -| :---------------- | :-------------------------------------------------------- | -| Destination Port: | 7443 (or whatever you set it to in the openHAB-auth file) | - -| Parameter | Value | -| :---------------- | :-------------------------------------------------------- | -| Destination Port: | 2020 (or whatever you set it to in the openHAB-auth file) | - -::: tip Note -We do this 'double' redirect to take advantage of the GUI certificate handling in DSM - this is the equivalent of CertBot for a Linux installation. -::: - -Give it a try again - you should now get redirected to `https://your-hostname.com` from `http://your-hostname.com`, and should receive a username and password prompt before you see the openHAB landing page. - -If you need to troubleshoot the nginx server, SSH into your DiskStation, and check the NGINX error log: - -```shell -sudo tail -f /var/log/nginx/error.log -``` - -This log will update in real-time, so do whatever it was that you were having issues with again, and you'll see the error. - ## Additional HTTPS Security To test your security settings [SSL Labs](https://www.ssllabs.com/ssltest/) provides a tool for testing your domain against ideal settings (Make sure you check "Do not show the results on the boards" if you don't want your domain seen). @@ -555,7 +365,7 @@ All of these settings are customizable, but make sure you [read up on](https://n Feel free to test the new configuration again on [SSL Labs](https://www.ssllabs.com/ssltest/). If you're achieving A or A+ here, then your client-openHAB communication is very secure. -## Further Reading +### Further Reading The setup above is a suggestion for high compatibility with an A+ rating at the time of writing, however flaws in these settings (particularly the cyphers) may become known overtime. The following articles may be useful when understanding and changing these settings. diff --git a/installation/reverse-proxy-synology.md b/installation/reverse-proxy-synology.md new file mode 100644 index 0000000000..73f64a3747 --- /dev/null +++ b/installation/reverse-proxy-synology.md @@ -0,0 +1,176 @@ +--- +layout: documentation +title: Synology DiskStation Reverse Proxy +--- +[[toc]] + +# Synology DiskStation Reverse Proxy + +Synology DSM (as of 6.2) has the ability to automatically acquire certificates from Let's Encrypt and renew them every 90 days as required. +The majority of the configuration can be completed through the DSM GUI, but SSH access is required to implement authentication (**authentication is essential for remote access to your openHAB instance**). + +Before you continue, make sure you have the below conditions: + +- A working installation of openHAB on your DiskStation (see the [Synology Installation Guide](https://www.openhab.org/docs/installation/synology.html/)) +- Your own domain you can configure the CAA record for +- Access to your DiskStation by SSH ([How to login to DSM with root permission via SSH/Telnet](https://www.synology.com/en-global/knowledgebase/DSM/tutorial/General_Setup/How_to_login_to_DSM_with_root_permission_via_SSH_Telnet/)) +- Ports 80 and 443 forwarded from your router to your DiskStation (make sure you reconfigure the router web UI to a different port first, so you don't lose access!) + +Log into the GUI of your DiskStation as administrator, and open the package center. +Install Apache HTTP Server. +This is needed to generate the password files. + +Go to Control Panel > Application Portal > Reverse Proxy. We will set up two reverse proxies, one for HTTP and one for HTTPS. +The HTTP one can be disabled later if desired (not at all essential if you will only use the app remotely, and never a browser). + +Create two reverse proxies as follows: + +| Parameter | Value | +| :-------------------- | :--------------------------------------------------------- | +| Description: | openHAB HTTPS | +| Source Protocol: | HTTPS | +| Source Hostname: | your-hostname.com | +| Source Port: | 443 | +| Enable HSTS | Unchecked | +| Enable HTTP/2 | Unchecked | +| Enable access control | Unchecked | +| Destination Protocol: | HTTPS | +| Destination Hostname: | localhost | +| Destination Port: | 8443 (or whichever HTTPS port your openHAB instance is on) | + +| Parameter | Value | +| :-------------------- | :-------------------------------------------------------- | +| Description: | openHAB HTTP | +| Source Protocol: | HTTP | +| Source Hostname: | your-hostname.com | +| Source Port: | 80 | +| Enable HSTS | Unchecked | +| Enable HTTP/2 | Unchecked | +| Enable access control | Unchecked | +| Destination Protocol: | HTTP | +| Destination Hostname: | localhost | +| Destination Port: | 8080 (or whichever HTTP port your openHAB instance is on) | + +Verify that the reverse proxy is working as expected - try and - you should end up at the openHAB landing page in both cases, but will get a security warning for the https site. + +Next, acquire certificates from Let's Encrypt using the GUI in DSM. + +Go to Control Panel > Security > Certificate, and click on 'Add'. +Select the option to 'Add a new Certificate'. +Put in a description, something like 'openHAB SSL Cert' (it doesn't matter). +Select 'Get a certificate from Let's Encrypt' and check the box to set it as default. +Click next. +Put in your domain name and email address. +Add a 'Subject Alternative Name' if you want a different topic in the subject line when Let's Encrypt email you about that certificate (not essential). +Click Apply, and wait a few minutes - your certificate is done! + +::: tip Note +Sometimes you may receive an error at the end of the certificate wizard - the first time this happens, click on 'cancel and see if you have a certificate anyway. +If the certificate has been generated, you are good to go. +::: + +Select the certificate that has just been created, and click on 'Configure'. +Ensure that the new certificate is listed next to your-hostname.com in the table - something like the below. +If it's not selected, update it. + +| Services | Certificate | +| :------------------- | :---------------- | +| your-hostname.com | your-hostname.com | +| FTPS | synology.com | +| Cloud Station Server | synology.com | +| etc etc | synology.com | + +Once this is done, update the CAA record for your-hostname.com with your registrar (exact process will vary by registrar). +Within an hour or so, you should not receive the security warning for . + +Next, you must add authentication to the reverse proxy. +There's no GUI way to do this, so we need to create another small NGINX virtual host on the DiskStation. + +Log into your DiskStation by SSH. +Use the admin username and password. +Create a .htpasswd file in your openHAB userdata folder (your userdata location may vary, update accordingly): + +```shell +htpasswd -c /volume1/openHAB/userdata/.htpasswd username +``` + +Next, add a very simple NGINX configuration similar to that created [for NGINX](reverse-proxy-nginx), but without the SSL parameters. +DSM comes with vi installed by default, but you may wish to [install nano](https://anto.online/other/how-to-install-nano-on-your-synology-nas/) + +```shell +sudo nano /usr/local/etc/nginx/sites-enabled/openHAB-auth +``` + +```json +# openHAB NGINX config + +server { + listen 2020; #This is simply an unused port, it can be any number + + server_name your_domain.com; + + return 301 https://$server_name$request_uri; +} + +server { + listen 7443 ssl; #This is simply an unused port, it can be any number + server_name your_domain.com; + + add_header 'Access-Control-Allow-Origin' '*' always; + add_header 'Access-Control-Allow_Credentials' 'true' always; + add_header 'Access-Control-Allow-Headers' 'Authorization,Accept,Origin,DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Content-Range,Range' always; + add_header 'Access-Control-Allow-Methods' 'GET,POST,OPTIONS,PUT,DELETE,PATCH' always; + add_header Set-Cookie X-OPENHAB-AUTH-HEADER=1; + + location / { + proxy_http_version 1.1; + proxy_pass https://localhost:8443/; #Update the port number if needed + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header Authorization ""; + satisfy any; + allow 192.168.1.0/24; + allow 127.0.0.1; + deny all; + auth_basic "Username and Password Required"; + auth_basic_user_file /volume1/openHAB/userdata/.htpasswd; #Update with your userdata folder if different + } + +} +``` + +Once you are done, save the file, restart and test NGINX: + +```shell +sudo nginx -s reload && sudo nginx -t +``` + +The first part of this file redirects any HTTP queries to HTTPS directly. +If you don't get any errors, update the reverse proxy settings in the DSM GUI to point to these new endpoints. +Back in the GUI, go to Control Panel > Application Portal > Reverse Proxy, make the updates below: + +| Parameter | Value | +| :---------------- | :-------------------------------------------------------- | +| Destination Port: | 7443 (or whatever you set it to in the openHAB-auth file) | + +| Parameter | Value | +| :---------------- | :-------------------------------------------------------- | +| Destination Port: | 2020 (or whatever you set it to in the openHAB-auth file) | + +::: tip Note +We do this 'double' redirect to take advantage of the GUI certificate handling in DSM - this is the equivalent of CertBot for a Linux installation. +::: + +Give it a try again - you should now get redirected to `https://your-hostname.com` from `http://your-hostname.com`, and should receive a username and password prompt before you see the openHAB landing page. + +If you need to troubleshoot the nginx server, SSH into your DiskStation, and check the NGINX error log: + +```shell +sudo tail -f /var/log/nginx/error.log +``` + +This log will update in real-time, so do whatever it was that you were having issues with again, and you'll see the error. diff --git a/installation/security.md b/installation/security.md index 9bdc31025c..d45df64bd4 100644 --- a/installation/security.md +++ b/installation/security.md @@ -88,7 +88,11 @@ It also provides you a simple way of **protecting your server** with authenticat The good news is that [openHABian](openhabian) already offers the possibility to activate a preconfigured NGINX reverse proxy, which includes setting up authentication and a valid [Let's Encrypt](https://letsencrypt.org) certificate. -Read the more on page [Running openHAB Behind a Reverse Proxy using NGINX](reverse-proxy.html) about how to configure NGINX. +Read the more following pages for your configuration: + +- [NGINX/openHABian](reverse-proxy-nginx.html) +- [Synology DiskStation](reverse-proxy-synology.html) +- [Apache](reverse-proxy-apache.html) ::: warning Security Warning It is vitally important that you MUST NOT directly expose your openHAB instance to the Internet (e.g. by opening a port in your firewall)!