OIDC Authentication

EdgePlane supports OIDC JWT validation alongside static token auth for MCP compatibility. This guide covers server configuration, CLI login flows, and Kubernetes secret management.

Server Environment Variables

AUTH_MODE=oidc
OIDC_REQUIRED=false
OIDC_ISSUER_URL=https://<your-idp>/application/o/<provider-slug>/
OIDC_AUDIENCE=<oidc-client-id>
OIDC_CLIENT_ID=<oidc-client-id>
OIDC_CLIENT_SECRET=<optional-for-confidential-clients>
OIDC_REDIRECT_URI=https://<edgeplane-host>/auth/oidc/callback
OIDC_SCOPES=openid profile email
EP_ADMIN_SUBJECTS=<comma-separated-subjects>
EP_ADMIN_EMAILS=<comma-separated-emails>
# optional — auto-discovered if omitted
# OIDC_JWKS_URL=https://<your-idp>/application/o/<provider-slug>/jwks/

Split Internal / Public Issuer

When the API container reaches the IdP via a private address (e.g. a Kubernetes ClusterIP) but browsers must redirect to a public hostname:

# Server-side: token discovery, JWKS fetch, iss validation
OIDC_ISSUER_URL=http://<cluster-ip>/application/o/<slug>/
OIDC_INTERNAL_ISSUER_URL=http://<cluster-ip>/application/o/<slug>/

# Browser-side: authorize_url returned to CLI and web — never validated against JWT claims
OIDC_PUBLIC_ISSUER_URL=https://<public-idp-host>/application/o/<slug>/

Rule: OIDC_ISSUER_URL must match the iss claim in issued JWTs. OIDC_PUBLIC_ISSUER_URL only rewrites the authorize_url returned to browsers and CLI clients.

# 1. Initiate — get a browser URL and a cli_nonce
curl -s https://<edgeplane-host>/auth/oidc/cli-initiate
# → {"authorize_url": "https://...", "cli_nonce": "...", "expires_at": "..."}

# 2. Open authorize_url in your browser and complete login.
#    The success page shows a grant_id (olg_…).

# 3. Exchange the grant_id for a session token
curl -s -X POST https://<edgeplane-host>/auth/oidc/exchange \
  -H "Content-Type: application/json" \
  -d '{"grant_id": "olg_…"}'
# → {"token": "mcs_…", "subject": "…", "expires_at": "…"}

# 4. Save the session token (edgeplane reads this automatically)
cat > ~/.edgeplane/session.json <<EOF
{"token":"mcs_…","subject":"…","email":"…","expires_at":"…","base_url":"https://<edgeplane-host>","session_id":1}
EOF
chmod 600 ~/.edgeplane/session.json

Polling instead of copy-paste:

curl -s https://<edgeplane-host>/auth/oidc/cli-poll/<cli_nonce>
# → {"status":"ready","grant_id":"olg_…"}  (404 until login completes)

With edgeplane auth login:

export EP_BASE_URL="https://<edgeplane-host>"
edgeplane auth login --ttl-hours 8
edgeplane auth whoami

EdgePlane uses a backend PKCE flow:

Browser requests GET /auth/oidc/start
Server redirects to IdP authorize endpoint with PKCE challenge
IdP returns to GET /auth/oidc/callback
Server exchanges auth code, validates token, issues one-time grant
Browser calls POST /auth/oidc/exchange to receive mcs_* session token

Auth Mode Reference

`AUTH_MODE`	Behavior
`token`	Static bearer token only
`oidc`	OIDC JWT only
`dual`	Accept both — recommended for staged migration

OIDC_REQUIRED=true in dual mode enforces OIDC for non-/mcp paths. MCP agent connections use service account tokens or node JWTs.

Staged Rollout (Recommended)

For production deployments adopting OIDC on an existing instance:

Set AUTH_MODE=oidc, OIDC_REQUIRED=false — OIDC available but not enforced
Validate CLI and web login flows work end-to-end
Optionally switch to AUTH_MODE=dual for a transition period
Optionally set OIDC_REQUIRED=true when all clients have migrated
Later: migrate MCP clients to service-account OIDC and remove static token

Kubernetes Secret Management

Never commit OIDC client secrets, service tokens, or static tokens to Git.

# Create a Secret with all auth env vars
apiVersion: v1
kind: Secret
metadata:
  name: edgeplane-auth
type: Opaque
stringData:
  AUTH_MODE: "oidc"
  OIDC_ISSUER_URL: "https://..."
  OIDC_CLIENT_ID: "..."
  OIDC_CLIENT_SECRET: "..."
  EP_ADMIN_EMAILS: "..."

Mount in the deployment:

envFrom:
- secretRef:
    name: edgeplane-auth

Token Types

Token type	Description	Recommended for
Session token (`mcs_*`)	DB-backed, revocable, expiring	Interactive CLI/web use
Service account (`mcs_sa_*`)	Long-lived, programmatic	MCP clients, CI pipelines
Node JWT	Per-node RS256 JWT	`edgeplaned` daemon, machine-to-machine
OIDC JWT	Short-lived, identity-bound	SSO environments (exchanged for session token)

Session tokens are the recommended auth mechanism for interactive use. They are revocable, expiring, and never written to agent config files on disk.