Configure OIDC authentication

By default, Holon uses local control tokens for authentication. For shared team servers or remote deployments, you can switch to OpenID Connect (OIDC). Team members log in through your existing identity provider (IdP), and Holon records which user prompted an agent.

This guide covers registering an OIDC client, configuring Holon, tuning session timeouts, and verifying logins.

Prerequisites

A running Holon instance reachable by your users (for example via --access tunnel, --access tailnet, or a reverse proxy).
An OIDC-compliant identity provider, such as Keycloak, Okta, Authentik, Google Workspace, or Microsoft Entra ID.
Administrative access in your IdP to register a new client application.

Security note: Holon requires HTTPS for the OIDC issuer URL and callback endpoints in production. HTTP is only permitted when the callback host is localhost.

Step 1: Register Holon in your IdP

Create a new OpenID Connect application in your identity provider:

Client ID: Choose an identifier, such as holon.
Client Authentication: Enable client credentials (confidential client) and generate a Client Secret.

Redirect URI: Set the callback URL:

https://<your-holon-host>/api/auth/oidc/callback

If testing locally on port 7878, use:

http://localhost:7878/api/auth/oidc/callback

Scopes: Ensure the client requests at least openid, profile, and email.

Note down the Issuer URL, Client ID, and Client Secret.

Step 2: Store the Client Secret in an environment variable

Never store client secrets in configuration files on disk. Set the secret as an environment variable where the Holon daemon runs:

export HOLON_OIDC_CLIENT_SECRET="your-oidc-client-secret"

If you run Holon as a systemd service or container, supply this variable in your service unit or environment file.

Step 3: Configure Holon

Set the authentication mode and provider parameters with holon config set:

# Switch to OIDC authentication mode
holon config set auth.mode "oidc"

# Set the issuer URL (must support OIDC discovery at /.well-known/openid-configuration)
holon config set auth.oidc.issuer_url "https://auth.example.com/realms/team"

# Set your registered Client ID
holon config set auth.oidc.client_id "holon"

# Point to the environment variable containing the secret
holon config set auth.oidc.client_secret_env "HOLON_OIDC_CLIENT_SECRET"

# Set the public callback URL (recommended behind reverse proxies)
holon config set auth.oidc.redirect_uri "https://holon.example.com/api/auth/oidc/callback"

Step 4: Configure session policies

Holon issues HttpOnly session cookies for browsers and session credentials for API clients. Configure how long sessions stay valid:

# Idle session lifetime in seconds (default: 86400, or 24 hours)
# Every user interaction refreshes this timer.
holon config set auth.session.idle_ttl_seconds 43200

# Optional absolute session lifetime in seconds (must be >= idle_ttl_seconds)
# When set, the session expires after this period regardless of activity.
holon config set auth.session.absolute_ttl_seconds 604800

To disable the absolute timeout and allow active users to stay signed in, omit auth.session.absolute_ttl_seconds or set it to null.

Step 5: Restart the daemon

Restart the daemon to apply authentication changes:

holon daemon restart

If running Holon interactively:

holon serve --access tunnel

Verify the setup

1. Log in via the Web GUI

Open https://<your-holon-host>/login in your browser.
The login page detects OIDC mode and displays a Continue with organization login link.
Click the link to redirect to your identity provider.
Sign in. The IdP redirects back to /api/auth/oidc/callback, which sets a secure holon_session cookie and lands on the dashboard (/).

2. Verify session identity

Inspect the current session using the session API:

curl -b "holon_session=<session-cookie>" https://<your-holon-host>/api/auth/session/me

Or provide the session token as a bearer credential:

curl -H "Authorization: Bearer <session-token>" https://<your-holon-host>/api/auth/session/me

The endpoint returns the authenticated user identity and authentication method:

{
  "ok": true,
  "user_id": "oidc-550e8400-e29b-41d4-a716-446655440000",
  "display_name": "Alice Chen",
  "auth_method": "oidc"
}

3. Check message attribution

In OIDC mode, every prompt sent through the control plane records the user's identity in the message origin:

actor_id: The persistent user identifier in Holon (formatted as oidc-<uuid-v4>).
actor_display_name: The user's display name at send time (falls back to actor_id if no name claim exists).

When auditing agent transcripts or inspecting messages via GET /api/agents/{agent_id}/messages/{message_id}, you can verify exactly who triggered each action.

4. Log out

To end a session, click Log out in the Web GUI or issue:

curl -X POST -H "Authorization: Bearer <session-token>" \
  https://<your-holon-host>/api/auth/session/logout

This invalidates the session record on the server and clears the browser cookie.

Troubleshooting

Redirect URI mismatch: Ensure the callback URI in your IdP matches auth.oidc.redirect_uri byte for byte, including protocol (https://), port, and trailing path (/api/auth/oidc/callback).
Invalid issuer URL: The issuer URL must match the iss claim in ID tokens and serve /.well-known/openid-configuration over HTTPS.
Secret not found: Verify that the environment variable named in auth.oidc.client_secret_env is exported in the daemon process environment.
Invalid TTL configuration: If you configure auth.session.absolute_ttl_seconds, it must be greater than or equal to auth.session.idle_ttl_seconds. Otherwise, Holon fails configuration validation on startup.