Merge pull request #302 from gunjambi/reverse-proxy-doc-for-upstream

Recommend HTTPS proxy over port forward.

Author: softhack007

docs/advanced/access-over-internet.md

@@ -0,0 +1,76 @@
+---
+title: Accessing WLED over Internet
+hide:
+  # - navigation
+  # - toc
+---
+
+WLED exposed to Internet safely with the help of a reverse proxy setup.
+This document describes the steps needed.
+
+!!! warning "Port Forwarding"
+    Under no circumstances port forward WLED instance to the public internet.
+    WLED does not support HTTPS or authentication, leading to a fundamentally insecure setup.
+
+!!! tip "Consider VPN Tunneling"
+    If you only need access from a single device, such as your phone,
+    consider a point-to-point VPN tunnel instead. Configuring a tunnel
+    may require less configuration and maintenance than a HTTPS reverse proxy.
+
+# Reverse proxy requirements
+
+WLED does not implement access control, allowing anyone able to connect to it change configuration or even update firmware.
+For a safe access, **the reverse proxy MUST implement access control** to only allow trusted users to access WLED.
+
+Secure access control cannot be implemented over insecure connection. **The reverse proxy MUST implement TLS termination**, only allowing access over HTTPS.
+
+Reverse proxy cannot run on the WLED device.
+You need a server in your local network to perform the encryption and proxying.
+
+# Example
+
+Assuming the following network setup, using Caddy as a reverse proxy:
+
+```
+[Public Internet]
+   |
+[Router]
+   |
+[Reverse Proxy]
+   |
+[WLED]
+```
+
+First, register a domain name. In this example, we assume the name "mydomain.example".
+A domain name is commonly a requirement for a HTTP certificate.
+You can use a dynamic dns provider for a free domain.
+
+Next, generate a HTTPs certificate for your domain.
+For the free Let's Encrypt certificates, configure necessary the automation for refreshing the certificate automatically.
+In this example, we are using Caddy which handles this automatically.
+
+We then expose the HTTPS port of the reverse proxy to public internet.
+In your network router, port forward port TCP 443 into the Reverse Proxy.
+In this example, we are using Caddy which only requires port 443 to complete the Let's Encrypt challenge for automatic certificate issuing.
+With other software, you may need to also open insecure HTTP port 80.
+
+Finally, in Caddyfile, configure the reverse proxy and authentication
+Note that Caddy uses HTTPS by default.
+With other software, we may need to disable access over the unsafe HTTP.
+
+```
+mydomain.example {
+  handle /wled/* {
+    # Create username and password. Password can be with `caddy hash-password --plaintext mypass`
+    basicauth {
+        yourusername PASSWORDHASH
+    }
+    uri strip_prefix /wled
+    reverse_proxy wled-wled-a.lan # IP address or the network local name of the WLED device
+  }
+}
+```
+
+Now `https://mydomain.example/wled/` exposes WLED to the public internet using secure HTTPS and password authentication.
+
+For additional securty, consider enabling [OTA lock password](/advanced/ota-lock).

docs/advanced/security.md docs/advanced/ota-lock.mddocs/advanced/security.md renamed to docs/advanced/ota-lock.md

@@ -1,11 +1,15 @@
 ---
-title: Security
+title: OTA Lock
 hide:
   # - navigation
   # - toc
 ---
 
-WLED was designed in a way that you should be safe to have a [router port forwarding](/advanced/remote-access-ifttt) to control the system from the public internet. This page will tell you what you can expect by WLEDs security.
+WLED security model is based on assumption that it is run on a trusted network, and in most cases, anyone having a network access to a WLED device has permissions for any operation.
+OTA Lock is an exception to this rule.
+OTA Lock allows limiting users who can perform OTA by requiring a password before allowing an update.
+This can be used for additional security when a device is accessed from the public internet. See [Remote Access / IFTTT](/advanced/remote-access-ifttt) for more information.
+This page will tell you what you can expect by WLEDs security.
 
 ### TLDR - what to do?
 

docs/advanced/remote-access-ifttt.md

@@ -17,15 +17,12 @@ If you add your WLED device to your Home Automation system (e.g. Home Assistant
 ### 2. Amazon Echo device
 If you have set up your Alexa device to control WLED, you can just use the Alexa App or another Echo device linked to your account to control your lights (on/off and brightness only)
 
-### 3. Port Forwarding
-**Warning: An insecure HTTP connection is used, please do NOT edit sensitive info like the WiFi settings when connected via port forwarding!**   
-This method offers more flexibility, but is also more involved.   
-**Keep in mind this causes anyone with your IP address to have access to your ESP8266!**   
-Setting up an [OTA lock password](/advanced/security) is a must to prevent attackers from acquiring your WiFi credentials!
-
-To expose WLED to the internet, create a port forwarding rule for your ESP's IP local ip and port (80) in your router configuration. It is not recommended to use port 80 on your public IP address since 80 is scanned constantly by bots good and bad. Use a 5 digit port for better security.
-If your public IP changes a lot, make sure to also use a dynamic DNS service so your lights are always accessible.
-_Unsure what any of this means or how to do it? Google for "[your router model] port forwarding"!_
+### 3. Reverse Proxy
+
+If you have a device capable running a reverse proxy in your local network,
+you can expose WLED safely over public internet.
+This allows you to control lighting from anywhere on the globe.
+See [Accessing WLED over Internet](/advanced/access-over-internet) for details.
 
 Additionally, this opens up many new possibilities for automation! You can use a service like [IFTTT](https://ifttt.com/) Webhooks to send automated WLED API calls that can do anything from turning on the lights at a set time to changing their color if you get a new email!
 

docs/basics/faq.md

@@ -20,7 +20,7 @@ hide:
 - [I have entered my WiFi credentials and rebooted, but I can not connect to the module now!](#i-have-entered-my-wifi-credentials-and-rebooted-but-i-can-not-connect-to-the-module-now)
 - [The module once was connected, but I can no longer reach it.](#the-module-once-was-connected-but-i-can-no-longer-reach-it)
 - [The wled-xxx.local address (mDNS) does not work.](#the-wled-xxxlocal-address-mdns-does-not-work)
-- [Is it safe to do a port forwarding to the public internet to control the lights from anywhere?](/advanced/security)
+- [Is it safe to expose WLED to the public internet to control the lights from anywhere?](#is-it-safe-to-expose-wled-to-the-public-internet-to-control-the-lights-from-anywhere)
 - [My device is unresponsive or animations lag!](#my-device-is-unresponsive-or-animations-lag)
 - [I'm having a bootloop! (LEDs turn on every ~5seconds)](#im-having-a-bootloop-leds-turn-on-every-5seconds)
 - [I am running realtime (e.g. E1.31) and not all of my LEDs are driven fluently!](#i-am-running-realtime-eg-e131-and-not-all-of-my-leds-are-driven-fluently)
@@ -92,9 +92,9 @@ This only works with Apple devices out of the box. You can install Bonjour to ma
 For Android there is no convenient way to achieve it, though you can use apps like "Bonjour search" to find the IP.
 It is highly recommended that you install the WLED Native app, which makes automatic discovery easy!
 
-### Is it safe to do a port forwarding to the public internet to control the lights from anywhere?
+### Is it safe to expose WLED to the public internet to control the lights from anywhere?
 
-See [this](/advanced/security) page.
+See [Accessing WLED over Internet](/advanced/access-over-internet) page.
 
 ### My device is unresponsive or animations lag!
 

mkdocs.yml

@@ -120,7 +120,8 @@ nav:
     - Audio Reactive WLED: advanced/audio-reactive.md
     - Home Automation: advanced/home-automation.md
     - Remote Access / IFTTT: advanced/remote-access-ifttt.md
-    - Security: advanced/security.md
+    - OTA Lock: advanced/ota-lock.md
+    - Accessing WLED over Internet: advanced/access-over-internet.md
     - Wiring Protips: advanced/wiring.md
     - Long Data Lines: advanced/longdata.md
     - Compiling WLED: advanced/compiling-wled.md