kandev/docs/decisions/0050-plugin-external-auth-capability.md

0050 — Plugins provide OIDC/SAML login via a capability-gated, host-minted session

• Status: accepted
• Date: 2026-07-26
• Area: backend, security, protocol
• Related: 0043 — Plugin host data API, Opt-in authentication, docs/specs/auth/spec.md, docs/specs/plugins/spec.md

Context

Kandev's opt-in auth (ADR 2026-07-24) ships a provider-based identity schema — auth_identities(provider, subject) with UNIQUE(provider, subject) — and says "OIDC/SSO can be added by inserting rows with a new provider … no migration required." What it did not provide was a way for a plugin to do that insertion and establish a session, so an external IdP (OIDC/SAML) could be delivered as an out-of-tree plugin rather than baked into the host.

The plugin capability model (ADR 0043) is a set of capability-gated Host gRPC RPCs the plugin calls, plus host→plugin events and a proxied inbound webhook (/api/plugins/{id}/webhooks/{key}, already on the auth public allowlist). None of these can establish an authenticated browser session.

The architectural constraint that shaped this decision: the kandev_session cookie must be set on the HTTP response to the browser. A Host gRPC RPC runs on the go-plugin broker channel, not the browser's HTTP connection, so it cannot set that cookie. The only plugin→browser HTTP path is the webhook response. Therefore session establishment must happen on the webhook response path, regardless of whether a new RPC exists.

Decision

Add an auth plugin capability and a capability-gated login directive on the plugin webhook response. An auth-capable plugin, after validating an IdP token/assertion in its webhook handler (the OIDC callback / SAML ACS), returns a reserved header X-Kandev-Auth-Login whose value is a JSON assertion {provider, subject, email, display_name}. The host webhook relay:

1. Always consumes and strips the directive header, so a plugin-controlled value can never reach the browser.
2. Interprets it only when the plugin declares capabilities.auth — a plugin that emits the directive without the capability is rejected (403), not silently ignored.
3. Calls auth.Service.AuthenticateExternal, which maps the assertion to a user (existing identity → link-by-email → JIT-provision a member), mints a session, and the host sets the kandev_session cookie itself. The email-linking step is trust-sensitive: the plugin MUST only assert an email the IdP verified as owned by the subject, otherwise a spoofed email claim is an account takeover. As defense-in-depth the host refuses to auto-link to an admin account (ErrSSOAdminLinkForbidden) — new users are members and an admin can only be reached through a link deliberately established while they were a member — but it cannot itself distinguish a verified email from an unverified one; that guarantee is the plugin's.
4. Drops any plugin-supplied Set-Cookie header on the webhook relay, so a plugin cannot overwrite the minted session cookie or fixate any other.

The plugin never receives the raw session token. Its authority is limited to asserting who the user is; the host owns minting, cookie flags, and the session lifecycle. AuthenticateExternal only operates in ModeEnabled, never creates or elevates an admin, and rejects disabled accounts. Sessions are the existing DB-backed opaque cookies, so per-user scoping, revocation, and user-disable apply to SSO sessions unchanged.

We deliberately did not add a Host.AuthenticateExternalIdentity RPC that returns the token to the plugin: it cannot set the browser cookie anyway, and handing the raw session token to the plugin is strictly weaker.

Consequences

• OIDC/SAML ships as an out-of-tree plugin using only the existing webhook transport; no proto/gRPC contract change, no schema migration.
• The auth capability is the highest-privilege capability in the system — a plugin holding it can log a visitor in as any (or a new) user. It must only be granted to operator-trusted plugins; treat it like admin install.
• Dropping plugin Set-Cookie on the webhook relay is a small behavior change for existing webhook plugins (they had no legitimate reason to set cookies).
• Login-screen discovery (landed). A plugin declares login buttons via a manifest auth_providers block ({id, display_name, initiate}, initiate naming one of its webhook keys). plugins.Service.SSOProviders() aggregates those from active, auth-capable plugins into initiate URLs, and the anonymous /api/v1/app-state boot payload carries them as auth.ssoProviders; the pre-auth login page renders one button per provider. No pre-auth plugin JS runs — the button is a plain navigation to the plugin's initiate webhook.
• Not yet built: setup-mode bootstrap of the first admin via SSO is out of scope (SSO requires ModeEnabled); the OIDC/SAML plugin implementations live in their own repos (e.g. kandev-plugin-google-oidc).

Alternatives considered

• A Host RPC that returns the session token to the plugin. Rejected: the RPC channel cannot set the browser cookie, so the plugin would still set it via the webhook response — the same path — while additionally holding the raw token. More coupling, weaker security, and a proto change for no gain.
• A plugin-registered HTTP route / middleware seam. Rejected: a far larger surface (arbitrary route registration, request interception) than SSO needs; the existing public-allowlisted webhook already receives the callback.
• First-party OIDC/SAML in the host. Still possible later, but the point of this work is to prove the capability path so IdP integrations live and ship independently of the monorepo.