Authentication

Authentication answers one question: who is calling? Ductor's API server accepts four credential types, each backed by a ClaimMapper that validates the credential and returns a verified authn.Principal. This page covers how each one works and how to turn it on.

At a glance

OIDC / JWT

The primary mechanism for human and machine callers alike. Ductor validates bearer JWTs against your identity provider's published keys — it never holds a shared secret for this path.

Configure

export DUCTOR_AUTH_ENABLED=true
export DUCTOR_API_OIDC_ISSUER="https://your-idp.example.com/"
export DUCTOR_API_OIDC_AUDIENCE="ductor-api"

Both issuer and audience are required; setting only one leaves OIDC inert (the JWT mapper is not registered). Clients then send:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

How validation works

• Keys (JWKS). On startup Ductor fetches the issuer's JWKS. By default the endpoint is derived as <issuer>/.well-known/jwks.json; explicit JWKS URLs can be supplied in config. Keys are cached and refreshed every 5 minutes in the background.
• Algorithms. Only asymmetric signatures are accepted — RS256 and ES256 by default. The verifier pins the allowed methods, which blocks the classic algorithm-downgrade attack (an HS256 token signed with the public key as the secret is rejected).
• Claims → Principal. sub becomes Subject (required), tenant_id → TenantID, org_id → OrgID, client_id/azp → ClientID, the space-delimited scope → Scopes, and the permissions claim (default name permissions) → Roles.
• Expiry. exp is honored with a default 1 minute of clock-skew tolerance.

Failure handling: the JWKS grace window

The subtlety worth seeing: an IdP outage does not break auth immediately. Tokens keep validating against cached keys right up to the edge of the grace window — and then flip to rejecting everything at once:

If the IdP's JWKS endpoint becomes unreachable, Ductor keeps trusting its cached keys for a bounded grace window (default 1 hour). Past that window without a successful refresh, the provider clears its cache and rejects all tokens (fail-closed) until the IdP recovers.

DB-backed API keys

Durable, revocable, per-tenant credentials for service-to-service traffic — minted and managed through the Tenant API Key API. Enable them with:

export DUCTOR_AUTH_API_KEY_ENABLED=true

Callers present the raw key in either header:

X-API-Key: duk_live_9f2c…            # preferred
Authorization: Bearer duk_live_9f2c… # also accepted

How validation works

• Ductor keys always begin with the duk_ prefix. The first 8 characters are stored as a lookup prefix, so a presented key is resolved to at most one or two candidate rows — the expensive bcrypt comparison runs against that tiny set, not every tenant key.
• The stored bcrypt hash is compared in constant time. A token that carries the duk_ prefix but is too short is rejected up front, so an attacker cannot turn a short key into a broad lookup prefix (a CPU-amplification guard).
• On success the Principal is built from the key: Subject is apikey:<id>, TenantID/Roles/Scopes/environment scope come from the row, and a fire-and-forget update stamps last_used_at.
• Only active, non-expired keys authenticate. Revoked or expired keys are rejected immediately.

See the API keys deep dive for minting, roles, scopes, environment scope, expiry, storage, and rotation.

SAML browser sessions

For enterprise SSO, Ductor runs a SAML 2.0 Service Provider. It is off by default; when disabled, no SAML route is mounted and behavior is byte-identical to a build without it.

export DUCTOR_IDENTITY_SAML_ENABLED=true
export DUCTOR_IDENTITY_SAML_SP_ENTITY_ID="https://app.example.com/saml/{tenant}/metadata"
export DUCTOR_IDENTITY_SAML_ACS_BASE_URL="https://app.example.com"   # must be HTTPS

The flow

One SP serves all tenants via per-tenant path scoping, with per-tenant IdP config managed out of band (CLI: ductor saml-idp set/get/disable). After a successful assertion at the ACS endpoint, Ductor mints an HS256 session JWT for the (tenant, NameID) pair. That token carries a fixed audience (saml_session) and issuer (ductor), the user's email and roles, a unique jti, and a default 8-hour TTL.

The browser then presents that session token as a normal Authorization: Bearer credential; the SAML session mapper verifies it. Its signing key is a per-tenant secret (minimum 32 bytes) stored AEAD-encrypted at rest.

Single Logout (SLO) and revocation

With identity.saml.slo_enabled=true, the /saml/{tenant}/slo endpoint is mounted. Both IdP-initiated and SP-initiated logout revoke the session's jti (recorded in saml_session_revocation), and an sso.logout audit event is emitted. Session verification then consults the revocation store and rejects a logged-out session even before its exp.

Service tokens (internal plane)

For coordinator-to-coordinator and worker-to-coordinator traffic on the internal transport plane, Ductor validates HS256 service tokens signed with a shared secret:

export DUCTOR_AUTH_SERVICE_TOKEN_SECRET="<32+ byte high-entropy secret>"

An empty secret disables service tokens. These carry the internal-only service role, whose scope bundle is read access plus the workflow-control surface; the internal RPC surface is additionally gated by an internal-only method option, not just by scope. Do not assign the service role to human identities.

Selecting and composing mappers

By default the API composes API key → JWT (with SAML inserted between them when enabled). To pin or compose explicitly, set auth.claim_mapper:

# Single validator
export DUCTOR_AUTH_CLAIM_MAPPER="jwt"

# Explicit chain (tried left to right; ErrMissingToken falls through)
export DUCTOR_AUTH_CLAIM_MAPPER="apikey,jwt"

Built-in factory names are jwt, apikey, and service-token (plus the SAML session factory when SAML is enabled). Operators can register custom factories via fx.Decorate(*claimmapper.Registry) and select them here by name.

Config reference