Merge pull request #1467 from helixml/design/saas-keycloak-extraction

feat(auth): add standalone Keycloak authentication support

Author: chocobar

.gitleaksignore

@@ -28,3 +28,6 @@ scripts/init-moonlight-web.sh:curl-auth-user:64
 
 # Wolf development certificate (local development only)
 wolf/key.pem:private-key:1
+
+# Keycloak docker-compose - PostgreSQL connection string (not a secret, just port/dbname)
+docker-compose.keycloak.yaml:generic-api-key:25

Dockerfile.keycloak

@@ -0,0 +1,12 @@
+FROM quay.io/keycloak/keycloak:23.0
+
+# Copy our custom theme into the Keycloak themes directory
+COPY themes/helix /opt/keycloak/themes/helix
+
+# Set proper ownership and permissions
+USER root
+RUN chown -R keycloak:keycloak /opt/keycloak/themes/helix
+USER keycloak
+
+# Build the theme cache (optional but recommended for production)
+RUN /opt/keycloak/bin/kc.sh build

api/pkg/auth/auth.go

@@ -3,7 +3,7 @@ package auth
 import (
 	"context"
 
-	"github.com/coreos/go-oidc"
+	"github.com/coreos/go-oidc/v3/oidc"
 	"golang.org/x/oauth2"
 
 	"github.com/helixml/helix/api/pkg/types"
@@ -25,6 +25,11 @@ type Authenticator interface {
 
 	RequestPasswordReset(ctx context.Context, email string) error
 	PasswordResetComplete(ctx context.Context, token, newPassword string) error
+
+	// GetOIDCClient returns the OIDC client for this authenticator.
+	// For KeycloakAuthenticator, this returns the internal OIDC client.
+	// For HelixAuthenticator, this returns nil (no OIDC support).
+	GetOIDCClient() OIDC
 }
 
 type OIDC interface {

api/pkg/auth/auth_test.go

@@ -0,0 +1,69 @@
+package auth
+
+import (
+	"testing"
+	"time"
+
+	"github.com/helixml/helix/api/pkg/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+)
+
+func TestHelixAuthenticator_GetOIDCClient(t *testing.T) {
+	// Create a minimal config for the authenticator
+	cfg := &config.ServerConfig{
+		Auth: config.Auth{
+			Regular: config.Regular{
+				TokenValidity: 24 * time.Hour,
+			},
+		},
+	}
+
+	authenticator, err := NewHelixAuthenticator(cfg, nil, "test-secret", nil)
+	require.NoError(t, err)
+
+	// HelixAuthenticator should return nil for GetOIDCClient
+	// since it doesn't use OIDC
+	oidcClient := authenticator.GetOIDCClient()
+	assert.Nil(t, oidcClient, "HelixAuthenticator.GetOIDCClient() should return nil")
+}
+
+func TestAuthenticator_Interface_GetOIDCClient(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	// Create a mock authenticator
+	mockAuth := NewMockAuthenticator(ctrl)
+
+	// Create a mock OIDC client
+	mockOIDC := NewMockOIDC(ctrl)
+
+	// Set up expectation - GetOIDCClient returns the mock OIDC client
+	mockAuth.EXPECT().GetOIDCClient().Return(mockOIDC)
+
+	// Call the method
+	var auth Authenticator = mockAuth
+	result := auth.GetOIDCClient()
+
+	// Verify result
+	assert.Equal(t, mockOIDC, result, "GetOIDCClient should return the expected OIDC client")
+}
+
+func TestAuthenticator_Interface_GetOIDCClient_Nil(t *testing.T) {
+	ctrl := gomock.NewController(t)
+	defer ctrl.Finish()
+
+	// Create a mock authenticator
+	mockAuth := NewMockAuthenticator(ctrl)
+
+	// Set up expectation - GetOIDCClient returns nil (like HelixAuthenticator)
+	mockAuth.EXPECT().GetOIDCClient().Return(nil)
+
+	// Call the method
+	var auth Authenticator = mockAuth
+	result := auth.GetOIDCClient()
+
+	// Verify result
+	assert.Nil(t, result, "GetOIDCClient should return nil when no OIDC client is available")
+}

api/pkg/auth/helix_authenticator.go

@@ -295,3 +295,9 @@ func (h *HelixAuthenticator) GenerateUserToken(_ context.Context, user *types.Us
 
 	return tokenString, nil
 }
+
+// GetOIDCClient returns nil for HelixAuthenticator as it doesn't use OIDC.
+// This satisfies the Authenticator interface.
+func (h *HelixAuthenticator) GetOIDCClient() OIDC {
+	return nil
+}

api/pkg/auth/keycloak.go

@@ -59,9 +59,11 @@ func NewKeycloakAuthenticator(cfg *config.ServerConfig, store store.Store) (*Key
 		return nil, err
 	}
 
-	keycloakURL, err := url.Parse(cfg.Auth.Keycloak.KeycloakFrontEndURL)
+	// Use internal KeycloakURL for OIDC discovery (server-to-server communication)
+	// KeycloakFrontEndURL is used by Keycloak for browser-facing URLs (set via KC_HOSTNAME_URL)
+	keycloakURL, err := url.Parse(cfg.Auth.Keycloak.KeycloakURL)
 	if err != nil {
-		return nil, fmt.Errorf("failed to parse keycloak front end url: %w", err)
+		return nil, fmt.Errorf("failed to parse keycloak url: %w", err)
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	defer cancel()
@@ -71,15 +73,35 @@ func NewKeycloakAuthenticator(cfg *config.ServerConfig, store store.Store) (*Key
 	// Strip any trailing slashes from the path
 	keycloakURL.Path = strings.TrimRight(keycloakURL.Path, "/")
 	keycloakURL.Path = fmt.Sprintf("%s/realms/%s", keycloakURL.Path, cfg.Auth.Keycloak.Realm)
+
+	// Build the expected issuer URL from the frontend URL
+	// This allows the API to connect to Keycloak via internal URL (keycloak:8080)
+	// while Keycloak is configured with external URL (localhost:8180) for browser access
+	var expectedIssuer string
+	if cfg.Auth.Keycloak.KeycloakFrontEndURL != "" && cfg.Auth.Keycloak.KeycloakFrontEndURL != cfg.Auth.Keycloak.KeycloakURL {
+		frontendURL, err := url.Parse(cfg.Auth.Keycloak.KeycloakFrontEndURL)
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse keycloak frontend url: %w", err)
+		}
+		frontendURL.Path = strings.TrimRight(frontendURL.Path, "/")
+		frontendURL.Path = fmt.Sprintf("%s/realms/%s", frontendURL.Path, cfg.Auth.Keycloak.Realm)
+		expectedIssuer = frontendURL.String()
+		log.Info().
+			Str("internal_url", keycloakURL.String()).
+			Str("expected_issuer", expectedIssuer).
+			Msg("Using separate issuer URL for browser-facing Keycloak")
+	}
+
 	client, err := NewOIDCClient(ctx, OIDCConfig{
-		ProviderURL:  keycloakURL.String(),
-		ClientID:     cfg.Auth.Keycloak.APIClientID,
-		ClientSecret: cfg.Auth.Keycloak.ClientSecret,
-		RedirectURL:  helixRedirectURL,
-		AdminUserIDs: cfg.WebServer.AdminUserIDs,
-		Audience:     "account",
-		Scopes:       []string{"openid", "profile", "email"},
-		Store:        store,
+		ProviderURL:    keycloakURL.String(),
+		ClientID:       cfg.Auth.Keycloak.APIClientID,
+		ClientSecret:   cfg.Auth.Keycloak.ClientSecret,
+		RedirectURL:    helixRedirectURL,
+		AdminUserIDs:   cfg.WebServer.AdminUserIDs,
+		Audience:       "account",
+		Scopes:         []string{"openid", "profile", "email"},
+		Store:          store,
+		ExpectedIssuer: expectedIssuer,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("failed to create keycloak client: %w", err)
@@ -376,14 +398,11 @@ func setRealmConfigurations(gck *gocloak.GoCloak, token string, cfg *config.Keyc
 		}
 	}
 
-	// Initialize attributes if not set
-	if realm.Attributes == nil {
-		realm.Attributes = &map[string]string{}
-	}
-
-	attributes := *realm.Attributes
-	attributes["frontendUrl"] = cfg.KeycloakFrontEndURL
-	*realm.Attributes = attributes
+	// NOTE: We intentionally do NOT set the realm's frontendUrl attribute here.
+	// The realm's frontendUrl would override the issuer in the OIDC discovery document,
+	// causing an issuer mismatch when the API verifies tokens.
+	// Instead, we handle browser redirects by overriding the authorization URL
+	// in the OIDC client (see AuthURLOverride in NewKeycloakAuthenticator).
 
 	// Set login theme to "helix" for both new and existing deployments
 	if realm.LoginTheme == nil || *realm.LoginTheme != "helix" {
@@ -400,7 +419,6 @@ func setRealmConfigurations(gck *gocloak.GoCloak, token string, cfg *config.Keyc
 
 	log.Info().
 		Str("realm", cfg.Realm).
-		Str("frontend_url", cfg.KeycloakFrontEndURL).
 		Str("login_theme", gocloak.PString(realm.LoginTheme)).
 		Msg("Configured realm")
 
@@ -597,4 +615,11 @@ func (k *KeycloakAuthenticator) PasswordResetComplete(ctx context.Context, token
 	return fmt.Errorf("passwordReset: not implemented")
 }
 
+// GetOIDCClient returns the OIDC client used by KeycloakAuthenticator.
+// This is needed because the server needs access to the OIDC client for
+// authentication flows (login redirect, callback, logout, token refresh).
+func (k *KeycloakAuthenticator) GetOIDCClient() OIDC {
+	return k.oidcClient
+}
+
 func addr[T any](t T) *T { return &t }

api/pkg/auth/mock.go

@@ -6,7 +6,7 @@ import (
 	"fmt"
 	"time"
 
-	"github.com/coreos/go-oidc"
+	"github.com/coreos/go-oidc/v3/oidc"
 	"github.com/helixml/helix/api/pkg/store"
 	"github.com/helixml/helix/api/pkg/types"
 	"github.com/rs/zerolog/log"
@@ -37,6 +37,12 @@ type OIDCConfig struct {
 	Audience     string
 	Scopes       []string
 	Store        store.Store
+	// ExpectedIssuer allows the OIDC provider to return a different issuer than the ProviderURL.
+	// This is useful when the API connects to Keycloak via an internal URL (e.g., keycloak:8080)
+	// but Keycloak is configured with an external URL (e.g., localhost:8180) for browser access.
+	// If set, the OIDC client will accept tokens with this issuer even though discovery
+	// was done via ProviderURL.
+	ExpectedIssuer string
 }
 
 func NewOIDCClient(ctx context.Context, cfg OIDCConfig) (*OIDCClient, error) {
@@ -91,7 +97,21 @@ func NewOIDCClient(ctx context.Context, cfg OIDCConfig) (*OIDCClient, error) {
 func (c *OIDCClient) getProvider() (*oidc.Provider, error) {
 	if c.provider == nil {
 		log.Trace().Str("provider_url", c.cfg.ProviderURL).Msg("Getting provider")
-		provider, err := oidc.NewProvider(context.Background(), c.cfg.ProviderURL)
+
+		// If ExpectedIssuer is set, use InsecureIssuerURLContext to allow the provider
+		// to return a different issuer than the discovery URL. This is needed when
+		// the API connects to Keycloak via an internal URL but Keycloak is configured
+		// with an external URL for browser access.
+		ctx := context.Background()
+		if c.cfg.ExpectedIssuer != "" {
+			log.Info().
+				Str("discovery_url", c.cfg.ProviderURL).
+				Str("expected_issuer", c.cfg.ExpectedIssuer).
+				Msg("Using InsecureIssuerURLContext to allow different issuer")
+			ctx = oidc.InsecureIssuerURLContext(ctx, c.cfg.ExpectedIssuer)
+		}
+
+		provider, err := oidc.NewProvider(ctx, c.cfg.ProviderURL)
 		if err != nil {
 			// Wrap error to indicate provider not ready (used to return 503 instead of 401)
 			return nil, fmt.Errorf("%w: %v", ErrProviderNotReady, err)
@@ -108,13 +128,14 @@ func (c *OIDCClient) getOauth2Config() (*oauth2.Config, error) {
 			log.Error().Err(err).Msg("Failed to get provider")
 			return nil, err
 		}
-		log.Trace().Str("client_id", c.cfg.ClientID).Str("redirect_url", c.cfg.RedirectURL).Interface("endpoints", provider.Endpoint()).Msg("Getting oauth2 config")
+		endpoint := provider.Endpoint()
+		log.Trace().Str("client_id", c.cfg.ClientID).Str("redirect_url", c.cfg.RedirectURL).Interface("endpoints", endpoint).Msg("Getting oauth2 config")
 		c.oauth2Config = &oauth2.Config{
 			ClientID:     c.cfg.ClientID,
 			ClientSecret: c.cfg.ClientSecret,
 			RedirectURL:  c.cfg.RedirectURL,
 			Scopes:       c.cfg.Scopes,
-			Endpoint:     provider.Endpoint(),
+			Endpoint:     endpoint,
 		}
 	}
 	return c.oauth2Config, nil
@@ -236,14 +257,43 @@ func (c *OIDCClient) ValidateUserToken(ctx context.Context, accessToken string)
 
 	userInfo, err := c.GetUserInfo(ctx, accessToken)
 	if err != nil {
-		return nil, fmt.Errorf("invalid access token (could not get user): %w", err)
+		return nil, fmt.Errorf("invalid access token (could not get user info): %w", err)
 	}
 
+	// Try to get the user from the database by their OIDC subject ID
 	user, err := c.store.GetUser(ctx, &store.GetUserQuery{
-		Email: userInfo.Email,
+		ID: userInfo.Subject,
 	})
-	if err != nil {
-		return nil, fmt.Errorf("invalid access token (could not get user): %w", err)
+	if err != nil && !errors.Is(err, store.ErrNotFound) {
+		return nil, fmt.Errorf("invalid access token (database error): %w", err)
+	}
+
+	// Extract full name from userinfo
+	fullName := userInfo.Name
+	if fullName == "" && userInfo.GivenName != "" && userInfo.FamilyName != "" {
+		fullName = userInfo.GivenName + " " + userInfo.FamilyName
+	}
+	if fullName == "" {
+		fullName = userInfo.Email
+	}
+
+	// If user doesn't exist, create them (first login after OIDC registration)
+	if user == nil {
+		log.Info().
+			Str("subject", userInfo.Subject).
+			Str("email", userInfo.Email).
+			Msg("Creating new user from OIDC token")
+
+		user, err = c.store.CreateUser(ctx, &types.User{
+			ID:        userInfo.Subject,
+			Username:  userInfo.Subject,
+			Email:     userInfo.Email,
+			FullName:  fullName,
+			CreatedAt: time.Now(),
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to create user: %w", err)
+		}
 	}
 
 	// Determine admin status:
@@ -255,7 +305,7 @@ func (c *OIDCClient) ValidateUserToken(ctx context.Context, accessToken string)
 		ID:          userInfo.Subject,
 		Username:    userInfo.Subject,
 		Email:       userInfo.Email,
-		FullName:    userInfo.Name,
+		FullName:    fullName,
 		Token:       accessToken,
 		TokenType:   types.TokenTypeOIDC,
 		Type:        types.OwnerTypeUser,

api/pkg/auth/oidc.go

@@ -1671,7 +1671,6 @@
     "oauth2DeviceCodeLifespan" : "600",
     "parRequestUriLifespan" : "60",
     "clientSessionMaxLifespan" : "0",
-    "frontendUrl" : "http://localhost:8080/auth",
     "acr.loa.map" : "{}"
   },
   "keycloakVersion" : "23.0.7",

api/pkg/auth/realm.json

@@ -170,7 +170,7 @@ type Regular struct {
 type Keycloak struct {
 	KeycloakEnabled     bool   `envconfig:"KEYCLOAK_ENABLED" default:"false"`
 	KeycloakURL         string `envconfig:"KEYCLOAK_URL" default:"http://keycloak:8080/auth"`
-	KeycloakFrontEndURL string `envconfig:"KEYCLOAK_FRONTEND_URL" default:"http://localhost:8080/auth"`
+	KeycloakFrontEndURL string `envconfig:"KEYCLOAK_FRONTEND_URL" default:"http://localhost:8180/auth"`
 	ServerURL           string `envconfig:"SERVER_URL" description:"The URL the api server is listening on."`
 	APIClientID         string `envconfig:"KEYCLOAK_CLIENT_ID" default:"api"`
 	ClientSecret        string `envconfig:"KEYCLOAK_CLIENT_SECRET"` // If not set, will be looked up using admin API