Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -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=
Expand Down
36 changes: 36 additions & 0 deletions http/server/example_test.go
Original file line number Diff line number Diff line change
@@ -1,13 +1,16 @@
package server_test

import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"time"

"github.com/golang-jwt/jwt/v5"

"github.com/dioad/lifecycle"

"github.com/dioad/auth/http/server"
"github.com/dioad/auth/oidc"
)
Expand Down Expand Up @@ -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:
// <nil>
// map[jwt-validators:ok]
}
56 changes: 56 additions & 0 deletions http/server/readiness.go
Original file line number Diff line number Diff line change
@@ -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...)...)
}
176 changes: 176 additions & 0 deletions http/server/readiness_test.go
Original file line number Diff line number Diff line change
@@ -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")
}
Loading