Authentication

Hadrian uses a single [auth.mode] setting that determines how all requests are authenticated across both the API and the admin panel.

Auth Modes

Configure authentication by setting [auth.mode] in hadrian.toml. Four modes are available:

Supporting Config Sections

Deployment Scenarios

Pick the scenario closest to your deployment. Each includes a minimal working config.

1. Local development

No authentication. All requests proceed anonymously. The admin panel, chat UI, and API are all open.

[auth.mode]
type = "none"

2. API key

API keys required for all access. The admin panel shows an "enter API key" login screen. SDK and API clients send keys via headers.

[auth.mode]
type = "api_key"

[auth.api_key]
header_name = "X-API-Key"
key_prefix = "gw_"
cache_ttl_secs = 300

Getting started: Use the bootstrap API key to create the initial organization and users. Then create API keys via the admin panel for each user. Paste a key into the chat UI settings or pass it to the OpenAI SDK.

3. SSO / IdP

Per-org SSO for browser sessions, with API key and JWT support on /v1/* endpoints. Each organization configures their own OIDC or SAML provider through the Admin UI at runtime.

[auth.mode]
type = "idp"

[auth.api_key]
key_prefix = "gw_"
cache_ttl_secs = 300

[auth.session]
cookie_name = "hadrian_session"
secure = true
secret = "${SESSION_SECRET}"

[auth.bootstrap]
api_key = "${HADRIAN_BOOTSTRAP_KEY}"
auto_verify_domains = ["acme.com"]

Getting started: Use the bootstrap API key to create organizations. Each org admin then configures their IdP via the SSO Admin Guide. Users are auto-provisioned on first SSO login. Per-org SSO configs automatically enable JWT validation on /v1/* endpoints -- no global OIDC configuration needed.

4. Reverse proxy (IAP)

Trust identity headers from an authenticating reverse proxy (Cloudflare Access, Tailscale, oauth2-proxy, etc.) for admin access. API access uses API keys.

[server.trusted_proxies]
cidrs = ["173.245.48.0/20", "103.21.244.0/22"]

[auth.mode]
type = "iap"
identity_header = "Cf-Access-Authenticated-User-Email"
email_header = "Cf-Access-Authenticated-User-Email"

[auth.api_key]
key_prefix = "gw_"
cache_ttl_secs = 300

Getting started: Configure your reverse proxy to authenticate all traffic to Hadrian and forward identity headers. Create API keys via the admin panel for chat UI and SDK access.

Architecture

Default Behavior

When [auth.mode] is omitted from hadrian.toml, authentication defaults to type = "none". This means:

• API requests proceed without credentials. A default anonymous user and organization are created for usage tracking.
• Admin routes are unprotected -- the web UI works without login.
• RBAC is permissive -- all authorization checks pass automatically.

Credential Handling in No-Auth Mode

Even with type = "none", the gateway validates credentials that are explicitly provided:

This means you can incrementally adopt authentication -- existing anonymous clients continue working while authenticated clients get identity tracking and RBAC. However, clients must not send placeholder or invalid credentials.

API Key Authentication

API keys are the primary method for programmatic access to /v1/* endpoints. Keys are created via the Admin UI or API and validated against the database.

# Using X-API-Key header
curl -H "X-API-Key: gw_live_abc123..." \
  https://gateway.example.com/v1/chat/completions

# Using Authorization header (OpenAI-compatible)
curl -H "Authorization: Bearer gw_live_abc123..." \
  https://gateway.example.com/v1/chat/completions

Key features:

• Configurable prefix (gw_live_, gw_test_, etc.)
• Budget limits (daily/monthly caps)
• Expiration dates
• Usage tracking per key
• Owner binding (org, team, project, or user)

In api_key mode, API keys authenticate everything -- including the admin panel. In idp and iap modes, API keys authenticate /v1/* endpoints alongside the mode's primary mechanism.

Format-Based Detection

When both API keys and JWTs are accepted (in idp mode), the gateway uses format-based detection:

• X-API-Key header: Always validated as an API key
• Authorization: Bearer header: Tokens starting with the API key prefix (default gw_) are validated as API keys; all others are validated as JWTs

Per-Org JWT Routing

In idp mode, per-org SSO configurations automatically enable JWT validation on /v1/* endpoints. There is no global JWT configuration in the config file -- all JWT validation derives from per-org SSO configs.

How it works:

1. Decode iss claim -- Extract the issuer from the JWT without verifying the signature yet
2. Per-org registry lookup -- Search the GatewayJwtRegistry for validators matching that issuer
3. Lazy-load from DB -- On cache miss, query the database for enabled OIDC SSO configs with that issuer, perform OIDC discovery to fetch the JWKS URI, and build a validator
4. Validate -- Verify the signature, expiry, audience, and issuer against the matched validator

Key behaviors:

• Validators are cached across requests -- JWKS keys are not re-fetched per request
• Unknown issuers are negatively cached for 60 seconds to prevent DB query amplification
• When an SSO config is created or updated via the Admin API, the registry is updated immediately
• Multiple organizations can share the same issuer (each gets its own validator with its own audience)

Session-Based Authentication

In idp mode, browser sessions use session cookies set during the SSO login flow. The session cookie authenticates both /admin/* and /v1/* requests, so users log in once and the chat UI works immediately -- no API key needed.

OIDC / SSO

Full OpenID Connect flow with browser redirects. Works with any OIDC-compliant identity provider:

SAML 2.0

SAML 2.0 authentication for enterprise identity providers that require the Security Assertion Markup Language protocol:

Reverse Proxy Authentication

In iap mode, Hadrian trusts identity headers from an authenticating reverse proxy:

Just-in-Time Provisioning

Automatically create users and add them to organizations when they first authenticate via SSO.

How it works:

1. User authenticates via OIDC or SAML
2. Gateway checks if user exists in database
3. If not, creates user with attributes from the identity token
4. Adds user to the configured organization with default role
5. Optionally adds user to a default team

Capabilities:

• Create users on first login
• Assign to organization and team
• Map IdP groups to teams (SSO group mappings)
• Sync attributes on subsequent logins
• Restrict by email domain

SSO Group Mappings

Map identity provider groups to Hadrian teams for automatic team assignment during provisioning.

When a user belongs to multiple groups mapping to the same team, the highest priority determines the role.

Authorization (RBAC)

After authentication, authorization determines what users can access. Hadrian uses CEL (Common Expression Language) for fine-grained access control.

Example policies:

# Super admins have full access
[[auth.rbac.policies]]
name = "super-admin"
condition = "'super_admin' in subject.roles"
effect = "allow"
priority = 100

# Users can only access resources in their organization
[[auth.rbac.policies]]
name = "org-isolation"
condition = "context.org_id in subject.org_ids"
effect = "allow"
priority = 10

API authorization extends CEL policies to /v1/* endpoints for:

• Model access control (restrict GPT-4 to premium users)
• Token limits by tier
• Feature gating (tools, file search, reasoning)
• Time-based access (business hours only)

Related Topics