From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id B5E431FF0B4 for ; Tue, 10 Nov 2026 16:05:33 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 86C76216AB; Tue, 10 Nov 2026 16:05:19 +0100 (CET) Mime-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=UTF-8 Date: Tue, 10 Nov 2026 16:05:09 +0100 Message-Id: To: "Thomas Lamprecht" , Subject: Re: [PATCH docs 3/9] user management: document the API token policy X-Mailer: aerc 0.20.0 References: <20260923210000.4031318-1-t.lamprecht@proxmox.com> <20260923210000.4031318-4-t.lamprecht@proxmox.com> In-Reply-To: <20260923210000.4031318-4-t.lamprecht@proxmox.com> From: "Shannon Sterz" X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794323109559 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.486 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: QLN443MWBKA6PWU5WG4P25U7HIJIIIN7 X-Message-ID-Hash: QLN443MWBKA6PWU5WG4P25U7HIJIIIN7 X-MailFrom: s.sterz@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: On Wed Sep 23, 2026 at 10:59 PM CEST, Thomas Lamprecht wrote: > 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 > --- > pveum.adoc | 34 ++++++++++++++++++++++++++++++++++ > 1 file changed, 34 insertions(+) > > diff --git a/pveum.adoc b/pveum.adoc > index d089cb6..0849657 100644 > --- a/pveum.adoc > +++ b/pveum.adoc > @@ -115,6 +115,40 @@ To use an API token, set the HTTP header 'Authorizat= ion' to the displayed value > of the form `PVEAPIToken=3DUSER@REALM!TOKENID=3DUUID` when making API re= quests, or > refer to your API client's documentation. > > +[[pveum_token_policy]] > +Token Policy > +~~~~~~~~~~~~ > + > +The optional `token-policy` datacenter option sets cluster-wide rules fo= r > +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, limi= t > +how far in the future the expiration date can be set, forbid changing th= e > +expiration date of existing tokens, and require privilege separation. > + > +Changing the policy requires `Sys.Modify` on `/`, like any other datacen= ter > +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=3D7776000 > +---- > + > +`max-lifetime` is set in seconds (7776000 above is 90 days), while the w= eb > +interface takes days. It counts from when the expiration date is set, th= at > +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 toke= ns > +keep working. Extending the expiration date within the limit stays possi= ble > +too, unless `disallow-expiry-changes` is set, which forbids any change o= f > +the expiration date after creation; such tokens can still be deleted and > +recreated. > + imo a warning here that the policy will not be enforced by nodes that aren't updated in a cluster would be nice here. while this this is maybe obvious, this is a compliance feature. so being transparent about such limitations could safe costly a back-and-forth with auditors. > [[pveum_resource_pools]] > Resource Pools > --------------