apexlnc 225ca63127
feat(auth): Add built-in OIDC browser auth flow (#1233)
Add built-in `oidc` browser authentication to the Rust runtime.

This PR introduces a self-contained `oidc` traffic policy for local
config. The gateway can start the authorization code flow with PKCE,
handle the callback itself, exchange the code for tokens, validate the
returned ID token, and persist an encrypted browser session cookie. That
gives users a built-in browser auth path without requiring an external
`oauth2-proxy` sidecar.

The feature is route-owned rather than globally dispatched. A route is
protected by attaching `oidc` to it, and the route that matches the
callback path is the route whose effective OIDC policy completes the
flow and owns the resulting browser session. Listener-level OIDC config
is lowered into route-phase policy attachments, but callback handling
still happens through normal route selection rather than a separate
callback registry or listener interception path.

Provider setup supports the two expected local-config modes:
- issuer-based discovery
- fully explicit `authorizationEndpoint`, `tokenEndpoint`, and `jwks`
configuration

At the config boundary, local OIDC compilation owns discovery, JWKS
loading, endpoint validation, and policy construction. The runtime OIDC
surface is kept focused on browser-flow behavior: redirects, callback
processing, token exchange, ID-token validation, and browser session
handling. The stored post-login redirect target is sanitized when
captured so callback completion only reflects local in-gateway
destinations.

This PR also:
- wires `OIDC_COOKIE_SECRET` through core config/bootstrap
- updates the generated schema and docs for the new policy
- adds a local Keycloak-backed `examples/oidc` example
- keeps `examples/oauth2-proxy` updated as the documented external
sidecar alternative

This is local-config only. Built-in logout, post-logout redirects,
refresh or access token persistence, and xDS/controller-managed OIDC
config remain out of scope for this first cut.
2026-04-01 08:05:40 -07:00
..

OIDC browser auth

This example shows the built-in oidc flow for browser authentication.

It uses:

  • Keycloak as a local OIDC issuer
  • one OIDC-protected route that serves both app traffic and the /oauth/callback path
  • the standard JWT claims surface (jwt.sub, jwt.email) in access logs after login

Running the example

Start the demo dependencies:

docker compose -f examples/oidc/docker-compose.yaml up -d

Export the required browser-auth cookie secret, then start agentgateway:

export OIDC_COOKIE_SECRET="$(python3 -c 'import os; print(os.urandom(32).hex())')"
cargo run -- -f examples/oidc/config.yaml

Open http://localhost:3000 in a browser. The gateway redirects to Keycloak, completes the code flow itself, and then returns to the protected upstream app.

Use these demo credentials:

  • username: testuser
  • password: testpass

Configuration:

frontendPolicies:
  accessLog:
    add:
      user.id: jwt.sub
      user.email: jwt.email
binds:
- port: 3000
  listeners:
  - name: default
    protocol: HTTP
    routes:
    - name: app
      matches:
      - path:
          pathPrefix: /
      backends:
      - host: localhost:18080
      policies:
        oidc:
          issuer: http://localhost:7080/realms/agentgateway
          clientId: agentgateway-browser
          clientSecret: agentgateway-secret
          redirectURI: http://localhost:3000/oauth/callback
          scopes:
          - profile
          - email

Stop the demo with:

docker compose -f examples/oidc/docker-compose.yaml down