feat: OIDC connector config and provider discovery API (#1548)

* feat: add OIDC connector configuration and provider discovery API

Add external OIDC connector configuration model (Task 18) supporting
Google, GitHub, Microsoft, and generic OIDC providers. Configuration
can be loaded from DEX_CONNECTORS JSON or individual environment
variables (DEX_CONNECTOR_{TYPE}_{FIELD}).

Add GET /api/auth/providers endpoint (Task 19) to the API gateway
that returns configured authentication providers for frontend login
button rendering. The endpoint is public (no auth required) and
includes Cache-Control headers.

* fix: log error when AUTH_PROVIDERS JSON is malformed

Previously, invalid JSON in AUTH_PROVIDERS was silently swallowed,
causing all OIDC login buttons to disappear with no log trace.
Now logs an error before falling back to the default provider.

* fix: remove undocumented AUTH_DEFAULT_PROVIDER from doc comment

The environment variable was documented but never read by the loader.

* fix: filter OIDC providers without authUrl when DEX_ISSUER is unset

OIDC providers configured without an explicit authUrl and no DEX_ISSUER
to derive one from are now logged and filtered out rather than published
with an empty auth URL in the discovery response.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

services/api-gateway/providers.go

@@ -0,0 +1,118 @@
+package gateway
+
+import (
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"os"
+	"strings"
+)
+
+// AuthProvider represents a configured authentication provider returned by the
+// provider discovery endpoint. The frontend uses this to render login buttons.
+type AuthProvider struct {
+	// ID is the unique identifier for this provider (e.g., "meridian", "google").
+	ID string `json:"id"`
+	// Type is the provider type: "password" for local login, "oidc" for external.
+	Type string `json:"type"`
+	// DisplayName is the human-readable label for the login button.
+	DisplayName string `json:"displayName"`
+	// AuthURL is the Dex authorization URL for OIDC providers.
+	// Empty for password-type providers.
+	AuthURL string `json:"authUrl,omitempty"`
+}
+
+// ProvidersResponse is the JSON response for GET /api/auth/providers.
+type ProvidersResponse struct {
+	Providers []AuthProvider `json:"providers"`
+}
+
+// ProvidersConfig holds the configuration for the provider discovery endpoint.
+type ProvidersConfig struct {
+	// Enabled controls whether the /api/auth/providers endpoint is registered.
+	Enabled bool
+	// Providers is the list of configured authentication providers.
+	Providers []AuthProvider
+}
+
+// LoadProvidersConfig loads provider configuration from environment variables.
+//
+// Environment variables:
+//   - AUTH_PROVIDERS_ENABLED: Enable the /api/auth/providers endpoint (default: false)
+//   - AUTH_PROVIDERS: JSON array of provider objects
+//   - DEX_ISSUER: Used to construct authUrl for OIDC providers when not explicitly set
+//
+// When AUTH_PROVIDERS is not set but AUTH_PROVIDERS_ENABLED is true, a default
+// "meridian" password provider is included.
+func LoadProvidersConfig() ProvidersConfig {
+	config := ProvidersConfig{
+		Enabled: getEnvBool("AUTH_PROVIDERS_ENABLED", false),
+	}
+
+	if !config.Enabled {
+		return config
+	}
+
+	dexIssuer := strings.TrimRight(os.Getenv("DEX_ISSUER"), "/")
+
+	if raw := os.Getenv("AUTH_PROVIDERS"); raw != "" {
+		var providers []AuthProvider
+		if err := json.Unmarshal([]byte(raw), &providers); err != nil {
+			slog.Error("failed to parse AUTH_PROVIDERS, falling back to default provider",
+				"error", err)
+		} else {
+			// Populate authUrl for OIDC providers and filter out those
+			// that would have no usable auth URL.
+			filtered := make([]AuthProvider, 0, len(providers))
+			for i := range providers {
+				if providers[i].Type == "oidc" && providers[i].AuthURL == "" {
+					if dexIssuer == "" {
+						slog.Error("skipping OIDC provider without authUrl and DEX_ISSUER",
+							"provider_id", providers[i].ID)
+						continue
+					}
+					providers[i].AuthURL = dexIssuer + "/auth/" + providers[i].ID
+				}
+				filtered = append(filtered, providers[i])
+			}
+			config.Providers = filtered
+		}
+	}
+
+	// Default to just the local password provider if nothing configured
+	if len(config.Providers) == 0 {
+		config.Providers = []AuthProvider{
+			{ID: "meridian", Type: "password", DisplayName: "Email & Password"},
+		}
+	}
+
+	return config
+}
+
+// getEnvBool parses a boolean from an environment variable.
+func getEnvBool(key string, defaultVal bool) bool {
+	v := os.Getenv(key)
+	switch strings.ToLower(v) {
+	case "true", "1", "yes":
+		return true
+	case "false", "0", "no":
+		return false
+	default:
+		return defaultVal
+	}
+}
+
+// handleProviders returns the configured authentication providers as JSON.
+// This endpoint is public (no auth required) because the frontend needs
+// to know which login methods are available before the user authenticates.
+func (s *Server) handleProviders(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.Header().Set("Cache-Control", "public, max-age=300")
+
+	resp := ProvidersResponse{Providers: s.providersConfig.Providers}
+	if resp.Providers == nil {
+		resp.Providers = []AuthProvider{}
+	}
+
+	_ = json.NewEncoder(w).Encode(resp)
+}

services/api-gateway/providers_test.go

@@ -0,0 +1,197 @@
+package gateway
+
+import (
+	"encoding/json"
+	"io"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestProvidersEndpoint_ReturnsProviders(t *testing.T) {
+	providers := []AuthProvider{
+		{ID: "meridian", Type: "password", DisplayName: "Email & Password"},
+		{ID: "google", Type: "oidc", DisplayName: "Google", AuthURL: "https://dex.example.com/dex/auth/google"},
+	}
+
+	server := newTestServerWithProviders(t, ProvidersConfig{
+		Enabled:   true,
+		Providers: providers,
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/providers", nil)
+	w := httptest.NewRecorder()
+	server.mux.ServeHTTP(w, req)
+
+	resp := w.Result()
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Equal(t, "application/json; charset=utf-8", resp.Header.Get("Content-Type"))
+	assert.Equal(t, "public, max-age=300", resp.Header.Get("Cache-Control"))
+
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	var result ProvidersResponse
+	require.NoError(t, json.Unmarshal(body, &result))
+	require.Len(t, result.Providers, 2)
+	assert.Equal(t, "meridian", result.Providers[0].ID)
+	assert.Equal(t, "password", result.Providers[0].Type)
+	assert.Equal(t, "google", result.Providers[1].ID)
+	assert.Equal(t, "oidc", result.Providers[1].Type)
+	assert.Equal(t, "https://dex.example.com/dex/auth/google", result.Providers[1].AuthURL)
+}
+
+func TestProvidersEndpoint_EmptyProviders_ReturnsEmptyArray(t *testing.T) {
+	server := newTestServerWithProviders(t, ProvidersConfig{
+		Enabled:   true,
+		Providers: nil,
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/providers", nil)
+	w := httptest.NewRecorder()
+	server.mux.ServeHTTP(w, req)
+
+	resp := w.Result()
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	var result ProvidersResponse
+	require.NoError(t, json.Unmarshal(body, &result))
+	assert.NotNil(t, result.Providers)
+	assert.Empty(t, result.Providers)
+}
+
+func TestProvidersEndpoint_PostReturns405(t *testing.T) {
+	server := newTestServerWithProviders(t, ProvidersConfig{
+		Enabled:   true,
+		Providers: []AuthProvider{{ID: "meridian", Type: "password", DisplayName: "Email & Password"}},
+	})
+
+	req := httptest.NewRequest(http.MethodPost, "/api/auth/providers", nil)
+	w := httptest.NewRecorder()
+	server.mux.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusMethodNotAllowed, w.Result().StatusCode)
+}
+
+func TestProvidersEndpoint_DisabledReturns404(t *testing.T) {
+	server := newTestServerWithProviders(t, ProvidersConfig{
+		Enabled: false,
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/providers", nil)
+	w := httptest.NewRecorder()
+	server.mux.ServeHTTP(w, req)
+
+	// When disabled, the route is not registered. The "/" catch-all will handle it.
+	// With no backend configured, it returns 503.
+	resp := w.Result()
+	defer resp.Body.Close()
+	assert.NotEqual(t, http.StatusOK, resp.StatusCode)
+}
+
+func TestProvidersEndpoint_OmitsEmptyAuthURL(t *testing.T) {
+	server := newTestServerWithProviders(t, ProvidersConfig{
+		Enabled: true,
+		Providers: []AuthProvider{
+			{ID: "meridian", Type: "password", DisplayName: "Email & Password"},
+		},
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/auth/providers", nil)
+	w := httptest.NewRecorder()
+	server.mux.ServeHTTP(w, req)
+
+	body, err := io.ReadAll(w.Result().Body)
+	require.NoError(t, err)
+
+	// authUrl should be omitted (omitempty) for password type
+	assert.NotContains(t, string(body), "authUrl")
+}
+
+func TestLoadProvidersConfig_Disabled(t *testing.T) {
+	cfg := LoadProvidersConfig()
+	assert.False(t, cfg.Enabled)
+	assert.Nil(t, cfg.Providers)
+}
+
+func TestLoadProvidersConfig_EnabledWithDefaults(t *testing.T) {
+	t.Setenv("AUTH_PROVIDERS_ENABLED", "true")
+
+	cfg := LoadProvidersConfig()
+	assert.True(t, cfg.Enabled)
+	require.Len(t, cfg.Providers, 1)
+	assert.Equal(t, "meridian", cfg.Providers[0].ID)
+	assert.Equal(t, "password", cfg.Providers[0].Type)
+}
+
+func TestLoadProvidersConfig_JSONProviders(t *testing.T) {
+	t.Setenv("AUTH_PROVIDERS_ENABLED", "true")
+	t.Setenv("AUTH_PROVIDERS", `[
+		{"id":"meridian","type":"password","displayName":"Email & Password"},
+		{"id":"google","type":"oidc","displayName":"Google"}
+	]`)
+	t.Setenv("DEX_ISSUER", "https://dex.example.com/dex")
+
+	cfg := LoadProvidersConfig()
+	assert.True(t, cfg.Enabled)
+	require.Len(t, cfg.Providers, 2)
+	assert.Equal(t, "meridian", cfg.Providers[0].ID)
+	assert.Empty(t, cfg.Providers[0].AuthURL) // password type gets no authUrl
+	assert.Equal(t, "google", cfg.Providers[1].ID)
+	assert.Equal(t, "https://dex.example.com/dex/auth/google", cfg.Providers[1].AuthURL)
+}
+
+func TestLoadProvidersConfig_ExplicitAuthURL(t *testing.T) {
+	t.Setenv("AUTH_PROVIDERS_ENABLED", "true")
+	t.Setenv("AUTH_PROVIDERS", `[{"id":"custom","type":"oidc","displayName":"Custom","authUrl":"https://custom.example.com/auth"}]`)
+	t.Setenv("DEX_ISSUER", "https://dex.example.com/dex")
+
+	cfg := LoadProvidersConfig()
+	require.Len(t, cfg.Providers, 1)
+	// Explicit authUrl should NOT be overwritten
+	assert.Equal(t, "https://custom.example.com/auth", cfg.Providers[0].AuthURL)
+}
+
+func TestLoadProvidersConfig_OIDCWithoutIssuer_Filtered(t *testing.T) {
+	t.Setenv("AUTH_PROVIDERS_ENABLED", "true")
+	t.Setenv("AUTH_PROVIDERS", `[
+		{"id":"meridian","type":"password","displayName":"Email & Password"},
+		{"id":"google","type":"oidc","displayName":"Google"}
+	]`)
+	// No DEX_ISSUER set
+
+	cfg := LoadProvidersConfig()
+	// Google OIDC provider should be filtered out (no authUrl, no DEX_ISSUER)
+	require.Len(t, cfg.Providers, 1)
+	assert.Equal(t, "meridian", cfg.Providers[0].ID)
+}
+
+func TestLoadProvidersConfig_InvalidJSON_FallsBackToDefault(t *testing.T) {
+	t.Setenv("AUTH_PROVIDERS_ENABLED", "true")
+	t.Setenv("AUTH_PROVIDERS", `{invalid`)
+
+	cfg := LoadProvidersConfig()
+	require.Len(t, cfg.Providers, 1)
+	assert.Equal(t, "meridian", cfg.Providers[0].ID)
+}
+
+func newTestServerWithProviders(t *testing.T, providersCfg ProvidersConfig) *Server {
+	t.Helper()
+	config := &Config{
+		Port:         8080,
+		BaseDomain:   "test.example.com",
+		DatabaseURL:  "postgres://test",
+		LocalDevMode: true,
+	}
+	logger := slog.New(slog.NewJSONHandler(io.Discard, nil))
+	return NewServer(config, logger, nil, WithProvidersConfig(providersCfg))
+}

services/api-gateway/server.go

@@ -34,6 +34,7 @@ type Server struct {
 	eventStreamHandler    *eventstream.Handler
 	rawEventStreamHandler http.Handler // used by tests and WithEventStreamHandlerHTTP
 	versionInfo           *VersionInfo
+	providersConfig       ProvidersConfig
 }
 
 // ServerOption is a functional option for configuring the server.
@@ -86,6 +87,14 @@ func WithVersionInfo(info *VersionInfo) ServerOption {
 	}
 }
 
+// WithProvidersConfig sets the authentication provider discovery configuration.
+// When enabled, the GET /api/auth/providers endpoint is registered.
+func WithProvidersConfig(cfg ProvidersConfig) ServerOption {
+	return func(s *Server) {
+		s.providersConfig = cfg
+	}
+}
+
 // NewServer creates a new gateway HTTP server with the given configuration.
 // The tenantResolver parameter is optional - if nil, all routes bypass tenant resolution.
 // Additional options can configure authentication middleware.
@@ -145,6 +154,11 @@ func (s *Server) registerRoutes() {
 	// Build version endpoint - NO middleware (public, like health)
 	s.mux.HandleFunc("/version", s.getOnly(s.handleVersion))
 
+	// Provider discovery endpoint - NO middleware (public, needed before login)
+	if s.providersConfig.Enabled {
+		s.mux.HandleFunc("/api/auth/providers", s.getOnly(s.handleProviders))
+	}
+
 	// API routes - with auth and tenant middleware chain.
 	// Prefer the Vanguard transcoder when configured; fall back to the legacy
 	// prefix-based reverse proxy when Backends are provided; otherwise use a