Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cake.ai/llms.txt

Use this file to discover all available pages before exploring further.

Header authentication lets a trusted upstream proxy (for example, oauth2-proxy, NGINX auth_request, or an Istio ext-authz filter) sign users in to Cake Agents by forwarding their identity in HTTP headers. When a request arrives without an existing session cookie, the server reads the configured headers, upserts the user, and creates a Better Auth session for the request. Use this when your platform already terminates SSO at the edge and you want Cake Agents to inherit that identity without a second login.

​
How it works

On every request without an active session:
  1. The server checks the configured JWT header. If present, it decodes the token (no signature verification; the upstream proxy is trusted) and reads the email and name claims.
  2. If the JWT is missing or does not contain the claims, the server falls back to the configured email and name headers.
  3. If an email is found, the server looks up the user by email. If no user exists, one is created with that email and name.
  4. The server creates a new Better Auth session and sets a signed session cookie on the response so subsequent requests reuse the cookie.
Requests that already carry a valid session cookie are passed through unchanged. Header auth never overrides an existing Better Auth session. If a request already carries a valid session cookie, header auth is a no-op for that request.
The server trusts whatever the configured headers contain. Only enable header auth behind a proxy that strips these headers from external traffic and injects them itself.

​
Configuration

Header auth is off by default. Configure it through the Helm chart’s headerAuth values, which map to environment variables on the web deployment.
Helm valueEnvironment variableDefaultDescription
headerAuth.enabledCAKE_HEADER_AUTH_ENABLEDfalseEnables the plugin.
headerAuth.email.headerCAKE_HEADER_AUTH_EMAIL_HEADERunsetHeader that carries the user’s email when no JWT is present.
headerAuth.email.claimCAKE_HEADER_AUTH_EMAIL_CLAIMemailJWT claim that contains the user’s email.
headerAuth.jwt.headerCAKE_HEADER_AUTH_JWT_HEADERunsetHeader that carries an unsigned JWT with identity claims (decoded only).
headerAuth.user.headerCAKE_HEADER_AUTH_USERunsetHeader that carries the user’s display name when no JWT is present.
headerAuth.user.claimCAKE_HEADER_AUTH_USER_CLAIMnameJWT claim that contains the user’s display name.
You must set at least one of headerAuth.jwt.header or headerAuth.email.header for the plugin to do anything. If only the JWT header is set, the email and name come from JWT claims. If only plain headers are set, the JWT step is skipped. If both a JWT and plain headers are present, JWT claims take precedence and plain headers are used as fallbacks for whichever field the JWT does not provide.

​
Example: oauth2-proxy in front of Cake Agents

This values.yaml snippet enables header auth and reads identity from headers that oauth2-proxy injects:
values.yaml
headerAuth:
  enabled: true
  email:
    header: X-Forwarded-Email
    claim: email
  user:
    header: X-Forwarded-Preferred-Username
    claim: name
If your proxy forwards an unsigned JWT instead of plain headers, point headerAuth.jwt.header at it and adjust the claim names if they differ from the defaults:
values.yaml
headerAuth:
  enabled: true
  jwt:
    header: X-Forwarded-Access-Token
  email:
    claim: email
  user:
    claim: preferred_username

​
Notes

  • Requests with internal Cake email addresses are rejected before a user is created. This is enforced by the internal email plugin, regardless of which header the email came from.
  • The session created by header auth is a regular Better Auth session and is visible to /api/auth/get-session and other Better Auth endpoints.
  • Header auth runs alongside SSO and the OAuth provider, so you can enable it together with oidc for users who hit the app directly.