Auth: Rotate portal JWT signing keys on a schedule and on demand

Author: lastzero

internal/commands/auth_jwt_keys.go

@@ -9,7 +9,9 @@ import (
 	"github.com/urfave/cli/v2"
 
 	"github.com/photoprism/photoprism/internal/config"
+	"github.com/photoprism/photoprism/internal/event"
 	"github.com/photoprism/photoprism/internal/photoprism/get"
+	"github.com/photoprism/photoprism/pkg/log/status"
 )
 
 // AuthJWTKeysCommand groups JWT key management helpers.
@@ -18,9 +20,83 @@ var AuthJWTKeysCommand = &cli.Command{
 	Usage: "JWT signing key helpers",
 	Subcommands: []*cli.Command{
 		AuthJWTKeysListCommand,
+		AuthJWTKeysRotateCommand,
 	},
 }
 
+// AuthJWTKeysRotateCommand replaces the active JWT signing key.
+var AuthJWTKeysRotateCommand = &cli.Command{
+	Name:      "rotate",
+	Usage:     "Replaces the active JWT signing key",
+	ArgsUsage: "",
+	Flags: []cli.Flag{
+		JsonFlag(),
+	},
+	Action: authJWTKeysRotateAction,
+}
+
+// authJWTKeysRotateAction issues a new portal signing key and reports both key IDs.
+// The replaced key stays in the JWKS for jwt.RotationOverlap.
+func authJWTKeysRotateAction(ctx *cli.Context) error {
+	return CallWithDependencies(ctx, func(conf *config.Config) error {
+		if err := requirePortal(conf); err != nil {
+			return err
+		}
+
+		manager := get.JWTManager()
+		if manager == nil {
+			return cli.Exit(errors.New("jwt manager not available"), 1)
+		}
+
+		prev, _ := manager.ActiveKey()
+
+		// A new key signs as soon as it exists, so an error alongside one means only the
+		// retirement is outstanding. A plain failure would invite a key-minting retry.
+		key, err := manager.RotateKey()
+		if err != nil && key == nil {
+			return cli.Exit(err, 1)
+		} else if err != nil {
+			fmt.Printf("Rotated to %s, but retiring the previous key did not complete: %s\n", key.Kid, err)
+		}
+
+		event.AuditInfo([]string{"cli", "jwt", "rotate signing key", status.Succeeded})
+
+		prevKid := ""
+		retired := ""
+		if prev != nil && prev.Kid != key.Kid {
+			prevKid = prev.Kid
+			for _, k := range manager.AllKeys() {
+				if k.Kid == prevKid && k.NotAfter > 0 {
+					retired = time.Unix(k.NotAfter, 0).UTC().Format(time.RFC3339)
+				}
+			}
+		}
+
+		if ctx.Bool("json") {
+			return printJSON(map[string]any{
+				"kid":      key.Kid,
+				"replaced": prevKid,
+				"notAfter": retired,
+			})
+		}
+
+		fmt.Println()
+		fmt.Printf("New signing key: %s\n", key.Kid)
+		switch {
+		case prevKid == "":
+			fmt.Println("No previous key to replace.")
+		case retired == "":
+			fmt.Printf("Replaced key %s.\n", prevKid)
+		default:
+			fmt.Printf("Replaced key %s, which verifies until %s.\n", prevKid, retired)
+		}
+		fmt.Println("A running portal loads its keys at startup, so restart it to use the new key.")
+		fmt.Println()
+
+		return nil
+	})
+}
+
 // AuthJWTKeysListCommand lists JWT signing keys.
 var AuthJWTKeysListCommand = &cli.Command{
 	Name:      "ls",

internal/config/config_cluster.go

@@ -754,6 +754,17 @@ func (c *Config) JWTLeeway() int {
 	return c.options.JWTLeeway
 }
 
+// JWTRotateDays returns the portal signing key lifetime in days, 0 when scheduled rotation
+// is off. Use a negative value to disable it everywhere: ApplyCliContext reads a zero from
+// defaults.yml as unset, so 0 only disables from a flag, an env var, or options.yml.
+func (c *Config) JWTRotateDays() int {
+	if c.options.JWTRotateDays < 0 {
+		return 0
+	}
+
+	return c.options.JWTRotateDays
+}
+
 // JWTAllowedScopes returns an optional allow-list of accepted JWT scopes.
 func (c *Config) JWTAllowedScopes() list.Attr {
 	if s := strings.TrimSpace(c.options.JWTScope); s != "" {

internal/config/config_cluster_test.go

@@ -992,3 +992,30 @@ func TestConfig_ClusterUUID_GenerateAndPersist(t *testing.T) {
 
 	c.options.OptionsYaml = optionsOriginal
 }
+
+func TestConfig_JWTRotateDays(t *testing.T) {
+	c := NewConfig(CliTestContext())
+	original := c.options.JWTRotateDays
+
+	t.Cleanup(func() {
+		c.options.JWTRotateDays = original
+	})
+
+	t.Run("Default", func(t *testing.T) {
+		c.options.JWTRotateDays = 90
+		assert.Equal(t, 90, c.JWTRotateDays())
+	})
+	t.Run("Custom", func(t *testing.T) {
+		c.options.JWTRotateDays = 30
+		assert.Equal(t, 30, c.JWTRotateDays())
+	})
+	t.Run("Disabled", func(t *testing.T) {
+		// 0 means the operator asked for manual rotation, so it must not read as unset.
+		c.options.JWTRotateDays = 0
+		assert.Equal(t, 0, c.JWTRotateDays())
+	})
+	t.Run("Negative", func(t *testing.T) {
+		c.options.JWTRotateDays = -7
+		assert.Equal(t, 0, c.JWTRotateDays())
+	})
+}

internal/config/flags.go

@@ -844,6 +844,12 @@ var Flags = CliFlags{
 			Value:   60,
 			EnvVars: EnvVars("JWT_LEEWAY"),
 		}}, {
+		Flag: &cli.IntFlag{
+			Name:    "jwt-rotate-days",
+			Usage:   "portal JWT signing key lifetime in `DAYS`, -1 to rotate manually only",
+			Value:   90,
+			EnvVars: EnvVars("JWT_ROTATE_DAYS"),
+		}}, {
 		Flag: &cli.StringFlag{
 			Name:    "portal-oidc-issuer",
 			Usage:   "Portal OIDC OP issuer `URL` advertised in discovery and ID tokens (defaults to site-url)",

internal/config/options.go

@@ -176,6 +176,7 @@ type Options struct {
 	JWKSCacheTTL              int           `yaml:"JWKSCacheTTL" json:"-" flag:"jwks-cache-ttl"`
 	JWTScope                  string        `yaml:"JWTScope" json:"-" flag:"jwt-scope"`
 	JWTLeeway                 int           `yaml:"JWTLeeway" json:"-" flag:"jwt-leeway"`
+	JWTRotateDays             int           `yaml:"JWTRotateDays" json:"-" flag:"jwt-rotate-days"`
 	PortalOIDCIssuer          string        `yaml:"PortalOIDCIssuer" json:"-" flag:"portal-oidc-issuer"`
 	PortalOIDCTTL             int           `yaml:"PortalOIDCTTL" json:"-" flag:"portal-oidc-ttl"`
 	PortalOIDCCodeTTL         int           `yaml:"PortalOIDCCodeTTL" json:"-" flag:"portal-oidc-code-ttl"`

internal/config/report.go

@@ -226,6 +226,7 @@ func (c *Config) Report() (rows [][]string, cols []string) {
 		{"jwks-cache-ttl", fmt.Sprintf("%d", c.JWKSCacheTTL())},
 		{"jwt-scope", c.JWTAllowedScopes().String()},
 		{"jwt-leeway", fmt.Sprintf("%d", c.JWTLeeway())},
+		{"jwt-rotate-days", fmt.Sprintf("%d", c.JWTRotateDays())},
 		{"advertise-url", clean.UriRedacted(c.AdvertiseUrl())},
 
 		// Networking.

internal/workers/jwt_keys.go

@@ -0,0 +1,81 @@
+package workers
+
+import (
+	"errors"
+	"fmt"
+	iofs "io/fs"
+	"time"
+
+	"github.com/photoprism/photoprism/internal/auth/jwt"
+	"github.com/photoprism/photoprism/internal/config"
+	"github.com/photoprism/photoprism/internal/event"
+	"github.com/photoprism/photoprism/internal/photoprism/get"
+	"github.com/photoprism/photoprism/pkg/clean"
+)
+
+// JWTKeySchedule is the cron expression for the portal signing key check.
+// Key lifetimes are measured in days, so a daily check is close enough.
+const JWTKeySchedule = "0 4 * * *"
+
+// jwtManager resolves the portal signing key manager, replaced in tests.
+var jwtManager = get.JWTManager
+
+// RunJWTKeyRotation replaces the portal JWT signing key once it reaches the configured
+// lifetime. The due-date check reads memory only, so a run that is not due touches no disk.
+func RunJWTKeyRotation(conf *config.Config) {
+	if conf == nil || !conf.Portal() {
+		return
+	}
+
+	days := conf.JWTRotateDays()
+
+	if days <= 0 {
+		return
+	}
+
+	rotateJWTKeys(jwtManager(), days)
+}
+
+// rotateJWTKeys rotates the signing key held by manager once it reaches days, and
+// otherwise reapplies a retirement that an earlier run did not persist.
+func rotateJWTKeys(manager *jwt.Manager, days int) {
+	if manager == nil {
+		return
+	}
+
+	if !manager.NeedsRotation(time.Duration(days) * 24 * time.Hour) {
+		// Pick up a key whose retirement did not reach disk on an earlier run.
+		if n, err := manager.RetireSuperseded(); err != nil {
+			event.SystemError([]string{"jwt", "retire superseded signing key", "%s"}, keyErrorText(err))
+		} else if n > 0 {
+			event.SystemInfo([]string{"jwt", "retired %d superseded signing keys"}, n)
+		}
+
+		return
+	}
+
+	key, err := manager.RotateKey()
+
+	// A new key signs as soon as it exists, so an error after that point means the
+	// replacement succeeded and only the retirement is outstanding.
+	switch {
+	case err != nil && key == nil:
+		event.SystemError([]string{"jwt", "rotate signing key", "%s"}, keyErrorText(err))
+	case err != nil:
+		event.SystemWarn([]string{"jwt", "rotated signing key, retirement pending", "%s"}, keyErrorText(err))
+	default:
+		event.SystemInfo([]string{"jwt", "rotated signing key after %d days", "new key id %s"}, days, clean.Log(key.Kid))
+	}
+}
+
+// keyErrorText renders a key I/O error without the file path it names, since the system
+// channel is delivered to the web UI.
+func keyErrorText(err error) string {
+	var pathErr *iofs.PathError
+
+	if errors.As(err, &pathErr) {
+		return clean.Error(fmt.Errorf("%s: %w", pathErr.Op, pathErr.Err))
+	}
+
+	return clean.Error(err)
+}

internal/workers/jwt_keys_test.go

@@ -0,0 +1,108 @@
+package workers
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/go-co-op/gocron/v2"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/photoprism/photoprism/internal/auth/jwt"
+	"github.com/photoprism/photoprism/internal/config"
+)
+
+// newJWTTestManager returns a key manager backed by a temp config directory.
+func newJWTTestManager(t *testing.T) *jwt.Manager {
+	t.Helper()
+
+	c := config.NewMinimalTestConfig(t.TempDir())
+
+	m, err := jwt.NewManager(c)
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		_ = os.RemoveAll(filepath.Join(c.PortalConfigPath(), "keys"))
+	})
+
+	return m
+}
+
+func TestRunJWTKeyRotation(t *testing.T) {
+	// The portal gate is what RunJWTKeyRotation adds over rotateJWTKeys, so it is what
+	// these cases cover; the rotation itself is exercised through rotateJWTKeys below.
+	t.Run("NilConfig", func(t *testing.T) {
+		assert.NotPanics(t, func() { RunJWTKeyRotation(nil) })
+	})
+	t.Run("NotAPortal", func(t *testing.T) {
+		c := config.NewMinimalTestConfig(t.TempDir())
+		require.False(t, c.Portal())
+
+		// Instances do not issue JWTs, so the manager must not even be resolved.
+		resolved := false
+		original := jwtManager
+		jwtManager = func() *jwt.Manager { resolved = true; return nil }
+		t.Cleanup(func() { jwtManager = original })
+
+		RunJWTKeyRotation(c)
+		assert.False(t, resolved)
+	})
+}
+
+func TestRotateJWTKeys(t *testing.T) {
+	t.Run("NoManager", func(t *testing.T) {
+		assert.NotPanics(t, func() { rotateJWTKeys(nil, 90) })
+	})
+	t.Run("NotDue", func(t *testing.T) {
+		m := newJWTTestManager(t)
+		before, err := m.EnsureActiveKey()
+		require.NoError(t, err)
+
+		rotateJWTKeys(m, 90)
+
+		after, err := m.ActiveKey()
+		require.NoError(t, err)
+		assert.Equal(t, before.Kid, after.Kid)
+		assert.Len(t, m.JWKS().Keys, 1)
+	})
+	t.Run("Disabled", func(t *testing.T) {
+		m := newJWTTestManager(t)
+		before, err := m.EnsureActiveKey()
+		require.NoError(t, err)
+
+		m.SetNow(func() time.Time { return time.Now().UTC().Add(10 * 365 * 24 * time.Hour) })
+		rotateJWTKeys(m, 0)
+
+		after, err := m.ActiveKey()
+		require.NoError(t, err)
+		assert.Equal(t, before.Kid, after.Kid, "a disabled lifetime must not rotate, however old the key is")
+	})
+	t.Run("Due", func(t *testing.T) {
+		m := newJWTTestManager(t)
+		before, err := m.EnsureActiveKey()
+		require.NoError(t, err)
+
+		// Move past the configured lifetime so the run is due.
+		m.SetNow(func() time.Time { return time.Now().UTC().Add(91 * 24 * time.Hour) })
+		rotateJWTKeys(m, 90)
+
+		after, err := m.ActiveKey()
+		require.NoError(t, err)
+		assert.NotEqual(t, before.Kid, after.Kid)
+		assert.EqualValues(t, 0, after.NotAfter)
+		// The replaced key keeps verifying during the overlap.
+		assert.Len(t, m.JWKS().Keys, 2)
+	})
+}
+
+func TestJWTKeySchedule(t *testing.T) {
+	// NewJob feeds this to gocron, which rejects a malformed expression at registration.
+	scheduler, err := gocron.NewScheduler()
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = scheduler.Shutdown() })
+
+	_, err = scheduler.NewJob(gocron.CronJob(JWTKeySchedule, false), gocron.NewTask(func() {}))
+	assert.NoError(t, err)
+}

internal/workers/workers.go

@@ -56,6 +56,17 @@ func Start(conf *config.Config) {
 			log.Errorf("scheduler: %s (backup)", err)
 		}
 
+		// Only portals issue JWTs, so only they need a signing key to rotate. The startup
+		// check runs as well, since a portal that is never up at the scheduled hour would
+		// otherwise never reach a tick.
+		if conf.Portal() {
+			if err = NewJob("jwt-keys", JWTKeySchedule, func() { RunJWTKeyRotation(conf) }); err != nil {
+				log.Errorf("scheduler: %s (jwt keys)", err)
+			}
+
+			go event.Safe(func() { RunJWTKeyRotation(conf) })
+		}
+
 		// Only schedule index and vision jobs if this is not a portal.
 		if !conf.Portal() {
 			// Schedule indexing job.