docs: add Setup Keys / PAT guide with API rename workaround
Document Setup Keys concept vs SSO, PAT creation and usage, and the workaround for renaming a setup key — the API silently ignores the name field on PUT, so the fix is to UPDATE store.db directly and restart netbird-server.
This commit is contained in:
138
setup-keys-and-pat.md
Normal file
138
setup-keys-and-pat.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Setup Keys 與 Personal Access Token (PAT)
|
||||
|
||||
本文整理 NetBird Setup Keys 的概念、PAT 的使用、以及一個 API 實作限制的繞道方法。
|
||||
|
||||
## Setup Keys：用途
|
||||
|
||||
Setup Key 是 NetBird 的 **預先認證 token**，讓裝置可以**免互動登入**直接加入網路。
|
||||
|
||||
### 兩種註冊方式
|
||||
|
||||
| 方式 | 指令/流程 | 適用 |
|
||||
|------|-----------|-------|
|
||||
| SSO 登入（互動式） | App 開瀏覽器 → OAuth2 → 授權 | 手機、筆電等個人裝置 |
|
||||
| Setup Key（非互動） | `netbird up --setup-key <UUID>` | 伺服器、容器、CI、IoT |
|
||||
|
||||
### Key 的屬性
|
||||
|
||||
- **Reusable / One-off**：一次性或可重複使用
|
||||
- **Expires**：有效期限（可設定永不過期）
|
||||
- **Peer Expiration**：加入的 peer 幾天後要重新認證
|
||||
- **Auto-assigned Groups**：自動加入指定群組
|
||||
- **Ephemeral**：peer 離線後自動清除（適合 CI / 短命容器）
|
||||
- **Usage Limit**：被使用次數上限
|
||||
|
||||
### 為什麼不建議給手機用
|
||||
|
||||
NetBird UI 會顯示警告：
|
||||
|
||||
> *Using setup keys for user devices is not recommended. SSO with MFA provides stronger security, proper user-device association, and periodic re-authentication.*
|
||||
|
||||
- 沒有使用者歸屬，Activity Log 難追溯
|
||||
- 缺少 MFA
|
||||
- 沒有週期性重新認證
|
||||
- token 形式是一串 UUID，外洩後任何人都能加入
|
||||
|
||||
**推薦做法**：個人裝置（手機、筆電）走 SSO；機器/自動化用 Setup Key。
|
||||
|
||||
## Personal Access Token (PAT)：API 存取
|
||||
|
||||
要用 NetBird API 操作資源（list、revoke、建立 setup key 等），需要一把 PAT。
|
||||
|
||||
### 如何建立 PAT
|
||||
|
||||
1. Dashboard → **Team → Users → 你自己 → Personal Access Tokens → Create Token**
|
||||
2. 填：
|
||||
- **Name**：易辨識的名稱（例：`Claude-API`、`admin-cli`、`ansible`）
|
||||
- **Expires in**：`1` – `365` 天（**強制有期限**，無法永不過期）
|
||||
3. 按 **Create Token** → Token 只會顯示**一次**，務必立刻複製保存
|
||||
|
||||
### PAT 為什麼強制有效期限
|
||||
|
||||
這是安全設計：就算 token 外洩，風險也有上限。建議做法：
|
||||
- 用密碼管理器（1Password、Bitwarden 等）存放
|
||||
- 命名包含用途（方便日後識別哪把是哪把）
|
||||
- 到期前 Dashboard 會有提醒
|
||||
- 長期用途（例如 IaC 腳本），排進年度維運任務重建
|
||||
|
||||
### PAT API 用法
|
||||
|
||||
```bash
|
||||
TOKEN=nbp_xxxxxxxx
|
||||
|
||||
# 列出所有 setup keys
|
||||
curl -sf -H "Authorization: Token $TOKEN" \
|
||||
https://netbird.timmy.us.kg/api/setup-keys | jq
|
||||
|
||||
# 查看單一 setup key
|
||||
curl -sf -H "Authorization: Token $TOKEN" \
|
||||
https://netbird.timmy.us.kg/api/setup-keys/<ID> | jq
|
||||
|
||||
# Revoke 一把 setup key
|
||||
curl -X PUT -H "Authorization: Token $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"...", "auto_groups":[], "revoked":true}' \
|
||||
https://netbird.timmy.us.kg/api/setup-keys/<ID>
|
||||
```
|
||||
|
||||
## 陷阱：API 無法更新 Setup Key 的名稱
|
||||
|
||||
### 症狀
|
||||
|
||||
對 `PUT /api/setup-keys/<id>` 送出含 `"name":"新名字"` 的 payload，API 回 **HTTP 200** 且 `updated_at` 有更新，但 `name` 實際**沒變**。
|
||||
|
||||
### 原因
|
||||
|
||||
NetBird 的 setup-key update handler **只處理 `auto_groups` 和 `revoked`** — `name`、`type`、`expires` 這些欄位在 API 層被視為建立時固定，payload 裡的值會被忽略。
|
||||
|
||||
### 繞道做法：直接改 SQLite
|
||||
|
||||
NetBird 伺服器用 SQLite (`/var/lib/netbird/store.db`) 存狀態。繞過 API 直接 UPDATE 資料表，再重啟 `netbird-server` 讓快取重載。
|
||||
|
||||
```bash
|
||||
# 步驟 1：把 DB 從容器拷貝出來（容器內沒裝 sqlite3 CLI）
|
||||
docker cp netbird-server:/var/lib/netbird/store.db /tmp/store.db
|
||||
|
||||
# 步驟 2：改名
|
||||
sqlite3 /tmp/store.db \
|
||||
"UPDATE setup_keys SET name='iPhone-15-Pro' WHERE id='d7h3p5mfs58s73f6qdr0'"
|
||||
|
||||
# 確認
|
||||
sqlite3 /tmp/store.db 'SELECT id, name FROM setup_keys'
|
||||
|
||||
# 步驟 3：覆蓋回容器 + 重啟 server（讓記憶體快取失效）
|
||||
docker cp /tmp/store.db netbird-server:/var/lib/netbird/store.db
|
||||
cd /opt/netbird
|
||||
docker compose restart netbird-server
|
||||
|
||||
# 步驟 4：用 API 驗證
|
||||
curl -sf -H "Authorization: Token $TOKEN" \
|
||||
https://netbird.timmy.us.kg/api/setup-keys | jq '.[] | {id, name}'
|
||||
```
|
||||
|
||||
重啟 `netbird-server` 會短暫中斷 gRPC 連線，**執行中的 peer 會自動重連**，約 5-10 秒內恢復。
|
||||
|
||||
### 替代做法
|
||||
|
||||
如果不想動 DB：**Revoke 舊 key，建立新 key 並命名正確**。缺點是已用那把 key 註冊的 peer 不受影響（peer 註冊成功後 key 已解耦），但任何依賴那把 key 的自動化腳本要更新。
|
||||
|
||||
## 其他可直接改 SQLite 的場景
|
||||
|
||||
NetBird 的 API 對某些欄位是 read-only，但 DB 是可以改的（風險自負）：
|
||||
|
||||
| 欄位 | API 可改？ | DB 可改 |
|
||||
|------|----------|--------|
|
||||
| setup_keys.name | 否 | 是 |
|
||||
| setup_keys.type | 否 | 是（但多半不該改） |
|
||||
| setup_keys.expires | 否（建立時才能設） | 是 |
|
||||
| peers.name | 是（`PUT /api/peers/{id}`） | 是 |
|
||||
| users.role | 是 | 是 |
|
||||
|
||||
**建議順序**：先試 API → 不行再看 DB schema → 確認欄位意義後再改 → 改完**必須重啟 netbird-server**。
|
||||
|
||||
## 安全提醒
|
||||
|
||||
- Setup Key 跟 PAT 都等同於長效憑證，存放要當密碼看待
|
||||
- PAT 失竊 → 立刻從 Dashboard revoke
|
||||
- Setup Key 失竊 → 立刻 revoke，已註冊的 peer 不受影響但無法再用這把 key 註冊新 peer
|
||||
- 不要把任何一種 token commit 進 git repo
|
||||
Reference in New Issue
Block a user