Token Configuration

Overview

Polystack Identity uses Fernet tokens by default — stateless, symmetric-key-encrypted tokens that do not require a database lookup on every validation request. This guide covers token format selection, Fernet key rotation procedures, and lifetime configuration. Proper token configuration balances security (short lifetimes) with operational convenience (longer windows for automation pipelines).

Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

Token Format Reference

Token Type	Storage	Validation	Use Case
Fernet	None (stateless)	Decrypted locally using key repository	Default. Recommended for all deployments.
JWT	None (stateless)	Verified locally via public key	Alternative to Fernet with standard JWT tooling.

Fernet is the recommended format for all deployments. JWT tokens are useful when you need to validate tokens outside of Polystack (e.g., in a sidecar proxy or API gateway).

Fernet Key Rotation

Fernet uses a key repository with three key roles:

Key Role	Position	Description
Primary	`1`	Used to sign all new tokens
Secondary	`2+`	Used to validate tokens signed by previous primary keys
Staged	`0`	Pre-positioned key that will become the next primary on rotation

Configure rotation schedule

the deployment console manages Fernet key rotation automatically via a scheduled cron job. Configure the rotation interval in your deployment globals:

Fernet key rotation schedule

keystone_fernet_key_rotation: "0 */24 * * *"  # Every 24 hours
keystone_fernet_max_active_keys: 3             # Primary + 1 secondary + staged

Rotate keys manually

To trigger an immediate rotation outside the scheduled window:

Rotate Fernet keys

keystone-manage fernet_rotate \
  --keystone-user keystone \
  --keystone-group keystone

After rotation, the deployment console synchronizes the new key set to all Identity API nodes.

Verify key synchronization

All nodes must have identical key files:

Check key file timestamps on all nodes

ls -la /var/lib/kolla/config_files/fernet-keys/

All nodes report the same key files with matching timestamps.

Rotate keys on all Identity API nodes simultaneously. Keys not in sync across nodes cause token validation failures. The deployment console’s rotation playbook handles synchronization automatically.

Token Lifetime Configuration

Token lifetime is configured in the deployment console globals. Shorter lifetimes improve security but increase re-authentication overhead for users and automation pipelines.

Token lifetime settings

keystone_token_expiration: 3600        # Default token lifetime in seconds (1 hour)
keystone_allow_expired_window: 172800  # Allow expired tokens for re-issue (48 hours)

Parameter	Default	Recommended	Notes
`keystone_token_expiration`	3600	3600 (1 hour)	Reduce for high-security environments
`keystone_allow_expired_window`	172800	172800 (48 hours)	Allows token re-issuance without password re-entry

For long-running automation jobs, use application credentials rather than increasing token lifetime. Application credentials can be scoped, restricted, and rotated independently of user accounts.

Verify Token Configuration

Issue a token and inspect its expiry

openstack token issue -f json | python3 -c "
import json, sys, datetime
t = json.load(sys.stdin)
expires = datetime.datetime.fromisoformat(t['expires'].replace('Z', '+00:00'))
now = datetime.datetime.now(datetime.timezone.utc)
print(f'Expires: {t[\"expires\"]}')
print(f'Valid for: {(expires - now).seconds // 60} minutes')
"

Next Steps

Security Hardening

Enforce MFA requirements and audit token usage patterns.

Architecture

Understand how Fernet keys flow through the distributed Identity service.

Admin Troubleshooting

Diagnose token validation failures caused by key synchronization issues.

Application Credentials

Create long-lived automation credentials as an alternative to extended token lifetimes.

Core Services

Other Services

Overview

Token Format Reference

Fernet Key Rotation

Configure rotation schedule

Rotate keys manually

Verify key synchronization

Token Lifetime Configuration

Verify Token Configuration

Next Steps

Security Hardening

Architecture

Admin Troubleshooting

Application Credentials

​Overview

​Token Format Reference

​Fernet Key Rotation

Configure rotation schedule

Rotate keys manually

Verify key synchronization

​Token Lifetime Configuration

​Verify Token Configuration

​Next Steps

Security Hardening

Architecture

Admin Troubleshooting

Application Credentials

Overview

Token Format Reference

Fernet Key Rotation

Token Lifetime Configuration

Verify Token Configuration

Next Steps