Skip to main content

​
Overview

Xloud 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 Xloud administrator if you do not have sufficient permissions.

​
Token Format Reference

Token TypeStorageValidationUse Case
FernetNone (stateless)Decrypted locally using key repositoryDefault. Recommended for all deployments.
JWTNone (stateless)Verified locally via public keyAlternative 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 Xloud (e.g., in a sidecar proxy or API gateway).

​
Fernet Key Rotation

Fernet uses a key repository with three key roles:
Key RolePositionDescription
Primary1Used to sign all new tokens
Secondary2+Used to validate tokens signed by previous primary keys
Staged0Pre-positioned key that will become the next primary on rotation

Configure rotation schedule

XDeploy 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, XDeploy 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. XDeploy’s rotation playbook handles synchronization automatically.

​
Token Lifetime Configuration

Token lifetime is configured in XDeploy 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)
ParameterDefaultRecommendedNotes
keystone_token_expiration36003600 (1 hour)Reduce for high-security environments
keystone_allow_expired_window172800172800 (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.