[PATCH docs 3/9] user management: document the API token policy

[Thomas Lamprecht <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>
---
 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 '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 changing the
+expiration date of existing tokens, and require privilege separation.
+
+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. Extending the expiration date within the limit stays possible
+too, unless `disallow-expiry-changes` is set, which forbids any change of
+the expiration date after creation; such tokens can still be deleted and
+recreated.
+
 [[pveum_resource_pools]]
 Resource Pools
 --------------
-- 
2.47.3