diff --git a/go.mod b/go.mod index 31dea36..3134f11 100644 --- a/go.mod +++ b/go.mod @@ -12,6 +12,7 @@ require ( github.com/cli/oauth v1.3.0 github.com/dioad/config v0.2.0 github.com/dioad/generics v0.0.9 + github.com/dioad/lifecycle v0.2.0 github.com/dioad/net v0.72.0 github.com/dioad/util v0.7.0 github.com/go-jose/go-jose/v4 v4.1.9 diff --git a/go.sum b/go.sum index 4cd42cc..00cb630 100644 --- a/go.sum +++ b/go.sum @@ -55,8 +55,8 @@ github.com/dioad/filter v0.6.1 h1:iEX/ztIXrI+udLt94N55TAIOd7JjCzIiIbYKG9B96sY= github.com/dioad/filter v0.6.1/go.mod h1:s8x3fpSsovtPo0tM8YEpzA3Y3bQtGAZwsHpzAVT1qBA= github.com/dioad/generics v0.0.9 h1:886ArS3vNm+c6usRuQmEhhyqxVLbJSdM5NMPnM49Ya8= github.com/dioad/generics v0.0.9/go.mod h1:NFn4N/41m2Ln8xjKm6c9ieZQeKohyCEg0RfQg34aVRg= -github.com/dioad/lifecycle v0.1.0 h1:vjR3ZElupNjZjvRNdSC8hzZ8gZRNqCSXFr/lfDFe5gM= -github.com/dioad/lifecycle v0.1.0/go.mod h1:o84RixfNcp4pkqTCE7Jw87JTYMrE+/z55TNErGRrCnI= +github.com/dioad/lifecycle v0.2.0 h1:/OeajDlOtjyd0BNKzPZGYQewTvDz2XNAiIfv1jgRLsw= +github.com/dioad/lifecycle v0.2.0/go.mod h1:o84RixfNcp4pkqTCE7Jw87JTYMrE+/z55TNErGRrCnI= github.com/dioad/net v0.72.0 h1:xLSqJlDBJWlIgiHtO+9O6iNCqwcHXkvlgLTiVVUhwGs= github.com/dioad/net v0.72.0/go.mod h1:AIQG8/RbqCLT61l83zDspEHB9znKZ+wH4cvbmyw9HvI= github.com/dioad/util v0.7.0 h1:DdSits6ZE/m6FSkSHLrPFehJJT7VlDGxxHkiZQ4xzaQ= diff --git a/http/server/example_test.go b/http/server/example_test.go index 82dfb45..d12b11f 100644 --- a/http/server/example_test.go +++ b/http/server/example_test.go @@ -1,6 +1,7 @@ package server_test import ( + "context" "fmt" "net/http" "net/http/httptest" @@ -8,6 +9,8 @@ import ( "github.com/golang-jwt/jwt/v5" + "github.com/dioad/lifecycle" + "github.com/dioad/auth/http/server" "github.com/dioad/auth/oidc" ) @@ -67,3 +70,36 @@ func ExampleOAuth2ValidatorHandler() { // token in a cookie: 401 // bad token: 401 } + +// ExampleAddValidatorCheck reports the identity provider behind a service's +// token validators as a readiness check. The check is degraded, not failing, so +// an identity provider outage shows in the report without taking the service out +// of rotation. +// +// The example serves a minimal discovery document and key set so that it runs +// without a real provider. +func ExampleAddValidatorCheck() { + var issuer *httptest.Server + issuer = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + switch r.URL.Path { + case "/.well-known/openid-configuration": + _, _ = fmt.Fprintf(w, `{"issuer":%q,"jwks_uri":%q}`, issuer.URL, issuer.URL+"/jwks") + case "/jwks": + _, _ = fmt.Fprint(w, `{"keys":[{"kty":"RSA","kid":"k1"}]}`) + default: + http.NotFound(w, r) + } + })) + defer issuer.Close() + + readiness := lifecycle.NewReadiness() + server.AddValidatorCheck(readiness, []oidc.ValidatorConfig{{Issuer: issuer.URL}}) + readiness.MarkStarted() + + report, err := readiness.Ready(context.Background()) + fmt.Println(err) + fmt.Println(report) + // Output: + // + // map[jwt-validators:ok] +} diff --git a/http/server/readiness.go b/http/server/readiness.go new file mode 100644 index 0000000..2f9e2b3 --- /dev/null +++ b/http/server/readiness.go @@ -0,0 +1,56 @@ +package server + +import ( + "context" + "net/http" + "time" + + "github.com/dioad/lifecycle" + + "github.com/dioad/auth/oidc" +) + +const ( + // ValidatorCheckName is the name AddValidatorCheck registers the check under, + // and so the key it has in a readiness report. + ValidatorCheckName = "jwt-validators" + + // DefaultValidatorCheckTimeout caps the check and each of its requests. It is + // below the 5s that Fly and lifecycle.DefaultCheckTimeout both use, so a hung + // identity provider makes the check report degraded rather than the probe + // itself time out. + DefaultValidatorCheckTimeout = 2 * time.Second + + // DefaultValidatorCheckCacheTTL is how long a result is reused, so frequent + // probes make at most one discovery and one JWKS request per issuer per + // interval per instance. + DefaultValidatorCheckCacheTTL = 30 * time.Second +) + +// AddValidatorCheck adds a readiness check to r that every identity provider +// behind validators answers OIDC discovery and serves at least one signing key +// (see oidc.ProbeValidators). It adds nothing when no validator fetches keys: +// none configured, or all use a static HMAC secret. +// +// The check is degraded, not failing: an identity provider outage affects every +// instance alike, so failing readiness would take the whole service out of +// rotation without moving traffic anywhere that could validate tokens. A pass +// means each issuer was reachable within DefaultValidatorCheckCacheTTL; it does +// not prove the validators' own key caches are current. +// +// opts follow the defaults, so WithCheckTimeout or WithCacheTTL replaces them. +func AddValidatorCheck(r *lifecycle.Readiness, validators []oidc.ValidatorConfig, opts ...lifecycle.CheckOption) { + if len(oidc.KeyFetchingIssuers(validators)) == 0 { + return + } + client := &http.Client{Timeout: DefaultValidatorCheckTimeout} + all := make([]lifecycle.CheckOption, 0, 3+len(opts)) + all = append(all, + lifecycle.WithDegraded(), + lifecycle.WithCacheTTL(DefaultValidatorCheckCacheTTL), + lifecycle.WithCheckTimeout(DefaultValidatorCheckTimeout), + ) + r.AddCheck(ValidatorCheckName, func(ctx context.Context) error { + return oidc.ProbeValidators(ctx, validators, client) + }, append(all, opts...)...) +} diff --git a/http/server/readiness_test.go b/http/server/readiness_test.go new file mode 100644 index 0000000..02ca77c --- /dev/null +++ b/http/server/readiness_test.go @@ -0,0 +1,176 @@ +package server_test + +import ( + "net/http" + "net/http/httptest" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/dioad/lifecycle" + + "github.com/dioad/auth/http/server" + "github.com/dioad/auth/oidc" +) + +// fakeIssuer serves an OIDC discovery document and a JWKS, counting discovery +// requests. +type fakeIssuer struct { + *httptest.Server + + discoveries atomic.Int32 +} + +func newFakeIssuer(t *testing.T, jwks string) *fakeIssuer { + t.Helper() + idp := &fakeIssuer{} + idp.Server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + switch r.URL.Path { + case "/.well-known/openid-configuration": + idp.discoveries.Add(1) + _, _ = w.Write([]byte(`{"issuer":"` + idp.URL + `","jwks_uri":"` + idp.URL + `/jwks"}`)) + case "/jwks": + _, _ = w.Write([]byte(jwks)) + default: + http.NotFound(w, r) + } + })) + t.Cleanup(idp.Close) + + return idp +} + +// fakeClock is a settable clock for the readiness cache. +type fakeClock struct{ now atomic.Int64 } + +func (c *fakeClock) Now() time.Time { return time.Unix(0, c.now.Load()) } +func (c *fakeClock) Advance(d time.Duration) { c.now.Add(int64(d)) } + +const oneKey = `{"keys":[{"kty":"RSA","kid":"k1"}]}` + +// started returns a started Readiness with the validators' check added. +func started(validators []oidc.ValidatorConfig, readiness ...lifecycle.ReadinessOption) *lifecycle.Readiness { + r := lifecycle.NewReadiness(readiness...) + server.AddValidatorCheck(r, validators) + r.MarkStarted() + + return r +} + +// details returns the per-check report of r.Ready. +func details(t *testing.T, r *lifecycle.Readiness) map[string]string { + t.Helper() + report, err := r.Ready(t.Context()) + require.NoError(t, err, "an identity provider problem must not make the instance not-ready") + checks, ok := report.(map[string]string) + require.True(t, ok) + + return checks +} + +func TestAddValidatorCheck_AddsNothingWithoutKeyFetchingValidators(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + validators []oidc.ValidatorConfig + }{ + {"no validators", nil}, + {"only HMAC validators", []oidc.ValidatorConfig{{Issuer: "https://issuer.example", HMACSecret: "s3cr3t", AllowInsecureHMAC: true}}}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + assert.Empty(t, details(t, started(tc.validators))) + }) + } +} + +func TestAddValidatorCheck_ReportsTheIdentityProviderAsADegradedDependency(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + jwks string + want string + }{ + {"keys served", oneKey, "ok"}, + {"empty key set", `{"keys":[]}`, "degraded: "}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + idp := newFakeIssuer(t, tc.jwks) + + checks := details(t, started([]oidc.ValidatorConfig{{Issuer: idp.URL}})) + + assert.Contains(t, checks[server.ValidatorCheckName], tc.want) + }) + } +} + +func TestAddValidatorCheck_ProbesEachIssuerOnceAndReusesTheResult(t *testing.T) { + t.Parallel() + + idp := newFakeIssuer(t, oneKey) + clock := &fakeClock{} + r := started([]oidc.ValidatorConfig{{Issuer: idp.URL}, {Issuer: idp.URL}}, lifecycle.WithClock(clock.Now)) + + details(t, r) + details(t, r) + assert.Equal(t, int32(1), idp.discoveries.Load(), "validators sharing an issuer are probed once, and the result is cached") + + clock.Advance(server.DefaultValidatorCheckCacheTTL) + details(t, r) + assert.Equal(t, int32(2), idp.discoveries.Load(), "the issuer is probed again once the cached result expires") +} + +func TestAddValidatorCheck_AHangingIssuerIsBoundedByTheCheckTimeout(t *testing.T) { + t.Parallel() + + release := make(chan struct{}) + hang := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) { + select { + case <-release: + case <-r.Context().Done(): + } + })) + t.Cleanup(func() { close(release); hang.Close() }) + idp := newFakeIssuer(t, oneKey) + r := started([]oidc.ValidatorConfig{{Issuer: hang.URL}, {Issuer: idp.URL}}) + + start := time.Now() + checks := details(t, r) + + assert.Less(t, time.Since(start), server.DefaultValidatorCheckTimeout+time.Second, + "issuers are probed concurrently within one check timeout") + assert.Contains(t, checks[server.ValidatorCheckName], "degraded: "+hang.URL) + assert.NotContains(t, checks[server.ValidatorCheckName], idp.URL+":", "a hanging issuer must not use up the time the others need") +} + +func TestAddValidatorCheck_OptionsReplaceTheDefaults(t *testing.T) { + t.Parallel() + + release := make(chan struct{}) + hang := httptest.NewServer(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) { + select { + case <-release: + case <-r.Context().Done(): + } + })) + t.Cleanup(func() { close(release); hang.Close() }) + r := lifecycle.NewReadiness() + server.AddValidatorCheck(r, []oidc.ValidatorConfig{{Issuer: hang.URL}}, lifecycle.WithCheckTimeout(50*time.Millisecond)) + r.MarkStarted() + + start := time.Now() + details(t, r) + + assert.Less(t, time.Since(start), time.Second, "a shorter timeout passed as an option must replace the default") +}