From: Thomas Lamprecht <t.lamprecht@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH v2 docs 7/19] user management: document the API token policy
Date: Sun, 15 Nov 2026 20:40:28 +0100 [thread overview]
Message-ID: <20261115194043.3947825-8-t.lamprecht@proxmox.com> (raw)
In-Reply-To: <20261115194043.3947825-1-t.lamprecht@proxmox.com>
Describe the new datacenter token-policy option next to the general
API token section, so admins who need to fulfill compliance
requirements find the enforcement options in one place. The option
reference itself is generated from the datacenter.cfg schema.
Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
---
changes since v1:
- adapt to 'disallow-expiry-extension'
- warn to only configure the policy once all nodes are upgraded
- note that it applies to tokens created by other tools too, like PDM
pveum.adoc | 44 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 44 insertions(+)
diff --git a/pveum.adoc b/pveum.adoc
index 1413faf..9370664 100644
--- a/pveum.adoc
+++ b/pveum.adoc
@@ -115,6 +115,50 @@ To use an API token, set the HTTP header 'Authorization' to the displayed value
of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
refer to your API client's documentation.
+[[pveum_token_policy]]
+Token Policy
+~~~~~~~~~~~~
+
+The optional `token-policy` datacenter option sets cluster-wide rules for
+creating and updating API tokens, as compliance standards like PCI DSS,
+SOC 2, or ISO 27001 often require, most notably a limited credential
+lifetime. The policy can require an expiration date for new tokens, limit
+how far in the future the expiration date can be set, forbid extending the
+expiration date of existing tokens, and require privilege separation.
+
+WARNING: The policy is enforced by the nodes that handle a token request,
+so in a cluster, only configure it once all nodes run a version supporting
+it. Nodes running an older version ignore the policy, and changing
+datacenter options on such a node removes it from the configuration.
+
+Changing the policy requires `Sys.Modify` on `/`, like any other datacenter
+option. Configure it in the web interface under *Datacenter -> Options ->
+API Token Policy*, or on the command line:
+
+[source,bash]
+----
+pvesh set /cluster/options --token-policy max-lifetime=7776000
+----
+
+`max-lifetime` is set in seconds (7776000 above is 90 days), while the web
+interface takes days. It counts from when the expiration date is set, that
+is on token creation or when an update changes it, and implies
+`require-expiry`, as a token without an expiration date would exceed any
+maximum lifetime.
+
+The policy only applies when a token is created or updated, and only to
+values that actually change. Existing tokens stay valid even if they do not
+conform to a policy configured later, and unrelated updates of such tokens
+keep working. A new expiration date must be within the limit. With
+`disallow-expiry-extension`, the expiration date of an existing token can
+only be shortened, or set if it has none. Tokens can always be deleted and
+recreated.
+
+NOTE: The policy also applies to tokens that other tools create through the
+API, for example when adding the cluster as a remote to Proxmox Datacenter
+Manager. If such a tool cannot create a compliant token, create one manually
+and use that in the tool instead.
+
[[pveum_resource_pools]]
Resource Pools
--------------
--
2.47.3
next prev parent reply other threads:[~2026-11-15 19:42 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-15 19:40 [PATCH v2 cluster/access-control/docs/manager/proxmox 0/19] fix #7805: add a datacenter-wide API token policy Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 cluster 1/19] datacenter config: add token-policy option Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 cluster 2/19] datacenter config: token policy: add default-to-max-lifetime setting Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 cluster 3/19] datacenter config: token policy: allow extension on regeneration Thomas Lamprecht
2026-11-17 13:30 ` Shannon Sterz
2026-11-15 19:40 ` [PATCH v2 access-control 4/19] fix #7805: api: token: enforce datacenter token policy Thomas Lamprecht
2026-11-17 13:30 ` Shannon Sterz
2026-11-15 19:40 ` [PATCH v2 access-control 5/19] api: token: apply the default lifetime from the " Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 access-control 6/19] api: token: allow extending tokens on secret regeneration Thomas Lamprecht
2026-11-15 19:40 ` Thomas Lamprecht [this message]
2026-11-15 19:40 ` [PATCH v2 docs 8/19] user management: document the default-to-max-lifetime setting Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 docs 9/19] user management: document extending tokens on secret regeneration Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 10/19] ui: token edit: only submit the expiration date when changed Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 11/19] api: cluster options: return token-policy without Sys.Audit Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 12/19] ui: dc options: allow editing the API token policy Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 13/19] ui: token edit: adapt to the datacenter " Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 14/19] ui: token policy: expose the default-to-max-lifetime setting Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 manager 15/19] ui: token policy: allow extension on secret regeneration Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 proxmox 16/19] access-control: add API token policy type with expiry checks Thomas Lamprecht
2026-11-17 13:29 ` Shannon Sterz
2026-11-15 19:40 ` [PATCH v2 proxmox 17/19] access-control: enforce token policy on token create and update Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 proxmox 18/19] access-control: apply a default token lifetime from the policy Thomas Lamprecht
2026-11-15 19:40 ` [PATCH v2 proxmox 19/19] access-control: allow extending tokens on secret regeneration Thomas Lamprecht
2026-11-17 13:29 ` Shannon Sterz
2026-11-17 13:29 ` [PATCH v2 cluster/access-control/docs/manager/proxmox 0/19] fix #7805: add a datacenter-wide API token policy Shannon Sterz
2026-11-18 2:17 ` applied: " Thomas Lamprecht
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261115194043.3947825-8-t.lamprecht@proxmox.com \
--to=t.lamprecht@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox