Merge pull request #8 from Sovietaced/background-metadata

Add support for fetching metadata in the background

Author: Sovietaced

README.md

@@ -5,7 +5,7 @@
 [![Go Report](https://goreportcard.com/badge/github.com/sovietaced/okta-jwt-verifier)](https://goreportcard.com/report/github.com/sovietaced/okta-jwt-verifier)
 
 Alternative implementation to the official [okta-jwt-verifier](https://github.com/okta/okta-jwt-verifier-golang) that 
-includes support for telemetry (ie. OpenTelemetry), minimizing operational latency, and testability.
+includes support for telemetry (ie. OpenTelemetry), minimizing verification latency, and testability.
 
 ## Examples
 
@@ -21,7 +21,8 @@ func main() {
     ctx := context.Background()
     issuer := "https://test.okta.com"
     clientId := "test"
-    v := verifier.NewVerifier(issuer, clientId)
+    v, err := verifier.NewVerifier(issuer, clientId)
+	
 
     idToken := "..."
     token, err := v.VerifyAccessToken(ctx, idToken)

metadata/okta/okta.go

@@ -11,15 +11,25 @@ import (
 	"time"
 )
 
+type FetchStrategy int64
+
 const (
+	Lazy FetchStrategy = iota // Fetch new metadata inline with requests (when not cached)
+	// Background Fetch new metadata in the background regardless of requests being made. This option was designed
+	// for eliminating in-line metadata calls and minimizing latency in production use. Warning: this option will
+	// attempt to seed metadata on initialization and block.
+	Background
+
 	DefaultCacheTtl = 5 * time.Minute
 )
 
 // Options are configurable options for the MetadataProvider.
 type Options struct {
-	httpClient *http.Client
-	cacheTtl   time.Duration
-	clock      clock.Clock
+	httpClient    *http.Client
+	cacheTtl      time.Duration
+	clock         clock.Clock
+	fetchStrategy FetchStrategy
+	backgroundCtx context.Context
 }
 
 // WithHttpClient allows for a configurable http client.
@@ -42,11 +52,28 @@ func withClock(clock clock.Clock) Option {
 	}
 }
 
+// WithFetchStrategy specifies a strategy for fetching new metadata.
+func WithFetchStrategy(fetchStrategy FetchStrategy) Option {
+	return func(mo *Options) {
+		mo.fetchStrategy = fetchStrategy
+	}
+}
+
+// WithBackgroundCtx specified the context to use in order to control the lifecycle of the background fetching
+// goroutine.
+func WithBackgroundCtx(ctx context.Context) Option {
+	return func(mo *Options) {
+		mo.backgroundCtx = ctx
+	}
+}
+
 func defaultOptions() *Options {
 	opts := &Options{}
 	WithHttpClient(http.DefaultClient)(opts)
 	withClock(clock.New())(opts)
 	WithCacheTtl(DefaultCacheTtl)(opts)
+	WithFetchStrategy(Lazy)(opts)
+	WithBackgroundCtx(context.Background())(opts)
 	return opts
 }
 
@@ -72,22 +99,34 @@ type MetadataProvider struct {
 	metadataMutex  sync.Mutex
 	cacheTtl       time.Duration
 	cachedMetadata *cachedMetadata
+	fetchStrategy  FetchStrategy
 }
 
 // NewMetadataProvider creates a new MetadataProvider for the specified Okta issuer.
-func NewMetadataProvider(issuer string, options ...Option) *MetadataProvider {
+func NewMetadataProvider(issuer string, options ...Option) (*MetadataProvider, error) {
 	opts := defaultOptions()
 	for _, option := range options {
 		option(opts)
 	}
 
 	metadataUrl := fmt.Sprintf("%s%s", issuer, "/.well-known/openid-configuration")
-	return &MetadataProvider{
-		metadataUrl: metadataUrl,
-		httpClient:  opts.httpClient,
-		clock:       opts.clock,
-		cacheTtl:    opts.cacheTtl,
+	mp := &MetadataProvider{
+		metadataUrl:   metadataUrl,
+		httpClient:    opts.httpClient,
+		clock:         opts.clock,
+		cacheTtl:      opts.cacheTtl,
+		fetchStrategy: opts.fetchStrategy,
 	}
+
+	if opts.fetchStrategy == Background {
+		_, err := mp.backgroundFetchAndCache(opts.backgroundCtx)
+		if err != nil {
+			return nil, fmt.Errorf("failed to seed metadata: %w", err)
+		}
+		go mp.backgroundFetchLoop(opts.backgroundCtx)
+	}
+
+	return mp, nil
 }
 
 // GetMetadata gets metadata for the specified Okta issuer.
@@ -99,12 +138,21 @@ func (mp *MetadataProvider) GetMetadata(ctx context.Context) (metadata.Metadata,
 		return cachedMetadataCopy.m, nil
 	}
 
+	if mp.fetchStrategy == Lazy {
+		return mp.lazyFetchAndCache(ctx)
+	}
+
+	return metadata.Metadata{}, fmt.Errorf("no metadata available")
+
+}
+
+func (mp *MetadataProvider) lazyFetchAndCache(ctx context.Context) (metadata.Metadata, error) {
 	// Acquire a lock
 	mp.metadataMutex.Lock()
 	defer mp.metadataMutex.Unlock()
 
 	// Check for a race before continuing
-	cachedMetadataCopy = mp.cachedMetadata
+	cachedMetadataCopy := mp.cachedMetadata
 	if cachedMetadataCopy != nil && mp.clock.Now().Before(cachedMetadataCopy.expiration) {
 		return cachedMetadataCopy.m, nil
 	}
@@ -120,6 +168,44 @@ func (mp *MetadataProvider) GetMetadata(ctx context.Context) (metadata.Metadata,
 	return mp.cachedMetadata.m, nil
 }
 
+func (mp *MetadataProvider) backgroundFetchAndCache(ctx context.Context) (metadata.Metadata, error) {
+	// Acquire a lock
+	mp.metadataMutex.Lock()
+	defer mp.metadataMutex.Unlock()
+
+	expiration := mp.clock.Now().Add(mp.cacheTtl)
+
+	newMetadata, err := mp.fetchMetadata(ctx)
+	if err != nil {
+		return metadata.Metadata{}, fmt.Errorf("failed to fetch new fresh metadata: %w", err)
+	}
+
+	mp.cachedMetadata = newCachedMetadata(expiration, newMetadata)
+	return mp.cachedMetadata.m, nil
+}
+
+func (mp *MetadataProvider) backgroundFetchLoop(ctx context.Context) {
+	// Seed cache initially
+	_, err := mp.backgroundFetchAndCache(ctx)
+	if err != nil {
+		// FIXME: log this
+	}
+
+	ticker := time.NewTicker(mp.cacheTtl / 2)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			_, err := mp.backgroundFetchAndCache(ctx)
+			if err != nil {
+				// FIXME: log this
+			}
+		}
+	}
+}
+
 func (mp *MetadataProvider) fetchMetadata(ctx context.Context) (metadata.Metadata, error) {
 	httpRequest, err := http.NewRequestWithContext(ctx, http.MethodGet, mp.metadataUrl, nil)
 	if err != nil {

metadata/okta/okta_test.go

@@ -19,7 +19,7 @@ import (
 	"go.opentelemetry.io/otel/sdk/trace/tracetest"
 )
 
-func TestMetadataProvider(t *testing.T) {
+func TestLazyMetadataProvider(t *testing.T) {
 
 	ctx := context.Background()
 
@@ -29,7 +29,8 @@ func TestMetadataProvider(t *testing.T) {
 		}))
 		defer svr.Close()
 
-		mp := NewMetadataProvider(svr.URL)
+		mp, err := NewMetadataProvider(svr.URL)
+		require.NoError(t, err)
 
 		m, err := mp.GetMetadata(ctx)
 		require.NoError(t, err)
@@ -47,9 +48,10 @@ func TestMetadataProvider(t *testing.T) {
 		defer svr.Close()
 
 		fakeClock := clock.NewMock()
-		mp := NewMetadataProvider(svr.URL, withClock(fakeClock))
+		mp, err := NewMetadataProvider(svr.URL, withClock(fakeClock))
+		require.NoError(t, err)
 
-		_, err := mp.GetMetadata(ctx)
+		_, err = mp.GetMetadata(ctx)
 		require.NoError(t, err)
 		require.Equal(t, 1, serverCount)
 
@@ -83,11 +85,12 @@ func TestMetadataProvider(t *testing.T) {
 		)
 
 		httpClient := http.Client{Transport: tr}
-		mp := NewMetadataProvider(svr.URL, WithHttpClient(&httpClient))
+		mp, err := NewMetadataProvider(svr.URL, WithHttpClient(&httpClient))
+		require.NoError(t, err)
 
 		tracer := provider.Tracer("test")
 		spanCtx, span := tracer.Start(ctx, "test")
-		_, err := mp.GetMetadata(spanCtx)
+		_, err = mp.GetMetadata(spanCtx)
 		require.NoError(t, err)
 		span.End()
 
@@ -104,6 +107,62 @@ func TestMetadataProvider(t *testing.T) {
 	})
 }
 
+func TestBackgroundMetadataProvider(t *testing.T) {
+
+	ctx := context.Background()
+
+	t.Run("get metadata success", func(t *testing.T) {
+		svr := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.Write(fixture(t, "metadata.json"))
+		}))
+		defer svr.Close()
+
+		backgroundCtx, cancelFunc := context.WithCancel(ctx)
+		defer cancelFunc()
+
+		mp, err := NewMetadataProvider(svr.URL, WithFetchStrategy(Background), WithBackgroundCtx(backgroundCtx))
+		require.NoError(t, err)
+
+		m, err := mp.GetMetadata(ctx)
+		require.NoError(t, err)
+
+		expectedMetadata := metadata.Metadata{JwksUri: "https://test.okta.com/oauth2/v1/keys"}
+		require.Equal(t, expectedMetadata, m)
+	})
+
+	t.Run("get metadata and verify cached", func(t *testing.T) {
+		serverCount := 0
+		svr := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			serverCount++
+			w.Write(fixture(t, "metadata.json"))
+		}))
+		defer svr.Close()
+
+		backgroundCtx, cancelFunc := context.WithCancel(ctx)
+		defer cancelFunc()
+
+		fakeClock := clock.NewMock()
+		mp, err := NewMetadataProvider(svr.URL, withClock(fakeClock), WithFetchStrategy(Background), WithBackgroundCtx(backgroundCtx))
+		require.NoError(t, err)
+
+		_, err = mp.GetMetadata(ctx)
+		require.NoError(t, err)
+		require.Equal(t, 1, serverCount)
+
+		// Get metadata again and ensure it is cached
+		_, err = mp.GetMetadata(ctx)
+		require.NoError(t, err)
+		require.Equal(t, 1, serverCount)
+
+		// Fast forward time and invalidate the cache
+		fakeClock.Add(10 * time.Minute)
+
+		_, err = mp.GetMetadata(ctx)
+		require.NoError(t, err)
+		require.Equal(t, 2, serverCount)
+	})
+}
+
 func fixture(t *testing.T, filename string) []byte {
 	b, err := os.ReadFile(fmt.Sprintf("testdata/%s", filename))
 	if err != nil {

verifier.go

@@ -35,11 +35,15 @@ func WithLeeway(leeway time.Duration) Option {
 	}
 }
 
-func defaultOptions(issuer string) *Options {
+func defaultOptions(issuer string) (*Options, error) {
 	opts := &Options{}
-	WithKeyfuncProvider(okta.NewKeyfuncProvider(oktametadata.NewMetadataProvider(issuer)))(opts)
+	mp, err := oktametadata.NewMetadataProvider(issuer)
+	if err != nil {
+		return nil, fmt.Errorf("creating default metadata provider: %w", err)
+	}
+	WithKeyfuncProvider(okta.NewKeyfuncProvider(mp))(opts)
 	WithLeeway(DefaultLeeway)(opts)
-	return opts
+	return opts, nil
 }
 
 // Option for the Verifier
@@ -65,8 +69,11 @@ type Verifier struct {
 }
 
 // NewVerifier creates a new Verifier for the specified issuer or client ID.
-func NewVerifier(issuer string, clientId string, options ...Option) *Verifier {
-	opts := defaultOptions(issuer)
+func NewVerifier(issuer string, clientId string, options ...Option) (*Verifier, error) {
+	opts, err := defaultOptions(issuer)
+	if err != nil {
+		return nil, fmt.Errorf("creating default options: %w", err)
+	}
 	for _, option := range options {
 		option(opts)
 	}
@@ -79,7 +86,7 @@ func NewVerifier(issuer string, clientId string, options ...Option) *Verifier {
 		jwt.WithExpirationRequired(),
 	)
 
-	return &Verifier{issuer: issuer, clientId: clientId, keyfuncProvider: opts.keyfuncProvider, parser: parser}
+	return &Verifier{issuer: issuer, clientId: clientId, keyfuncProvider: opts.keyfuncProvider, parser: parser}, nil
 }
 
 // VerifyIdToken verifies an Okta ID token.

verifier_test.go

@@ -32,7 +32,8 @@ func TestVerifierVerifyIdToken(t *testing.T) {
 	}
 
 	kp := okta.NewKeyfuncProvider(mp)
-	v := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp))
+	v, err := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp))
+	require.NoError(t, err)
 
 	t.Run("verify valid id token", func(t *testing.T) {
 		token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
@@ -160,7 +161,8 @@ func TestVerifierVerifyIdToken(t *testing.T) {
 
 	t.Run("verify id token expiration with leeway", func(t *testing.T) {
 
-		lv := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp), WithLeeway(time.Minute))
+		lv, err := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp), WithLeeway(time.Minute))
+		require.NoError(t, err)
 
 		token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
 			"iss":   issuer,
@@ -211,7 +213,8 @@ func TestVerifierVerifyAccessToken(t *testing.T) {
 	}
 
 	kp := okta.NewKeyfuncProvider(mp)
-	v := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp))
+	v, err := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp))
+	require.NoError(t, err)
 
 	t.Run("verify valid access token", func(t *testing.T) {
 		token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
@@ -360,7 +363,8 @@ func TestVerifierVerifyAccessToken(t *testing.T) {
 
 	t.Run("verify access token expiration with leeway", func(t *testing.T) {
 
-		lv := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp), WithLeeway(time.Minute))
+		lv, err := NewVerifier(issuer, clientId, WithKeyfuncProvider(kp), WithLeeway(time.Minute))
+		require.NoError(t, err)
 
 		token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
 			"iss":   issuer,