From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id E48AF1FF09D for ; Sun, 15 Nov 2026 20:42:29 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 19D11217F0; Sun, 15 Nov 2026 20:41:07 +0100 (CET) From: Thomas Lamprecht 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 Message-ID: <20261115194043.3947825-8-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261115194043.3947825-1-t.lamprecht@proxmox.com> References: <20261115194043.3947825-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794771649484 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.077 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: BYKZQAT3F2XDADFLJV4A5EX3CD25R6SO X-Message-ID-Hash: BYKZQAT3F2XDADFLJV4A5EX3CD25R6SO X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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