Identity Integration
This guide covers the real authentication model in a10e-manager: the [auth] section of a10e.toml, the two SSO providers it supports (Auth0 and WorkOS), and the JWT session flow that follows a successful login.
The [auth] Configuration
Section titled “The [auth] Configuration”[auth]provider = "local"jwt_secret = "change-me"auth0_domain = ""auth0_audience = ""auth0_bypass = false
# Only used when provider = "workos"workos_client_id = ""workos_jwks_url = ""workos_issuer = ""workos_audience = ""workos_api_key = ""workos_role_map = ""workos_default_role = ""| Field | Purpose |
|---|---|
provider |
Which authentication provider is active: local, auth0, or workos. |
jwt_secret |
Signing secret for locally-issued session tokens. Required in every deployment — generate one with openssl rand -base64 32 and never reuse it across environments. |
auth0_domain |
Your Auth0 tenant domain (for example https://your-tenant.us.auth0.com), used when provider = "auth0". |
auth0_audience |
The API audience registered in Auth0 for token validation. |
auth0_bypass |
Development-only flag to skip Auth0 token verification. Leave false outside local development. |
workos_client_id |
The WorkOS client ID for your project. |
workos_jwks_url / workos_issuer / workos_audience |
WorkOS JWT verification settings — where to fetch signing keys and what issuer/audience to expect on incoming tokens. |
workos_api_key |
API key used for server-side calls to WorkOS (for example organization lookups). |
workos_role_map |
Maps WorkOS roles to Alien Giraffe’s user/admin/super_admin roles. |
workos_default_role |
The role assigned to a user with no mapped WorkOS role. |
Configuration resolves in this order: built-in defaults → a10e.toml → the operator config overlay at /etc/a10e/config.toml (see Persistent Platform Configuration) → environment variables → CLI flags. In practice, set the baseline in a10e.toml and override secrets like jwt_secret with an environment variable in production.
Choosing A Provider
Section titled “Choosing A Provider”The default for local development and evaluation. Sessions are issued and validated entirely by a10e-manager itself, with no external identity provider involved. This is what a10e.toml.example ships with (provider = "local").
Use this when your organization already runs Auth0. Set:
[auth]provider = "auth0"jwt_secret = "generated-secret"auth0_domain = "https://your-tenant.us.auth0.com"auth0_audience = "https://a10e.company.com"auth0_bypass = falseOn first login, a user record is created with the default role user, and the profile (email, name, avatar) is synced from Auth0’s /userinfo endpoint. Subsequent logins refresh the profile and increment the login count. See Users And Roles for what happens after authentication — role assignment, activation state, and the admin endpoints that manage accounts.
If your deployment uses Auth0 Organizations, the organization claim on the token is mapped to a local organization; an unmapped organization claim is rejected rather than silently defaulted, except when the deployment has exactly one organization, in which case a token with no organization claim falls back to it.
workos
Section titled “workos”Use this when you need to front multiple enterprise identity providers (Okta, Azure AD, Google Workspace, SAML, and others) without configuring each one individually in a10e-manager — WorkOS handles those connections upstream and presents a single normalized identity to the platform. Set:
[auth]provider = "workos"jwt_secret = "generated-secret"workos_client_id = "client_..."workos_jwks_url = "https://api.workos.com/sso/jwks/client_..."workos_issuer = "https://api.workos.com/user_management/client_..."workos_audience = "client_..."workos_api_key = "sk_live_..."workos_role_map = ""workos_default_role = "user"Unlike Auth0, an unmapped WorkOS organization claim is not rejected outright — the platform confirms the organization exists via the WorkOS API and auto-provisions a matching local organization the first time it’s seen. As with Auth0, a token with no organization claim falls back to the deployment’s sole organization when exactly one exists.
Exact values for workos_client_id, workos_jwks_url, workos_issuer, and workos_audience come from your WorkOS project’s dashboard — configure the connections you need (Okta, Azure AD, Google Workspace, etc.) there, not in a10e.toml.
Session Flow
Section titled “Session Flow”- The user authenticates against the configured provider (Auth0 or WorkOS), or against the local provider directly.
a10e-managervalidates the resulting token and resolves the organization it belongs to.- A user record is created or updated, and a session begins.
- The dashboard and CLI use the resulting session/JWT for all subsequent API calls.
Next Steps
Section titled “Next Steps”- Users And Roles — the role model, admin endpoints, and business rules that apply once a user is authenticated.
- Secret Isolation — how
jwt_secretand other credentials are kept out of application logic.