2.6 KiB

Raw Blame History

ADR-005: Bearer Token Authentication as Primary Auth Method

Date: 2026-05-15
Status: Accepted
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`)

Token auth is default when truenas_token_auth is not explicitly set (or default to requiring it in new plugin)
Validation at startup: in run_lun_command, validate credentials presence before any API call
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:

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

2.6 KiB Raw Blame History