Proxy / Header Authentication

Proxy authentication lets Ideon delegate identity verification entirely to a trusted reverse proxy. When enabled, Ideon reads the user identity from HTTP headers your proxy injects and signs the user in automatically — no OAuth flow, no password prompt.

This is useful for deployments where access is already controlled upstream: mTLS-verified nginx, Traefik with ForwardAuth, Authelia, Vouch, or any similar setup.

How it works

When a user hits the proxy, the proxy verifies their identity (certificate, SSO, MFA, etc.) and forwards the request to Ideon with identity headers attached. Ideon reads those headers, looks up or creates the user account, and issues a session.

The flow:

1. User accesses Ideon through the reverse proxy.
2. Proxy verifies the user and injects identity headers.
3. Proxy redirects the user to /api/auth/proxy-sign-in.
4. Ideon validates the internal proxy secret, reads the headers, and signs the user in.

Environment variables

Variable	Required	Default	Description
AUTH_PROXY_ENABLED	Yes	false	Set to true to enable proxy auth.
AUTH_PROXY_SECRET	Yes	—	A shared secret sent by the proxy in x-proxy-secret.
AUTH_PROXY_HEADER_USER	No	x-remote-user	Header containing the username or display name.
AUTH_PROXY_HEADER_EMAIL	No	x-remote-email	Header containing the user's email address. Required.
AUTH_PROXY_AUTO_PROVISION	No	false	Set to true to automatically create accounts for unknown users.

nginx example

map $ssl_client_s_dn $client_cn {
  default "";
  ~CN=([^,\/]+) $1;
}
map $ssl_client_s_dn $client_email {
  default "";
  ~E=([^,\/]+) $1;
}

server {
  server_name ideon.example.com;
  listen 443 ssl;

  ssl_certificate     /path/to/server-fullchain.pem;
  ssl_certificate_key /path/to/server-key.pem;

  ssl_client_certificate /path/to/ca.pem;
  ssl_verify_client on;
  ssl_verify_depth 2;

  if ($ssl_client_verify != SUCCESS) {
    return 403;
  }

  location / {
    proxy_pass http://localhost:3000/;

    proxy_set_header Host               $host;
    proxy_set_header X-Real-IP          $remote_addr;
    proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto  $scheme;

    proxy_set_header X-Remote-User      $client_cn;
    proxy_set_header X-Remote-Email     $client_email;
    proxy_set_header X-Proxy-Secret     your-shared-secret;
  }
}

Replace your-shared-secret with the value of AUTH_PROXY_SECRET.

Auto-provisioning

When AUTH_PROXY_AUTO_PROVISION=true, Ideon creates a new account on first sign-in if no user with the given email exists. The username is derived from the email prefix or the AUTH_PROXY_HEADER_USER header value. The account is created with the member role.

When AUTH_PROXY_AUTO_PROVISION=false (the default), users must already have an account in Ideon. Unknown emails are redirected to /login?error=ProxyAuthNoAccount.

Audit log

All proxy sign-in events are recorded in the audit log under the loginProxy action, with success or failure status and the failure reason when applicable. This applies to both provisioned and existing users.

Security considerations

• The AUTH_PROXY_SECRET header must be kept confidential. It is the only mechanism preventing a direct request to /api/auth/proxy-sign-in from bypassing authentication. Ensure the Ideon instance is not directly reachable from the internet — only the proxy should be able to reach it.
• Proxy auth does not replace other authentication modes. Email/password, OAuth, and SAML remain available in parallel.
• If the AUTH_PROXY_HEADER_EMAIL header is missing or empty, the sign-in is rejected.