feat(oidc): optional TLS CA certificate pinning for the IdP

OIDC discovery, JWKS fetch, and token exchange used the system TLS trust
store with no pinning. A CA compromise in the system store would let an
attacker MITM the IdP, serve a forged JWKS, and sign an ID token for any
subject — authenticating as any operator (full mesh compromise). High
bar (CA compromise + network position), but the blast radius justifies
defence-in-depth.

Add an optional oidc.tls_ca_cert config field pointing to a PEM CA
bundle. When set, NewOIDC builds a dedicated *http.Client whose RootCAs
is that bundle and wires it through oidc.ClientContext before provider
discovery; go-oidc reuses the same client for the JWKS keyset, so
discovery and id_token verification are both pinned. The callback wires
the same client into the token exchange. The system trust store is left
intact for every other connection. A missing or malformed CA file fails
NewOIDC loudly rather than silently falling back to the system store.

Closes #264

Author: juev

configs/server.example.yml

@@ -126,3 +126,9 @@ allow_self_registration: false
 #   # set `default_role: "admin"` AND at least one allowlist entry (the
 #   # two-field footprint is the point).
 #   default_role: "user"                   # role for newly-federated users
+#   # Optional: pin the IdP's TLS to a specific CA bundle (#264). When set,
+#   # OIDC discovery, JWKS fetch, and token exchange trust only this PEM bundle,
+#   # so a CA compromise in the system trust store cannot MITM the IdP and forge
+#   # ID tokens. Leave unset to use the system trust store. Only affects IdP
+#   # traffic; every other connection still uses the system store.
+#   tls_ca_cert: /etc/nebula-mgmt/oidc-ca.pem

internal/config/server.go

@@ -379,6 +379,14 @@ type OIDCConfig struct {
 	// or send it in a shape HandleCallback can't decode (numeric,
 	// nested object, etc). emailVerifiedRequired() resolves nil → true.
 	RequireEmailVerified *bool `yaml:"require_email_verified,omitempty"`
+
+	// TLSCACert optionally pins the IdP's TLS trust to a PEM CA bundle at this
+	// path (#264). When set, OIDC discovery, JWKS fetch, and token exchange use
+	// a dedicated HTTP client whose RootCAs is this bundle, so a CA compromise
+	// in the system trust store cannot MITM the IdP. Empty = use the system
+	// trust store (default). The system store is untouched for every other
+	// connection.
+	TLSCACert string `yaml:"tls_ca_cert,omitempty"`
 }
 
 // EmailVerifiedRequired reports whether HandleCallback must enforce the

internal/web/oidc.go

@@ -3,11 +3,14 @@ package web
 import (
 	"context"
 	"crypto/rand"
+	"crypto/tls"
+	"crypto/x509"
 	"encoding/hex"
 	"errors"
 	"fmt"
 	"log/slog"
 	"net/http"
+	"os"
 	"strings"
 	"sync"
 	"time"
@@ -56,6 +59,12 @@ type OIDC struct {
 	// for user-role operators without coupling OIDC to Web struct.
 	// If nil, auto-provision is skipped.
 	provisionCA func(ctx context.Context, op *models.Operator) error
+
+	// httpClient is the CA-pinned HTTP client used for all IdP traffic when
+	// oidc.tls_ca_cert is configured (#264). nil means the system trust store
+	// is used (default). When set it is wired into discovery/JWKS at provider
+	// creation and into the callback's token exchange via oidc.ClientContext.
+	httpClient *http.Client
 }
 
 // SetCookieSecure controls the Secure attribute on the OIDC state cookie.
@@ -77,6 +86,21 @@ func NewOIDC(ctx context.Context, cfg *config.OIDCConfig, s store.Store, sm *Ses
 	if cfg.Issuer == "" || cfg.ClientID == "" || cfg.RedirectURL == "" {
 		return nil, fmt.Errorf("oidc: issuer, client_id, redirect_url are required")
 	}
+	// When tls_ca_cert is configured, pin all IdP traffic to that CA bundle by
+	// running discovery (and later JWKS + token exchange) over a dedicated HTTP
+	// client. go-oidc stores the client from the context at provider creation
+	// and reuses it for the JWKS keyset, so this one ClientContext covers
+	// discovery and id_token verification; the callback wires the same client
+	// into the token exchange (#264).
+	var httpClient *http.Client
+	if cfg.TLSCACert != "" {
+		c, err := oidcHTTPClientWithCA(cfg.TLSCACert)
+		if err != nil {
+			return nil, fmt.Errorf("oidc: %w", err)
+		}
+		httpClient = c
+		ctx = oidc.ClientContext(ctx, httpClient)
+	}
 	provider, err := oidc.NewProvider(ctx, cfg.Issuer)
 	if err != nil {
 		return nil, fmt.Errorf("oidc discovery: %w", err)
@@ -93,14 +117,38 @@ func NewOIDC(ctx context.Context, cfg *config.OIDCConfig, s store.Store, sm *Ses
 		Scopes:       scopes,
 	}
 	return &OIDC{
-		cfg:      *cfg,
-		provider: provider,
-		verifier: provider.Verifier(&oidc.Config{ClientID: cfg.ClientID}),
-		oauth:    oc,
-		store:    s,
-		session:  sm,
-		logger:   logger,
-		states:   make(map[string]time.Time),
+		cfg:        *cfg,
+		provider:   provider,
+		verifier:   provider.Verifier(&oidc.Config{ClientID: cfg.ClientID}),
+		oauth:      oc,
+		store:      s,
+		session:    sm,
+		logger:     logger,
+		states:     make(map[string]time.Time),
+		httpClient: httpClient,
+	}, nil
+}
+
+// oidcHTTPClientWithCA builds an HTTP client that trusts only the CA bundle at
+// caPath for TLS, used to pin the IdP connection (#264). It fails loudly when
+// the file is unreadable or holds no valid PEM certificate rather than silently
+// falling back to the system trust store.
+func oidcHTTPClientWithCA(caPath string) (*http.Client, error) {
+	pemBytes, err := os.ReadFile(caPath) // #nosec G304 -- operator-supplied trusted config path
+	if err != nil {
+		return nil, fmt.Errorf("read tls_ca_cert %q: %w", caPath, err)
+	}
+	pool := x509.NewCertPool()
+	if !pool.AppendCertsFromPEM(pemBytes) {
+		return nil, fmt.Errorf("tls_ca_cert %q: no valid PEM certificates", caPath)
+	}
+	return &http.Client{
+		Transport: &http.Transport{
+			TLSClientConfig: &tls.Config{
+				RootCAs:    pool,
+				MinVersion: tls.VersionTLS12,
+			},
+		},
 	}, nil
 }
 
@@ -182,7 +230,14 @@ func (o *OIDC) HandleCallback(rw http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	tok, err := o.oauth.Exchange(r.Context(), code)
+	// Route token exchange (and id_token verification) through the CA-pinned
+	// client when tls_ca_cert is configured, so the callback honors the same
+	// trust anchor as discovery (#264). Without pinning this is just r.Context().
+	ctx := r.Context()
+	if o.httpClient != nil {
+		ctx = oidc.ClientContext(ctx, o.httpClient)
+	}
+	tok, err := o.oauth.Exchange(ctx, code)
 	if err != nil {
 		o.logger.Error("oidc exchange", "error", err)
 		http.Error(rw, "oidc token exchange failed", http.StatusBadGateway)
@@ -193,7 +248,7 @@ func (o *OIDC) HandleCallback(rw http.ResponseWriter, r *http.Request) {
 		http.Error(rw, "oidc response missing id_token", http.StatusBadGateway)
 		return
 	}
-	idToken, err := o.verifier.Verify(r.Context(), rawID)
+	idToken, err := o.verifier.Verify(ctx, rawID)
 	if err != nil {
 		http.Error(rw, "oidc id_token verification failed: "+err.Error(), http.StatusBadGateway)
 		return

internal/web/oidc_testhelper_test.go

@@ -62,9 +62,9 @@ type mockIDP struct {
 	tokenStatus int
 }
 
-// setupOIDCServer starts a mock IdP and returns a handle for configuring it.
-// Callers must call t.Cleanup or defer Close.
-func setupOIDCServer(t *testing.T) *mockIDP {
+// newMockIDP builds a mock IdP (signing key + handlers) without starting a
+// server, so callers can choose a plaintext or TLS httptest server.
+func newMockIDP(t *testing.T) *mockIDP {
 	t.Helper()
 
 	key, err := rsa.GenerateKey(rand.Reader, 2048)
@@ -88,19 +88,42 @@ func setupOIDCServer(t *testing.T) *mockIDP {
 		return nil
 	}
 
-	idp := &mockIDP{
+	return &mockIDP{
 		signer:    signer,
 		publicKey: &key.PublicKey,
 		kid:       kid,
 	}
+}
 
+// routes wires the five discovery/JWKS/token/userinfo/auth endpoints the
+// relying-party flow needs onto a fresh mux.
+func (m *mockIDP) routes() http.Handler {
 	mux := http.NewServeMux()
-	mux.HandleFunc("/.well-known/openid-configuration", idp.handleDiscovery)
-	mux.HandleFunc("/keys", idp.handleJWKS)
-	mux.HandleFunc("/auth", idp.handleAuth)
-	mux.HandleFunc("/token", idp.handleToken)
-	mux.HandleFunc("/userinfo", idp.handleUserinfo)
-	idp.server = httptest.NewServer(mux)
+	mux.HandleFunc("/.well-known/openid-configuration", m.handleDiscovery)
+	mux.HandleFunc("/keys", m.handleJWKS)
+	mux.HandleFunc("/auth", m.handleAuth)
+	mux.HandleFunc("/token", m.handleToken)
+	mux.HandleFunc("/userinfo", m.handleUserinfo)
+	return mux
+}
+
+// setupOIDCServer starts a plaintext-HTTP mock IdP and returns a handle for
+// configuring it. Callers must call t.Cleanup or defer Close.
+func setupOIDCServer(t *testing.T) *mockIDP {
+	t.Helper()
+	idp := newMockIDP(t)
+	idp.server = httptest.NewServer(idp.routes())
+	t.Cleanup(idp.Close)
+	return idp
+}
+
+// setupOIDCServerTLS starts the same mock IdP over TLS (self-signed cert), used
+// to exercise oidc.tls_ca_cert certificate pinning (#264). The server's cert is
+// reachable via idp.server.Certificate().
+func setupOIDCServerTLS(t *testing.T) *mockIDP {
+	t.Helper()
+	idp := newMockIDP(t)
+	idp.server = httptest.NewTLSServer(idp.routes())
 	t.Cleanup(idp.Close)
 	return idp
 }

internal/web/oidc_tls_pin_test.go

@@ -0,0 +1,140 @@
+package web
+
+import (
+	"context"
+	"encoding/pem"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/forgekeep/nebula-mesh/internal/config"
+)
+
+// writeIDPCAPEM writes the TLS mock IdP's self-signed certificate to a PEM file
+// and returns its path, for use as oidc.tls_ca_cert.
+func writeIDPCAPEM(t *testing.T, idp *mockIDP) string {
+	t.Helper()
+	cert := idp.server.Certificate()
+	if cert == nil {
+		t.Fatal("TLS mock IdP has no certificate")
+	}
+	pemBytes := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw})
+	path := filepath.Join(t.TempDir(), "idp-ca.pem")
+	if err := os.WriteFile(path, pemBytes, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// TestOIDCTLSPin_DiscoverySucceedsWithPin verifies that pinning the IdP's CA
+// lets discovery succeed against an otherwise-untrusted self-signed TLS IdP.
+func TestOIDCTLSPin_DiscoverySucceedsWithPin(t *testing.T) {
+	_, s := newTestWeb(t)
+	idp := setupOIDCServerTLS(t)
+	caPath := writeIDPCAPEM(t, idp)
+
+	o := newOIDCFromMock(t, idp, s, config.OIDCConfig{
+		AllowedEmails: []string{"alice@example.com"},
+		DefaultRole:   "user",
+		TLSCACert:     caPath,
+	})
+	if o == nil {
+		t.Fatal("expected non-nil OIDC with valid CA pin")
+	}
+	if o.httpClient == nil {
+		t.Error("expected pinned httpClient to be set when tls_ca_cert is configured")
+	}
+}
+
+// TestOIDCTLSPin_DiscoveryFailsWithoutPin verifies that without pinning, the
+// self-signed TLS IdP is rejected by the system trust store at discovery.
+func TestOIDCTLSPin_DiscoveryFailsWithoutPin(t *testing.T) {
+	_, s := newTestWeb(t)
+	idp := setupOIDCServerTLS(t)
+
+	cfg := config.OIDCConfig{
+		Enabled:       true,
+		Issuer:        idp.Issuer(),
+		ClientID:      "test-client",
+		ClientSecret:  "test-secret",
+		RedirectURL:   "https://nebula-mesh.test/ui/oidc/callback",
+		AllowedEmails: []string{"alice@example.com"},
+		DefaultRole:   "user",
+		// No TLSCACert: the self-signed cert is not trusted.
+	}
+	sm := NewSessionManager(s)
+	_, err := NewOIDC(context.Background(), &cfg, s, sm, slog.New(slog.NewTextHandler(io.Discard, nil)))
+	if err == nil {
+		t.Fatal("expected discovery to fail against untrusted self-signed IdP without pinning")
+	}
+}
+
+// TestOIDCTLSPin_BadCAFile verifies a missing or malformed CA file fails NewOIDC
+// loudly instead of silently falling back to the system store.
+func TestOIDCTLSPin_BadCAFile(t *testing.T) {
+	_, s := newTestWeb(t)
+	idp := setupOIDCServerTLS(t)
+	sm := NewSessionManager(s)
+
+	base := config.OIDCConfig{
+		Enabled:       true,
+		Issuer:        idp.Issuer(),
+		ClientID:      "test-client",
+		ClientSecret:  "test-secret",
+		RedirectURL:   "https://nebula-mesh.test/ui/oidc/callback",
+		AllowedEmails: []string{"alice@example.com"},
+		DefaultRole:   "user",
+	}
+
+	t.Run("missing file", func(t *testing.T) {
+		cfg := base
+		cfg.TLSCACert = filepath.Join(t.TempDir(), "does-not-exist.pem")
+		if _, err := NewOIDC(context.Background(), &cfg, s, sm, slog.New(slog.NewTextHandler(io.Discard, nil))); err == nil {
+			t.Fatal("expected error for missing CA file")
+		}
+	})
+
+	t.Run("garbage file", func(t *testing.T) {
+		bad := filepath.Join(t.TempDir(), "garbage.pem")
+		if err := os.WriteFile(bad, []byte("not a pem certificate"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		cfg := base
+		cfg.TLSCACert = bad
+		if _, err := NewOIDC(context.Background(), &cfg, s, sm, slog.New(slog.NewTextHandler(io.Discard, nil))); err == nil {
+			t.Fatal("expected error for non-PEM CA file")
+		}
+	})
+}
+
+// TestOIDCTLSPin_FullCallback drives the full callback flow (token exchange +
+// id_token verification) against the TLS IdP with pinning, proving the pinned
+// client is used end to end, not just for discovery.
+func TestOIDCTLSPin_FullCallback(t *testing.T) {
+	_, s := newTestWeb(t)
+	idp := setupOIDCServerTLS(t)
+	caPath := writeIDPCAPEM(t, idp)
+
+	o := newOIDCFromMock(t, idp, s, config.OIDCConfig{
+		AllowedEmails: []string{"alice@example.com"},
+		DefaultRole:   "user",
+		TLSCACert:     caPath,
+	})
+
+	idp.NextIDToken(map[string]any{
+		"sub":                "alice-sub",
+		"aud":                "test-client",
+		"email":              "alice@example.com",
+		"email_verified":     true,
+		"preferred_username": "alice",
+		"name":               "Alice",
+	})
+
+	rec := driveCallback(t, o, "state-tlspin", "code-1")
+	if rec.Code != http.StatusSeeOther {
+		t.Fatalf("status = %d, want 303; body=%s", rec.Code, rec.Body.String())
+	}
+}