feat(auth): add JWT proxy authentication for reverse proxy setups

When Semaphore runs behind a reverse proxy (e.g. Pomerium), the proxy
authenticates users and passes identity via a signed JWT header. This
adds stateless JWT validation as a new auth path, avoiding redundant
OIDC configuration.

Auth flow: JWT header checked first in authenticationHandler. If present
and valid, user is loaded/created. If present but invalid, hard 401 (no
fallthrough). If absent, existing bearer/session auth proceeds unchanged.

- JWTAuthConfig in util/config_auth.go with configurable header, JWKS
  URL, audience, issuer, and claim mappings (implements ClaimsProvider)
- Header and jwks_url must be explicitly configured; no vendor-specific
  defaults. Both are validated at startup when JWT auth is enabled.
- JWKS fetching via keyfunc.NewDefault with background retry and backoff
  (5s, 10s, 30s, 1m) so the server starts even if JWKS is initially
  unreachable. JWT auth returns a clear error until JWKS becomes available.
- JWT parsing via golang-jwt/jwt/v5 with algorithm allowlist (ES256,
  ES384, ES512, RS256, RS384, RS512), required expiration, optional
  aud/iss validation
- Auto-creates external users on first JWT auth (same as OIDC pattern)
- Rejects JWT if email matches a local (non-external) user
- JWT auth failures log request path, remote address, and on validation
  errors include the token's actual iss/aud values for debugging

Author: abh

api/auth.go

@@ -213,9 +213,25 @@ func authenticationHandler(w http.ResponseWriter, r *http.Request) (ok bool, req
 
 	req = r
 
+	var jwtConfig *util.JWTAuthConfig
+	if util.Config.Auth != nil {
+		jwtConfig = util.Config.Auth.JWT
+	}
 	authHeader := strings.ToLower(r.Header.Get("authorization"))
 
-	if len(authHeader) > 0 && strings.Contains(authHeader, "bearer") {
+	if jwtConfig != nil && jwtConfig.Enabled && r.Header.Get(jwtConfig.GetHeader()) != "" {
+		// JWT proxy auth: if the header is present, commit to this path.
+		var err error
+		userID, err = authenticateByJWT(r)
+		if err != nil {
+			log.WithFields(log.Fields{
+				"path":   r.URL.Path,
+				"remote": r.RemoteAddr,
+			}).Warn("JWT auth failed: ", err)
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+	} else if len(authHeader) > 0 && strings.Contains(authHeader, "bearer") {
 		token, err := helpers.Store(r).GetAPIToken(strings.Replace(authHeader, "bearer ", "", 1))
 
 		if err != nil {

api/jwt_auth.go

@@ -0,0 +1,183 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/MicahParks/keyfunc/v3"
+	"github.com/golang-jwt/jwt/v5"
+	log "github.com/sirupsen/logrus"
+
+	"github.com/semaphoreui/semaphore/api/helpers"
+	"github.com/semaphoreui/semaphore/db"
+	"github.com/semaphoreui/semaphore/util"
+)
+
+var (
+	globalKeyfunc   keyfunc.Keyfunc
+	globalKeyfuncMu sync.RWMutex
+	globalJWTParser *jwt.Parser
+)
+
+func initJWKSCache(jwksURL string) {
+	if !strings.HasPrefix(jwksURL, "https://") {
+		log.Warn("JWT JWKS URL is not HTTPS: ", jwksURL)
+	}
+
+	globalJWTParser = newJWTParser(util.Config.Auth.JWT)
+
+	kf, err := fetchJWKS(jwksURL)
+	if err != nil {
+		log.Errorf("JWKS initial fetch from %s failed: %v — JWT auth unavailable until JWKS is fetched", jwksURL, err)
+		go retryJWKSFetch(jwksURL)
+		return
+	}
+
+	globalKeyfuncMu.Lock()
+	globalKeyfunc = kf
+	globalKeyfuncMu.Unlock()
+	log.Info("JWKS loaded from ", jwksURL)
+}
+
+// fetchJWKS fetches the JWKS from the given URL. The initial HTTP fetch runs
+// synchronously; if it succeeds, background refresh continues automatically.
+func fetchJWKS(jwksURL string) (keyfunc.Keyfunc, error) {
+	type result struct {
+		kf  keyfunc.Keyfunc
+		err error
+	}
+	ch := make(chan result, 1) // buffered so the goroutine won't leak on timeout
+	go func() {
+		kf, err := keyfunc.NewDefault([]string{jwksURL})
+		ch <- result{kf, err}
+	}()
+	select {
+	case r := <-ch:
+		return r.kf, r.err
+	case <-time.After(15 * time.Second):
+		return nil, fmt.Errorf("timeout fetching JWKS from %s", jwksURL)
+	}
+}
+
+// retryJWKSFetch retries JWKS fetch indefinitely with backoff. It never gives
+// up because the JWKS endpoint may become reachable after the server starts
+// (e.g. DNS not yet propagated inside a pod).
+func retryJWKSFetch(jwksURL string) {
+	delays := []time.Duration{5 * time.Second, 10 * time.Second, 30 * time.Second, time.Minute}
+
+	for attempt := 0; ; attempt++ {
+		delay := delays[len(delays)-1]
+		if attempt < len(delays) {
+			delay = delays[attempt]
+		}
+		time.Sleep(delay)
+
+		log.Infof("JWKS retry attempt %d for %s", attempt+1, jwksURL)
+		kf, err := fetchJWKS(jwksURL)
+		if err != nil {
+			log.Errorf("JWKS retry %d failed: %v", attempt+1, err)
+			continue
+		}
+
+		globalKeyfuncMu.Lock()
+		globalKeyfunc = kf
+		globalKeyfuncMu.Unlock()
+		log.Info("JWKS loaded from ", jwksURL)
+		return
+	}
+}
+
+func newJWTParser(config *util.JWTAuthConfig) *jwt.Parser {
+	opts := []jwt.ParserOption{
+		jwt.WithValidMethods([]string{"ES256", "ES384", "ES512", "RS256", "RS384", "RS512"}),
+		jwt.WithExpirationRequired(),
+	}
+
+	if config.Audience != "" {
+		opts = append(opts, jwt.WithAudience(config.Audience))
+	}
+	if config.Issuer != "" {
+		opts = append(opts, jwt.WithIssuer(config.Issuer))
+	}
+
+	return jwt.NewParser(opts...)
+}
+
+func validateProxyJWT(tokenString string) (map[string]any, error) {
+	globalKeyfuncMu.RLock()
+	kf := globalKeyfunc
+	globalKeyfuncMu.RUnlock()
+
+	if kf == nil {
+		return nil, fmt.Errorf("JWKS not yet available — JWT auth is temporarily unavailable")
+	}
+
+	token, err := globalJWTParser.Parse(tokenString, kf.Keyfunc)
+	if err != nil {
+		// Parse without verification solely to extract iss/aud for operator-facing
+		// log messages. The token has already been rejected above.
+		unverified, _, parseErr := jwt.NewParser(jwt.WithoutClaimsValidation()).ParseUnverified(tokenString, jwt.MapClaims{})
+		if parseErr == nil {
+			if claims, ok := unverified.Claims.(jwt.MapClaims); ok {
+				return nil, fmt.Errorf("JWT validation failed (iss=%v aud=%v): %w",
+					claims["iss"], claims["aud"], err)
+			}
+		}
+		return nil, fmt.Errorf("JWT validation failed: %w", err)
+	}
+
+	claims, ok := token.Claims.(jwt.MapClaims)
+	if !ok {
+		return nil, fmt.Errorf("unexpected claims type")
+	}
+
+	return claims, nil
+}
+
+func authenticateByJWT(r *http.Request) (int, error) {
+	config := util.Config.Auth.JWT
+
+	tokenString := r.Header.Get(config.GetHeader())
+	if tokenString == "" {
+		return 0, fmt.Errorf("no JWT in header %s", config.GetHeader())
+	}
+
+	claims, err := validateProxyJWT(tokenString)
+	if err != nil {
+		return 0, err
+	}
+
+	prepareClaims(claims)
+	parsed, err := parseClaims(claims, config)
+	if err != nil {
+		return 0, fmt.Errorf("extract claims: %w", err)
+	}
+
+	store := helpers.Store(r)
+
+	user, err := store.GetUserByLoginOrEmail("", parsed.email)
+
+	if errors.Is(err, db.ErrNotFound) {
+		user = db.User{
+			Username: parsed.username,
+			Name:     parsed.name,
+			Email:    parsed.email,
+			External: true,
+		}
+		user, err = store.CreateUserWithoutPassword(user)
+	}
+
+	if err != nil {
+		return 0, fmt.Errorf("JWT user lookup/creation: %w", err)
+	}
+
+	if !user.External {
+		return 0, fmt.Errorf("JWT user %q conflicts with local user", user.Email)
+	}
+
+	return user.ID, nil
+}