Overview
Xloud Identity runs as a distributed service with API endpoints fronted by HAProxy. The token validation path is on every service’s critical path — all Xloud services call the Identity API to validate incoming requests. Understanding the architecture is essential for sizing, high availability planning, and troubleshooting.Service Topology
Component Reference
| Component | Port | Description |
|---|---|---|
| Identity API (v3) | 5000 | Authentication, token issuance, and service catalog |
| HAProxy | 5000 | Load balances API requests across all Identity API nodes |
| MariaDB | 3306 | Persistent storage for users, projects, roles, domains, and catalog |
| Fernet Key Repository | — | Symmetric keys for stateless token signing and encryption |
| LDAP (optional) | 389/636 | External user directory for enterprise AD/LDAP integration |
| Federation (optional) | — | SAML 2.0 or OIDC IdP integration |
Authentication Flow
High Availability Considerations
Stateless token validation
Stateless token validation
Fernet tokens are stateless — no database lookup is needed to validate them. The
Identity API decrypts the token locally using the Fernet key repository. This means
token validation scales horizontally without database pressure, and any Identity
API node can validate any token as long as all nodes share the same Fernet key set.
Fernet key synchronization
Fernet key synchronization
All Identity API nodes must have identical Fernet key sets. XDeploy manages
key distribution automatically during rotation. If nodes become out of sync,
tokens signed by one node cannot be validated by another.Verify key consistency:All nodes must report the same count and file timestamps.
Check key file count on all nodes
Database redundancy
Database redundancy
The Identity database is a MariaDB Galera cluster in a multi-node deployment.
Identity writes (user creation, role assignments) are replicated synchronously
across all MariaDB nodes. HAProxy in front of MariaDB distributes read operations.
Deployment Footprint
Identity API container
/etc/keystone
keystone.conf
policy.yaml
/etc/keystone/fernet-keys
Next Steps
Authentication Backends
Configure SQL, LDAP, and federation authentication drivers.
Token Configuration
Set Fernet key rotation schedules and token lifetime policies.
Security Hardening
Enforce MFA, audit assignments, and apply hardening best practices.
Admin Troubleshooting
Diagnose token validation failures and service communication issues.