Update the reverse proxy auth docs

Author: fguillot

content/en/v1/admin/config.md

@@ -230,4 +230,10 @@ define('TOTP_ISSUER', 'Kanboard');
 
 // Comma separated list of trusted proxy headers, for example: "HTTP_X_REAL_IP,HTTP_X_FORWARDED_FOR"
 define('TRUSTED_PROXY_HEADERS', '');
+
+// Comma separated list of trusted proxy IP networks (CIDR), for example: "192.168.0.0/16,10.0.0.0/8,::1/128"
+define('TRUSTED_PROXY_NETWORKS', '');
+
+// Allow private network access when fetching metadata for external links
+define('EXTERNAL_LINK_ALLOW_PRIVATE_NETWORKS', false);
 ```

content/en/v1/admin/reverse_proxy_authentication.md

@@ -8,11 +8,14 @@ menu:
 
 This authentication method is often used for [SSO](http://en.wikipedia.org/wiki/Single_sign-on) (Single Sign-On), especially for large organizations.
 
-The authentication is handled by another system. Kanboard does not store your password and assumes you are already authenticated.
+The authentication is handled by another system.
+Kanboard does not store your password and assumes you are already authenticated.
 
 ## Requirements
 
-- Apache authentication on the same server or a properly configured reverse proxy.
+- Apache or another web server with authentication capabilities (e.g., Basic Auth, LDAP, OAuth, SAML)
+- A reverse proxy configured to authenticate users and forward authentication headers to Kanboard
+- Network configuration ensuring Kanboard is only accessible through the reverse proxy
 
 ## How Does This Work?
 
@@ -25,15 +28,83 @@ The authentication is handled by another system. Kanboard does not store your pa
 
 ### Setting Up Your Reverse Proxy
 
-This is outside the scope of this documentation. Ensure the reverse proxy sends the user login via an HTTP header and identify which header is used.
+This is outside the scope of this documentation. You must configure your reverse proxy to authenticate users and pass the authenticated username via an HTTP header to Kanboard.
+
+Consult your reverse proxy documentation to:
+
+- Enable authentication (e.g., Basic Auth, LDAP, OAuth, SAML)
+- Configure the proxy to set an HTTP header containing the authenticated username
+- Identify which header name your proxy uses (e.g., `REMOTE_USER`, `X-Forwarded-User`, `X-Authenticated-User`)
+
+You will need this header name for the Kanboard configuration below.
+
+#### Security (important): prevent authentication header spoofing
+
+When reverse proxy authentication is enabled, Kanboard trusts the configured header (for example `REMOTE_USER` or `HTTP_X_AUTHENTICATED_USER`).
+If an attacker can reach Kanboard directly (bypassing the reverse proxy) or can inject headers that your proxy forwards, they could impersonate another user.
+
+To avoid this, configure your reverse proxy so that:
+
+- Kanboard is not reachable directly from untrusted networks (only through the reverse proxy).
+- The proxy removes any incoming authentication headers from the client request.
+- The proxy sets the authentication header itself, using a value coming from the proxy authentication step.
+
+Nginx example (strip client-supplied headers, then set your own):
+
+```nginx
+location / {
+    # Strip any client-supplied authentication headers to prevent spoofing
+    proxy_set_header X-Forwarded-User "";
+    proxy_set_header REMOTE_USER "";
+
+    # Set the authentication header from the authenticated user
+    # For HTTP Basic Auth, use $remote_user
+    proxy_set_header X-Forwarded-User $remote_user;
+
+    # For auth_request module, use a variable from your auth subrequest:
+    # proxy_set_header X-Forwarded-User $auth_user;
+
+    # Forward other standard headers
+    proxy_set_header Host $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_pass http://kanboard_upstream;
+}
+```
+
+Apache example (unset, then set from the authenticated user):
+
+```apache
+# Strip any client-supplied authentication headers to prevent spoofing
+RequestHeader unset X-Forwarded-User
+RequestHeader unset REMOTE_USER
+
+# Set the authentication header from the authenticated user
+# This example assumes Apache HTTP Basic Auth or similar module
+RequestHeader set X-Forwarded-User "%{REMOTE_USER}e"
+
+# Alternative: if using mod_auth_openidc or similar OAuth/OIDC module:
+# RequestHeader set X-Forwarded-User "%{OIDC_CLAIM_preferred_username}e"
+```
+
+Also ensure the upstream Kanboard server only accepts connections from the reverse proxy (for example, firewall rules, binding Kanboard to `127.0.0.1`, or allowing only the proxy IP).
 
 ### Setting Up Kanboard
 
-Create a custom `config.php` file or copy the `config.default.php` file:
+Since Kanboard version 1.2.49, it is mandatory to configure the `TRUSTED_PROXY_NETWORKS` option when enabling reverse proxy authentication.
+This setting specifies the list of trusted proxy networks in CIDR format that are permitted to set the authentication header.
+
+For instance, if your reverse proxy operates on the same server as Kanboard, you can configure it as follows: `127.0.0.1/32,::1/128`.
 
 ```php
-<?php
+define('TRUSTED_PROXY_NETWORKS', '127.0.0.1/32,::1/128');
+```
 
+Then, enable reverse proxy authentication by adding the following configuration to your `config.php` file.
+
+```php
 // Enable/disable reverse proxy authentication
 define('REVERSE_PROXY_AUTH', true); // Set this value to true
 
@@ -57,9 +128,17 @@ define('REVERSE_PROXY_EMAIL_HEADER', 'REMOTE_EMAIL');
 define('REVERSE_PROXY_FULLNAME_HEADER', 'REMOTE_NAME');
 ```
 
-{{< hint type="info" >}}
-- If the proxy is the same web server that runs Kanboard, according to the [CGI protocol](http://www.ietf.org/rfc/rfc3875), the header name will be `REMOTE_USER`. For example, Apache adds `REMOTE_USER` by default if `Require valid-user` is set.
-- If you use a different header for `REVERSE_PROXY_USER_HEADER`, the value must be prefixed by `HTTP_`, all hyphens must be replaced by underscores, and the string must be in all capitals because it is fetched from the `$_SERVER` array. For example, `X-Proxy-Username` becomes `HTTP_X_PROXY_USERNAME`.
-- If Apache is a reverse proxy to another Apache running Kanboard, the header `REMOTE_USER` is not set (the same behavior applies to IIS and Nginx).
-- If you have a real reverse proxy, the [HTTP ICAP draft](http://tools.ietf.org/html/draft-stecher-icap-subid-00#section-3.4) proposes the header to be `X-Authenticated-User`. This de facto standard has been adopted by several tools.
-{{</ hint >}}
+#### Custom Header Names
+
+If you want to use a custom HTTP header for `REVERSE_PROXY_USER_HEADER` option, you must follow PHP's `$_SERVER` variable naming convention:
+
+1. Prefix the header name with `HTTP_`
+2. Convert to uppercase
+3. Replace hyphens with underscores
+
+**Examples:**
+
+- `X-Proxy-Username` → `HTTP_X_PROXY_USERNAME`
+- `X-Authenticated-User` → `HTTP_X_AUTHENTICATED_USER`
+
+**Note:** The standard `REMOTE_USER` header is an exception and does not require the `HTTP_` prefix.