| 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 and connected to Cloud: Check `http://your-server:19999/api/v3/info` and inspect the `cloud` section. Use `cloud.status` to verify whether the agent is connected to Netdata Cloud, and if it is not `online`, inspect `cloud.reason` for the failure details |
| 127 | - If needed, run `sudo netdatacli aclk-state` to diagnose the ACLK connection |
| 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 | ``` |