67 lines
2.6 KiB
Markdown
67 lines
2.6 KiB
Markdown
# ADR-005: Bearer Token Authentication as Primary Auth Method
|
|
|
|
**Date**: 2026-05-15
|
|
**Status**: Decided
|
|
**Deciders**: Kevin Adams
|
|
|
|
## Context
|
|
|
|
TrueNAS SCALE and recent TrueNAS CORE versions support API key (Bearer Token) authentication. Basic auth (username + password) requires a full system user account, is less secure, and may be deprecated in future TrueNAS releases.
|
|
|
|
The `feature_bearer_token` branch already has partial support:
|
|
- `truenas_token_auth` flag (boolean)
|
|
- `truenas_secret` field (holds either password or token depending on flag)
|
|
- Bearer Token header set in `freenas_api_connect` when flag is true
|
|
|
|
## Decision
|
|
|
|
Bearer Token auth should be the **primary** and recommended authentication method. Basic auth remains for backward compatibility.
|
|
|
|
## Changes Required
|
|
|
|
### In `LunCmd/FreeNAS.pm` (and future `Custom/TrueNASPlugin.pm`)
|
|
|
|
1. **Token auth is default** when `truenas_token_auth` is not explicitly set (or default to requiring it in new plugin)
|
|
2. **Validation at startup**: in `run_lun_command`, validate credentials presence before any API call
|
|
3. **Error messages** should guide users toward token auth when credentials are missing
|
|
|
|
### In the UI (Custom Plugin properties)
|
|
|
|
The new custom storage plugin defines these properties:
|
|
```perl
|
|
truenas_token_auth => {
|
|
description => "Use API Token instead of username/password",
|
|
type => 'boolean',
|
|
default => 1, # Default to token auth in the new plugin
|
|
},
|
|
truenas_secret => {
|
|
description => "TrueNAS API Token or Password",
|
|
type => 'string',
|
|
},
|
|
freenas_user => {
|
|
description => "TrueNAS Username (only needed without token auth)",
|
|
type => 'string',
|
|
optional => 1,
|
|
},
|
|
```
|
|
|
|
PVE auto-generates the UI form — the `freenas_user` field would be conditionally hidden in the UI when `truenas_token_auth` is true. This hiding behavior in the auto-generated form may need to be tested against PVE 8.x's form rendering.
|
|
|
|
### Generating an API Token in TrueNAS
|
|
|
|
TrueNAS SCALE: System → API Keys → Add
|
|
TrueNAS CORE: This may require web UI access or direct CLI.
|
|
|
|
The token is a long random string; it goes in the `truenas_secret` field. No username needed with token auth.
|
|
|
|
## Backward Compatibility
|
|
|
|
- Existing configs using `freenas_password` + `freenas_user` continue to work
|
|
- The custom plugin should map legacy fields on first load
|
|
- `freenas_password` is aliased to `truenas_secret` for backward compat
|
|
|
|
## Security Notes
|
|
|
|
- Tokens should be scoped to minimum needed permissions if TrueNAS supports scoped tokens
|
|
- The secret is stored in `/etc/pve/storage.cfg` (PVE cluster config) — it is not encrypted but the file is only readable by root
|