Docs: Add bearer token protection as recommended security method (#21712)
* Docs: Add bearer token protection as recommended security method Add documentation for bearer token protection feature which allows users to secure direct access to Netdata agents using Netdata Cloud SSO with a single configuration setting. Changes: - Add dedicated page for bearer token protection configuration - Add bearer token as first recommended method in security guide - Add callouts to all reverse proxy guides pointing to the simpler alternative - Document which APIs remain unprotected and why * Fix naming convention: capitalize Agents and Parents * Fix broken documentation link to claim README
Costa Tsaousis committed
Feb 6, 2026 at 10:17 UTC
a50eaa53324a0a610c2fab32e95857d2ec7573e6
9 files changed
+225
-1
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/README.md
+12
@@ -1,5 +1,17 @@
1
# Running Netdata Behind a Reverse Proxy
2
3
+:::tip Simpler Alternative for Netdata Cloud Users
4
+
5
+If you use Netdata Cloud (free or paid), consider [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) instead. With a single setting (`bearer token protection = yes`), you get:
6
+
7
+- **Cloud SSO authentication** - Users sign in through Netdata Cloud
8
+- **Role-based access** - Cloud roles apply to direct agent access
9
+- **No proxy setup required** - No nginx, Apache, or htpasswd configuration
10
+
11
+Reverse proxy setup is still valuable if you need custom authentication, don't use Netdata Cloud, or require offline access.
12
+
13
+:::
14
+
15
You can improve security and capabilities by running your Netdata Agent behind another web server in production environments. This approach lets you secure access to the dashboard with SSL, user authentication, and firewall rules while providing more robustness and capabilities than the Agent's [internal web server](/src/web/README.md).
16
17
## Supported Reverse Proxy Solutions
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-apache.md
+6
@@ -159,6 +159,12 @@ Repeat the operation for as many servers as you need.
159
160
## Enable Basic Auth
161
162
+:::tip Simpler Alternative
163
+
164
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or Apache auth configuration needed.
165
+
166
+:::
167
+
168
If you wish to add an authentication (user/password) to access your Netdata, do these:
169
170
Install the package `apache2-utils`. On Debian/Ubuntu run `sudo apt-get install apache2-utils`.
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-caddy.md
+10
@@ -20,6 +20,16 @@ netdata.domain.tld {
20
}
21
```
22
23
+## Protect access to Netdata
24
+
25
+:::tip Simpler Alternative
26
+
27
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no Caddy auth configuration needed.
28
+
29
+:::
30
+
31
+For Caddy-based authentication, refer to the [Caddy documentation on authentication](https://caddyserver.com/docs/caddyfile/directives/basicauth).
32
+
33
## limit direct access to Netdata
34
35
You would also need to instruct Netdata to listen only to `127.0.0.1` or `::1`.
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-h2o.md
+6
@@ -102,6 +102,12 @@ necessary to specify inside the H2O configuration that the final destination is
102
103
### Enable authentication
104
105
+:::tip Simpler Alternative
106
+
107
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or H2O auth configuration needed.
108
+
109
+:::
110
+
111
Create an authentication file to enable basic authentication via H2O, this secures your Netdata dashboard.
112
113
If you don't have an authentication file, you can use the following command:
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-haproxy.md
+6
@@ -160,6 +160,12 @@ backend netdata_backend
160
161
## Enable authentication
162
163
+:::tip Simpler Alternative
164
+
165
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no HAProxy userlist configuration needed.
166
+
167
+:::
168
+
169
To use basic HTTP Authentication, create an authentication list:
170
171
```text
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-lighttpd.md
+9
-1
@@ -29,7 +29,15 @@ then you can get away with just
29
proxy.server = ( "" => ( ( "host" => "127.0.0.1", "port" => 19999 )))
30
```
31
32
-Though if it's public facing, you might then want to put some authentication on it. `htdigest` support looks like:
32
+Though if it's public facing, you might then want to put some authentication on it.
33
+
34
+:::tip Simpler Alternative
35
+
36
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htdigest files or lighttpd auth configuration needed.
37
+
38
+:::
39
+
40
+`htdigest` support looks like:
41
42
```text
43
auth.backend = "htdigest"
docs/netdata-agent/configuration/running-the-netdata-agent-behind-a-reverse-proxy/Running-behind-nginx.md
+6
@@ -179,6 +179,12 @@ If Nginx is not configured as described here, you will probably receive the erro
179
180
### Enable authentication
181
182
+:::tip Simpler Alternative
183
+
184
+If you use Netdata Cloud, [Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md) provides authentication with a single setting - no htpasswd files or nginx auth configuration needed.
185
+
186
+:::
187
+
188
Create an authentication file to enable basic authentication via Nginx, this secures your Netdata dashboard.
189
190
If you don't have an authentication file, you can use the following command:
docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md
new
+146
@@ -0,0 +1,146 @@
1
+# Secure Your Netdata Agent with Bearer Token Protection
2
+
3
+Netdata provides native bearer token protection that integrates with Netdata Cloud Single Sign-On (SSO). With a single configuration setting, you can secure direct access to your Netdata Agents and Parents while inheriting the same permissions and roles your users have in Netdata Cloud.
4
+
5
+## Who Can Use This
6
+
7
+Bearer token protection is available to all Netdata Cloud users:
8
+
9
+- **Community plan** (free)
10
+- **Business plan** (paid)
11
+
12
+Your agent must be [claimed to Netdata Cloud](/src/claim/README.md) to use this feature.
13
+
14
+## How It Works
15
+
16
+When bearer token protection is enabled:
17
+
18
+1. Users visit your agent's dashboard directly (e.g., `http://your-server:19999`)
19
+2. The agent redirects them to Netdata Cloud for authentication
20
+3. After successful Cloud SSO login, users receive a time-limited bearer token
21
+4. The token grants access based on their Netdata Cloud role (Admin, Manager, Troubleshooter, etc.)
22
+5. Tokens expire after 24 hours and are automatically renewed through Cloud
23
+
24
+This means:
25
+
26
+- **Single Sign-On**: Users authenticate once via Netdata Cloud
27
+- **Role-Based Access**: Cloud roles and permissions apply to direct agent access
28
+- **Centralized Control**: Manage access through Netdata Cloud, not per-agent configurations
29
+- **No Password Files**: No htpasswd files or reverse proxy auth configuration needed
30
+
31
+## Enable Bearer Token Protection
32
+
33
+Edit your `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script:
34
+
35
+```bash
36
+cd /etc/netdata
37
+sudo ./edit-config netdata.conf
38
+```
39
+
40
+Add or modify the `[web]` section:
41
+
42
+```ini
43
+[web]
44
+ bearer token protection = yes
45
+```
46
+
47
+Restart Netdata to apply:
48
+
49
+```bash
50
+sudo systemctl restart netdata
51
+```
52
+
53
+## What Gets Protected
54
+
55
+When enabled, bearer token protection secures **all data APIs**, including:
56
+
57
+- Metrics and charts (`/api/v3/data`, `/api/v3/allmetrics`)
58
+- Alerts (`/api/v3/alerts`, `/api/v3/alert_transitions`)
59
+- Contexts and nodes (`/api/v3/contexts`, `/api/v3/nodes`)
60
+- Functions (`/api/v3/function`, `/api/v3/functions`)
61
+- Dynamic configuration (`/api/v3/config`)
62
+
63
+## What Remains Public
64
+
65
+**Static web files** (HTML, CSS, JavaScript) in Netdata's web directory are **not protected**. This means:
66
+
67
+- Users can still download and view the dashboard UI
68
+- The dashboard will load but **won't display any data**
69
+- All API calls from the dashboard will fail until the user authenticates
70
+
71
+This is by design - it allows the dashboard to redirect users to Netdata Cloud for authentication.
72
+
73
+A small set of APIs also remain publicly accessible for operational reasons:
74
+
75
+| API | What it exposes |
76
+|-----|-----------------|
77
+| `/api/v3/info` | Agent version, OS, build info, capabilities |
78
+| `/api/v3/me` | Current user authentication status |
79
+| `/api/v3/claim` | Agent claiming endpoint (protected by separate security key) |
80
+| `/api/v3/stream_info` | Streaming connection statistics |
81
+| `/api/v2/claim` | Agent claiming endpoint (v2, protected by security key) |
82
+| `/api/v1/registry?action=hello` | Node list, machine GUIDs, cloud connection status |
83
+| `/api/v1/manage/health` | Alert silencing (protected by separate X-Auth-Token) |
84
+
85
+These APIs are required for the authentication flow and dashboard initialization. The registry `hello` action returns node identifiers and cloud connection status, which the dashboard needs to initiate the authentication redirect.
86
+
87
+**Note:** Other v1 and v2 APIs (like `/api/v2/info`, `/api/v3/versions`, `/api/v3/progress`) **are protected** by bearer token - only the specific endpoints listed above bypass protection.
88
+
89
+## Requirements
90
+
91
+- Agent must be claimed to Netdata Cloud
92
+- ACLK connection must be active (agent connected to Cloud)
93
+- Users must have a Netdata Cloud account with access to the space containing the agent
94
+
95
+## Comparison with Other Methods
96
+
97
+| Method | Setup Complexity | SSO | Centralized Management | Works Offline |
98
+|--------|-----------------|-----|----------------------|---------------|
99
+| **Bearer Token Protection** | Single setting | Yes | Yes | No |
100
+| Reverse Proxy + Basic Auth | High (proxy + htpasswd) | No | No | Yes |
101
+| IP-Based Restrictions | Medium | No | No | Yes |
102
+| Disable Dashboard | Single setting | N/A | N/A | N/A |
103
+
104
+Choose bearer token protection when you want the simplest setup with Cloud SSO integration. Choose reverse proxy if you need custom authentication, don't use Netdata Cloud, or require offline access.
105
+
106
+## Combining with Other Security Measures
107
+
108
+Bearer token protection can be combined with:
109
+
110
+- **TLS/SSL encryption**: Configure [TLS in Netdata](/src/web/server/README.md#examples) for encrypted connections
111
+- **IP restrictions**: Add `allow connections from` to limit which IPs can even attempt to connect
112
+- **Firewall rules**: Block port 19999 from untrusted networks
113
+
114
+Example combining bearer token with IP restrictions:
115
+
116
+```ini
117
+[web]
118
+ bearer token protection = yes
119
+ allow connections from = 10.* 192.168.* localhost
120
+```
121
+
122
+## Troubleshooting
123
+
124
+**Users can't authenticate:**
125
+
126
+- Verify the agent is claimed: Check `http://your-server:19999/api/v3/info` for `cloud-available: true`
127
+- Verify ACLK is connected: Look for "ACLK" status in the agent logs
128
+- Ensure users have access to the same Cloud space as the agent
129
+
130
+**Token expired errors:**
131
+
132
+- Tokens automatically renew when users have an active Cloud session
133
+- If tokens expire, users simply re-authenticate through Cloud
134
+
135
+**Want to disable temporarily:**
136
+
137
+```ini
138
+[web]
139
+ bearer token protection = no
140
+```
141
+
142
+Or via API (requires Admin/Manager role via Cloud):
143
+
144
+```
145
+POST /api/v3/bearer_protection
146
+```
docs/netdata-agent/securing-netdata-agents.md
+24
@@ -8,6 +8,30 @@ You can protect your Agents by implementing any of these security measures:
8
9
### Recommended Methods
10
11
+**Enable Bearer Token Protection (Netdata Cloud SSO)**
12
+
13
+*Best for:* Users who want direct access to agents secured by Netdata Cloud authentication
14
+
15
+You can secure direct access to your Netdata Agents and Parents with a single configuration setting. Bearer token protection integrates with Netdata Cloud SSO, so users authenticate through Cloud and inherit their Cloud roles and permissions.
16
+
17
+Edit the `[web]` section in `netdata.conf` using the [`edit-config`](/docs/netdata-agent/configuration/README.md#edit-configuration-files) script:
18
+
19
+```text
20
+[web]
21
+ bearer token protection = yes
22
+```
23
+
24
+After restart, users accessing `http://NODE:19999` will be redirected to Netdata Cloud for authentication. Their Cloud role (Admin, Manager, Troubleshooter, etc.) determines what they can access.
25
+
26
+**Requirements:**
27
+
28
+- Agent must be [claimed to Netdata Cloud](/src/claim/README.md)
29
+- Works with both Community (free) and Business plans
30
+
31
+For detailed configuration options, see [Secure Your Netdata Agent with Bearer Token Protection](/docs/netdata-agent/configuration/secure-your-netdata-agent-with-bearer-token.md).
32
+
33
+---
34
+
35
**Disable the Local Dashboard**
36
37
*Best for:* Users who monitor their systems through Netdata Cloud dashboards