Authentication Architecture

Technical reference for Eneo’s OIDC authentication system, including protocol details, security mechanisms, and internal components.

OIDC Protocol Flow

Eneo implements the OAuth 2.0 Authorization Code Flow with OpenID Connect. Both single-tenant and multi-tenant setups go through the same public endpoints (/api/v1/auth/initiate and /api/v1/auth/callback) and use server-signed state JWTs (HS256) for security.

Overview

Flow Steps Explained

Security Mechanisms

Eneo Session Identity

Eneo-issued browser, internal MCP and module tokens share one identity contract:

After signature, issuer, audience and time validation, the backend resolves the account by both user_id and tenant_id. Deleted accounts and mismatched identity claims cannot authenticate. Account and tenant state checks and normal resource permissions still apply. A name or email change cannot transfer an existing session to another account, including one with the same username.

The identity contract belongs to Eneo session tokens. Identity-provider tokens are validated separately during OIDC login and exchanged for an Eneo session.

Deploying the identity contract

The transition requires users to sign in again. Pre-upgrade Eneo and module tokens, and pending module login tickets, are rejected; there is no fallback to username or email authentication. Module applications must restart the login handoff on an authentication failure.

Update all API instances and workers together, draining old instances before serving traffic with the new deployment. Old instances still resolve sessions by username and must not remain in a rolling deployment. No account rename, account merge or database migration is needed for this change. A recovery build must retain the identity validation; rolling back to username-based authentication reintroduces the vulnerability.

State Token (CSRF Protection)

The state parameter is a JWT signed with HS256:

# federation_router.py
state_payload: OIDCStatePayload = {
    "tenant_id": str(tenant_obj.id),
    "tenant_slug": tenant_obj.slug or tenant_obj.name,
    "frontend_state": state or "",
    "nonce": secrets.token_hex(16),
    "redirect_uri": redirect_uri,
    "correlation_id": correlation_id,
    "exp": int(time.time()) + settings.oidc_state_ttl_seconds,
    "iat": int(time.time()),
    "config_version": tenant_config_version,
}
signed_state = pyjwt.encode(
    cast(dict[str, Any], state_payload), settings.jwt_secret, algorithm="HS256"
)

Key parameters:

An expired state is rejected with 400 Authorization session expired. Please try logging in again.; a state that fails signature validation is rejected with 400 Invalid state parameter.

Redis State Cache

# federation_router.py
state_cache_payload: OIDCStateCache = {
    "tenant_id": str(tenant_obj.id),
    "tenant_slug": tenant_obj.slug or tenant_obj.name,
    "redirect_uri": redirect_uri,
    "config_version": tenant_config_version,
    "iat": state_payload["iat"],
}
state_cache_key = f"oidc:state:{state_payload['nonce']}"
 
await redis_client.setex(
    state_cache_key,
    settings.oidc_state_ttl_seconds,
    json.dumps(state_cache_payload, separators=(",", ":")),
)

The cache is best-effort:

The key is deleted when the callback finishes, whether it succeeded or failed, so a state cannot be replayed while Redis is available.

Redirect URI Grace Period

When tenant federation configuration changes (e.g., updating canonical_public_origin), users mid-authentication could encounter redirect URI mismatches. The grace period mechanism prevents failed logins during configuration updates.

How it works:

# federation_router.py
grace_period = min(
    settings.oidc_redirect_grace_period_seconds,
    settings.oidc_state_ttl_seconds,
)
 
if redirect_mismatch:
    if not settings.strict_oidc_redirect_validation:
        allow_redirect_mismatch = True
    else:
        # grace-period checks, see table below
        ...

The redirect_uri carried in the state is first checked for well-formedness and then compared with the tenant’s currently configured redirect URIs (canonical plus additional_redirect_uris). On a mismatch:

• strict_oidc_redirect_validation = false: any well-formed redirect_uri from the state is accepted.
• strict_oidc_redirect_validation = true (default): the old redirect_uri is accepted only if all of the following hold:

Otherwise the callback fails with 400 Redirect URI mismatch - authentication flow invalid. This may occur if tenant configuration changed during login. ….

Token Auth Method Selection

The backend automatically selects the token endpoint authentication method from IdP discovery:

# federation_router.py
def _select_auth_method(methods: list[str] | None) -> str | None:
    if not methods:
        return None
    normalized = [str(m).lower() for m in methods if m]
    if "client_secret_post" in normalized:
        return "client_secret_post"
    if "client_secret_basic" in normalized:
        return "client_secret_basic"
    return normalized[0]

Selection priority:

Any other method selected from discovery is logged as unsupported and replaced by client_secret_post.

Tenant State Validation

Authentication is blocked for non-active tenants at both initiate and callback stages. Both return 403 Forbidden:

State Tamper Detection

When the cached state is available, the callback validates that the tenant context in the signed state matches the cached state to detect tampering:

# federation_router.py
expected_tenant_id = cached_state["tenant_id"]
if expected_tenant_id and expected_tenant_id != str(tenant_id):
    ...
    raise HTTPException(
        status_code=status.HTTP_400_BAD_REQUEST,
        detail=(
            "Authorization state mismatch detected. "
            "Please restart the sign-in flow."
        ),
        headers={"X-Correlation-ID": correlation_id},
    )

Validation checks:

Both checks return 400 with the same detail and are logged as callback.state_tampered debug events with reason set to tenant_id_mismatch or tenant_slug_mismatch. The checks only run when Redis returned a cached state; the signed JWT itself is always verified.

Multi-Tenant Federation Architecture

Tenant Resolution

When federation is enabled (FEDERATION_ENABLED=true) and more than one active tenant exists, the login page has to know which tenant’s IdP to use. Eneo does not derive the tenant from the hostname; the frontend resolves it in this order:

Slugs must match ^[a-z0-9-]+$. The selector lists every active tenant that has a slug, regardless of whether federation is configured for it; a tenant without an IdP fails at /auth/initiate with 500 No identity provider configured for tenant '{slug}'.

On the backend, GET /api/v1/auth/initiate without a tenant parameter auto-selects the tenant when exactly one active tenant exists and otherwise returns 400 Tenant parameter required when multiple tenants exist.

Federation Config Storage

Federation config is stored in the federation_config JSONB column of the tenants table. PUT …/federation fetches the discovery document immediately and stores the resolved endpoints alongside the request fields:

Secret Encryption

Client secrets are encrypted using Fernet (AES-128-CBC + HMAC-SHA256):

Key generation:

uv run python -m eneo.cli.generate_encryption_key

ID Token Validation

Claims Validated

The backend validates these claims (auth_service.py):

Clock skew tolerance: 120 seconds (2 minutes) - configurable via oidc_clock_leeway_seconds

User Claims Extracted

Only the email claim is used. The claim name comes from claims_mapping.email (default email); the ID token’s sub is logged for diagnostics but not persisted:

# federation_router.py
claims_mapping: OIDCClaimsMapping = federation_config.get(
    "claims_mapping"
) or {"email": "email"}
email_claim = claims_mapping.get("email", "email")
...
email = payload.get(email_claim)

A missing claim is rejected with 401 Email claim not found in ID token; a malformed address with 401 Email claim from identity provider is invalid. Contact your administrator.

Domain Validation

When allowed_domains is configured, email domains are compared case-insensitively using IDNA2008. Unicode and punycode forms of the same domain match; distinct domains such as faß.de and fass.de do not. A non-matching domain is rejected with:

403 Email domain '{domain}' is not allowed for this organization. Contact your administrator to add your domain.

Global OIDC uses OIDC_ALLOWED_DOMAINS (JSON array, default []); per-tenant federation uses allowed_domains. An empty list leaves existing active tenant members unrestricted by domain, but cannot admit new members through JIT. The federation callback records admission refusals as callback.user_denied with a reason.

JIT Provisioning

UserService.resolve_federated_user is the single admission owner for the federation callback and the global OIDC/MobilityGuard login endpoint. It reuses the active account in the configured tenant, rejects inactive accounts and cross-tenant matches, and checks for removed rows before considering account creation. The removed-account lookup is tenant-scoped and tests for existence because several historical rows can share an email.

FederatedIdentity.from_claims receives validated token claims and preserves only a valid email address and its verification status. Values such as "true" or 1 do not count as verification. When email is selected through a custom claims mapping, standard email_verified only authorizes JIT if the selected address equals the standard email claim.

Provisioning is a per-tenant flag set through the sysadmin API (POST /api/v1/sysadmin/tenants/{id}/). Keep it false when SCIM manages membership. A SCIM token does not implicitly change this setting. SCIM or an administrator can restore an account; login cannot.

New accounts use state=ACTIVE, the email local part as username (falling back to the full email, then no username, on collisions), and the tenant’s default role. Without a default role they have no roles and a warning is logged. Both paths write USER_CREATED with actor SYSTEM and provisioning_method: jit_federation; audit-log failure does not prevent account creation.

JWKS Handling

The signing key is fetched with PyJWT’s PyJWKClient, constructed anew for every callback:

# federation_router.py
jwk_client = JWKClient(jwks_uri)
signing_key = jwk_client.get_signing_key_from_jwt(
    id_token
).key  # Extract raw key from PyJWK wrapper

Caching:

• No JWKS caching across requests - each callback creates a fresh client and downloads the key set
• No Redis/persistent caching for JWKS keys
• Endpoints missing from the stored config (authorization_endpoint, token_endpoint, jwks_uri) are resolved by fetching the discovery document, also without caching. API-configured tenants have these stored at PUT/PATCH time; the environment-variable configuration only has discovery_endpoint, so discovery is fetched on every login

A JWKS fetch or key lookup failure is reported as 401 Failed to validate ID token signature.

Configuration Parameters

From config.py:

Federation Admin API

Endpoints

All paths are relative to /api/v1/sysadmin and return 404 Federation is not enabled unless FEDERATION_ENABLED=true.

Authentication: X-API-Key header with the super admin API key (ENEO_SUPER_API_KEY).

PUT and PATCH (when discovery_endpoint changes) fetch the discovery document before saving and fail with 400 if it is unreachable or lacks issuer, authorization_endpoint, token_endpoint or jwks_uri. Every change writes a FEDERATION_UPDATED audit event.

Test Endpoint Behavior

POST /tenants/{tenant_id}/federation/test performs:

• Fetches the discovery document from the stored discovery_endpoint
• Validates HTTP 200 response
• Verifies required OIDC fields are present (issuer, authorization_endpoint, token_endpoint, jwks_uri)
• Returns {"success": true, "message": "Federation config is valid and IdP is reachable", "issuer": "…"}
• Does NOT fetch the JWKS
• Does NOT attempt authentication
• Does NOT validate client credentials

Failures are reported as 500 with the reason in detail (HTTP status from the IdP, missing fields, or connection error).

Observability

Correlation IDs

Generated with secrets.token_hex(8) → 16 hex characters.

• Created in /auth/initiate
• Embedded in state JWT
• Reused in /auth/callback
• Included in all log entries and returned as the X-Correlation-ID header on callback errors

OIDC Debug Events

Enable debug logging via the observability API (POST /api/v1/sysadmin/observability/oidc-debug/). Events follow pattern [OIDC DEBUG] {event}:

Initiate phase:

• initiate.state_cached
• initiate.state_cache_failed / initiate.state_cache_skipped
• initiate.authorization_ready

Callback phase:

• callback.state_decoded
• callback.state_cache_hit / callback.state_cache_miss
• callback.state_cache_error / callback.state_cache_unavailable / callback.state_cache_missing
• callback.state_tampered (with reason: tenant_id_mismatch or tenant_slug_mismatch)
• callback.tenant_loaded
• callback.tenant_inactive
• callback.email_extracted
• callback.user_denied
• callback.jit_provisioning
• callback.success
• callback.unexpected_error

Troubleshooting Flow

Provider-Specific Notes

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

https://keycloak.example.com/realms/{realm}/.well-known/openid-configuration

https://{tenant}.auth0.com/.well-known/openid-configuration

Public OIDC Endpoints

These endpoints do NOT require authentication: