66 lines
2.5 KiB
Markdown
66 lines
2.5 KiB
Markdown
# Machine & AI Assistant Authentication Guide
|
|
|
|
This guide describes how to configure programmatic, machine-to-machine, and AI assistant authentication across services protected by **Authentik** and **Traefik ForwardAuth**.
|
|
|
|
---
|
|
|
|
## 🎯 Use Case
|
|
When an AI assistant (or automation script, CLI tool, or cron job) needs to:
|
|
* Inspect Zigbee2MQTT logs or device states via `https://zigbee2mqtt.moritzgraf.de`
|
|
* Scrape or query metrics from `https://prometheus.haumdaucher.de`
|
|
* Trigger or query APIs protected behind the Traefik ForwardAuth gateway
|
|
|
|
Instead of interactive browser logins or hardcoding static basic auth credentials into individual ingress configs, Authentik supports **Service Accounts & API Tokens**.
|
|
|
|
---
|
|
|
|
## ⚙️ Setup Instructions
|
|
|
|
### 1. Create a Service Account in Authentik
|
|
1. Navigate to **Directory > Users** in Authentik (`https://auth.haumdaucher.de`).
|
|
2. Click **Create Service Account**:
|
|
* **Username**: `ai-assistant` (or `mopbot`, `cli-agent`)
|
|
* **Create API Token**: Check this box.
|
|
* **Token Expiration**: Set to never expire (or desired TTL).
|
|
3. Copy the generated **Token Secret** (e.g. `ak_tok_xxxx...`).
|
|
|
|
### 2. Grant Access Permissions
|
|
1. Go to **Directory > Groups**.
|
|
2. Add the `ai-assistant` service account to the appropriate group (e.g. `infra-admins` or `zigbee-readers`).
|
|
3. Ensure the Application/Proxy Provider policy allows this group.
|
|
|
|
---
|
|
|
|
## 💻 Making Authenticated API Calls
|
|
|
|
### HTTP Bearer Token (Recommended)
|
|
Pass the API token in the `Authorization` header:
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer <your-authentik-token>" \
|
|
https://zigbee2mqtt.moritzgraf.de/api/bridge/info
|
|
```
|
|
|
|
When Traefik ForwardAuth queries Authentik with this header, Authentik detects the Bearer token, authenticates the `ai-assistant` service account, checks permissions, and responds with HTTP `200 OK`. Traefik then proxies the request directly to the backend.
|
|
|
|
### Python / Scripting Example
|
|
|
|
```python
|
|
import requests
|
|
|
|
AUTH_TOKEN = "your-authentik-token"
|
|
headers = {
|
|
"Authorization": f"Bearer {AUTH_TOKEN}",
|
|
"Accept": "application/json"
|
|
}
|
|
|
|
response = requests.get("https://zigbee2mqtt.moritzgraf.de/api/bridge/devices", headers=headers)
|
|
print(response.json())
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Rotating & Revoking Tokens
|
|
* To rotate a token, navigate to **Directory > Tokens and App passwords**.
|
|
* You can view active tokens, inspect last-used timestamps, and revoke compromised tokens instantly with one click without restarting any Kubernetes pods or modifying ingress secrets.
|