Add support for static JWKS

Signed-off-by: Matheus Pimenta <[email protected]>

Author: matheuscscp

README.md

@@ -55,6 +55,32 @@ permissions:
   contents: read
 ```
 
+It's also possible to set a static JWKS JSON document for verifying the token
+signature. This is useful for cases where the OIDC discovery endpoint is not
+reachable from the Internet, e.g. in air-gapped environments. Example:
+
+```yaml
+issuer: https://kubernetes.default.svc.cluster.local
+audience: https://kubernetes.default.svc.cluster.local
+subject: system:serviceaccount:my-app:my-app
+jwks: |
+  {
+    "keys": [
+      {
+        "use": "sig",
+        "kty": "RSA",
+        "kid": "LHVGP8kqzN1MuKRMTsroIcR-7hdicXWdpaquEWcAh9Q",
+        "alg": "RS256",
+        "n": "s5XuFpodwhj6my_gTUHDKbHmQIx-3Tf40OduMZRWlU6_B_nSdjX01kS1UQSGw_G5eVQARooI-tY1vj3bBwn4dEEFa2TlnNnAJca0hj2Izef8A8Uw-mT0fgGI4Hs3xS84Mn_WXNlKXEiPLiFyOGNr0GQBKZDyTps8JUlvnwuWCv1gkzudUHa8B0i8ITSEUclK9_LqZj4zXUAN0Wj_4DVfI_PQ0IHci9K5Q9bgCV0j1EvTsyrwGyLFwyhktUmNhjREAfgYmxvbIRhPSP4YuO2Et1KM7YmjA75cQ9oE3i-QLrOZDripyMRop5RmWttQCEdEWLQWPzBd7aZ5CLbmZuIlIQ",
+        "e": "AQAB"
+      }
+    ]
+  }
+
+permissions:
+  contents: read
+```
+
 This policy will allow OIDC tokens from Google accounts of folks with a
 Chainguard email address to federate and read the repo contents.
 

pkg/jwks/jwks.go

@@ -0,0 +1,41 @@
+// Copyright 2025 Chainguard, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package jwks
+
+import (
+	"crypto"
+	"encoding/json"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/go-jose/go-jose/v4"
+)
+
+// ConfigOption is a function that modifies the OIDC config.
+type ConfigOption func(*oidc.Config)
+
+// NewVerifier creates an OIDC verifier from a JWKS string.
+func NewVerifier(raw string, opts ...ConfigOption) (*oidc.IDTokenVerifier, error) {
+	var jwks jose.JSONWebKeySet
+	if err := json.Unmarshal([]byte(raw), &jwks); err != nil {
+		return nil, err
+	}
+
+	var keys []crypto.PublicKey
+	for _, key := range jwks.Keys {
+		keys = append(keys, key.Key)
+	}
+
+	var issuerURL string // ignored
+	keySet := &oidc.StaticKeySet{PublicKeys: keys}
+	config := &oidc.Config{
+		// Issuer and audience are verified later on by the trust policy.
+		SkipIssuerCheck:   true,
+		SkipClientIDCheck: true,
+	}
+	for _, opt := range opts {
+		opt(config)
+	}
+
+	return oidc.NewVerifier(issuerURL, keySet, config), nil
+}

pkg/jwks/jwks_test.go

@@ -0,0 +1,86 @@
+// Copyright 2025 Chainguard, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package jwks_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/octo-sts/app/pkg/jwks"
+)
+
+func TestNewVerifier(t *testing.T) {
+	// This is a JWKS from a kind Kubernetes cluster.
+	const rawJWKS = `{
+  "keys": [
+    {
+      "use": "sig",
+      "kty": "RSA",
+      "kid": "LHVGP8kqzN1MuKRMTsroIcR-7hdicXWdpaquEWcAh9Q",
+      "alg": "RS256",
+      "n": "s5XuFpodwhj6my_gTUHDKbHmQIx-3Tf40OduMZRWlU6_B_nSdjX01kS1UQSGw_G5eVQARooI-tY1vj3bBwn4dEEFa2TlnNnAJca0hj2Izef8A8Uw-mT0fgGI4Hs3xS84Mn_WXNlKXEiPLiFyOGNr0GQBKZDyTps8JUlvnwuWCv1gkzudUHa8B0i8ITSEUclK9_LqZj4zXUAN0Wj_4DVfI_PQ0IHci9K5Q9bgCV0j1EvTsyrwGyLFwyhktUmNhjREAfgYmxvbIRhPSP4YuO2Et1KM7YmjA75cQ9oE3i-QLrOZDripyMRop5RmWttQCEdEWLQWPzBd7aZ5CLbmZuIlIQ",
+      "e": "AQAB"
+    }
+  ]
+}`
+
+	// This is an expired token. We check both if the verifier errors out due to
+	// the expiry, and also if it succeds when we skip the expiry check, which is
+	// enough to test that the signature is correctly being verified.
+	const rawToken = `eyJhbGciOiJSUzI1NiIsImtpZCI6IkxIVkdQOGtxek4xTXVLUk1Uc3JvSWNSLTdoZGljWFdkcGFxdUVXY0FoOVEifQ.eyJhdWQiOlsiaHR0cHM6Ly9rdWJlcm5ldGVzLmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiXSwiZXhwIjoxNzQ0NzYzODI0LCJpYXQiOjE3NDQ3NjMyMjQsImlzcyI6Imh0dHBzOi8va3ViZXJuZXRlcy5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsIiwianRpIjoiODU2YTA2OWItZmUyZi00OTI4LTgzNGMtOTUwNGYwMmU4MzQzIiwia3ViZXJuZXRlcy5pbyI6eyJuYW1lc3BhY2UiOiJkZWZhdWx0Iiwic2VydmljZWFjY291bnQiOnsibmFtZSI6ImRlZmF1bHQiLCJ1aWQiOiIxYjg3OTNjZC02YTYyLTQ2ZmYtOWNmNy1lN2ZlOWU3Y2RiODYifX0sIm5iZiI6MTc0NDc2MzIyNCwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OmRlZmF1bHQ6ZGVmYXVsdCJ9.NF8UW6O8nqQ0HIKNxc2UuRBOZ5QRQhosS9_2zd0I9sCdE5OL6YWarYLb9-1_hDqEZkve5drvTTUx6fcgP3_mn10RKDg18mxbHL1dGHNTm3ZnfeTEw6XBndBocLs_Ytb8E_du_PozoKkEKDktVb98YTdgF-J3mhJTt_KBPNTkwSaFSzH6RDMq38LQaF-SKDcv2qzdzj8L6edUHNWZxf4UvqFLlEwVcmXjkh1XWmNQ-rvgc4oK7NGPuWQThkozrIsjlgKsG8ueFiATUx7I9SuRRGiOl4Vz6KfMUoCkeKLFfLXNRdVSP1C3KNtOOZWdlIJBye7pz-9VydB3DzkWVtsfAA`
+
+	t.Run("invalid jwks", func(t *testing.T) {
+		verifier, err := jwks.NewVerifier("invalid jwks")
+		if err == nil {
+			t.Error("expected error, got nil")
+		}
+		if verifier != nil {
+			t.Errorf("expected nil verifier, got %v", verifier)
+		}
+	})
+
+	t.Run("valid jwks and invalid token (expired)", func(t *testing.T) {
+		verifier, err := jwks.NewVerifier(rawJWKS)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if verifier == nil {
+			t.Fatal("expected non-nil verifier, got nil")
+		}
+
+		token, err := verifier.Verify(context.Background(), rawToken)
+		if err == nil {
+			t.Error("expected error, got nil")
+		} else if !strings.Contains(err.Error(), "token is expired") {
+			t.Errorf("expected expiry error, got %v", err)
+		}
+		if token != nil {
+			t.Errorf("expected nil token, got %v", token)
+		}
+	})
+
+	t.Run("valid jwks and token (because expiry is skipped)", func(t *testing.T) {
+		verifier, err := jwks.NewVerifier(rawJWKS, func(c *oidc.Config) { c.SkipExpiryCheck = true })
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if verifier == nil {
+			t.Fatal("expected non-nil verifier, got nil")
+		}
+
+		token, err := verifier.Verify(context.Background(), rawToken)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if token == nil {
+			t.Fatal("expected non-nil token, got nil")
+		}
+
+		if token.Subject != "system:serviceaccount:default:default" {
+			t.Errorf("expected subject 'system:serviceaccount:default:default', got %s", token.Subject)
+		}
+	})
+}

pkg/octosts/octosts.go

@@ -31,6 +31,7 @@ import (
 	apiauth "chainguard.dev/sdk/auth"
 	pboidc "chainguard.dev/sdk/proto/platform/oidc/v1"
 	"github.com/chainguard-dev/clog"
+	"github.com/octo-sts/app/pkg/jwks"
 	"github.com/octo-sts/app/pkg/provider"
 )
 
@@ -57,10 +58,11 @@ var (
 type sts struct {
 	pboidc.UnimplementedSecurityTokenServiceServer
 
-	atr      *ghinstallation.AppsTransport
-	ceclient cloudevents.Client
-	domain   string
-	metrics  bool
+	atr            *ghinstallation.AppsTransport
+	ceclient       cloudevents.Client
+	domain         string
+	metrics        bool
+	jwksConfigOpts []jwks.ConfigOption
 }
 
 type cacheTrustPolicyKey struct {
@@ -107,22 +109,41 @@ func (s *sts) Exchange(ctx context.Context, request *pboidc.ExchangeRequest) (_
 	}
 	bearer := strings.TrimPrefix(auth[0], "Bearer ")
 
-	// Validate the Bearer token.
-	issuer, err := apiauth.ExtractIssuer(bearer)
+	e.InstallationID, e.TrustPolicy, err = s.lookupInstallAndTrustPolicy(ctx, request.Scope, request.Identity)
 	if err != nil {
-		return nil, status.Errorf(codes.InvalidArgument, "invalid bearer token: %v", err)
+		return nil, err
 	}
+	clog.FromContext(ctx).Infof("trust policy: %#v", e.TrustPolicy)
 
-	// Fetch the provider from the cache or create a new one and add to the cache
-	p, err := provider.Get(ctx, issuer)
-	if err != nil {
-		return nil, status.Errorf(codes.InvalidArgument, "unable to fetch or create the provider: %v", err)
+	var verifier *oidc.IDTokenVerifier
+
+	// If a JWKS is set on the trust policy, we need to use it to validate the
+	// incoming token. This is for supporting OIDC discovery endpoints that are
+	// not reachable from the Internet, such as air-gapped environments.
+	if e.TrustPolicy.JWKS != "" {
+		var err error
+		verifier, err = jwks.NewVerifier(e.TrustPolicy.JWKS, s.jwksConfigOpts...)
+		if err != nil {
+			return nil, status.Errorf(codes.InvalidArgument, "failed to parse JWKS: %v", err)
+		}
+	} else {
+		// Validate the Bearer token.
+		issuer, err := apiauth.ExtractIssuer(bearer)
+		if err != nil {
+			return nil, status.Errorf(codes.InvalidArgument, "invalid bearer token: %v", err)
+		}
+
+		// Fetch the provider from the cache or create a new one and add to the cache
+		p, err := provider.Get(ctx, issuer)
+		if err != nil {
+			return nil, status.Errorf(codes.InvalidArgument, "unable to fetch or create the provider: %v", err)
+		}
+		verifier = p.Verifier(&oidc.Config{
+			// The audience is verified later on by the trust policy.
+			SkipClientIDCheck: true,
+		})
 	}
 
-	verifier := p.Verifier(&oidc.Config{
-		// The audience is verified later on by the trust policy.
-		SkipClientIDCheck: true,
-	})
 	tok, err := verifier.Verify(ctx, bearer)
 	if err != nil {
 		return nil, status.Errorf(codes.Unauthenticated, "unable to validate token: %v", err)
@@ -134,12 +155,6 @@ func (s *sts) Exchange(ctx context.Context, request *pboidc.ExchangeRequest) (_
 		Subject: tok.Subject,
 	}
 
-	e.InstallationID, e.TrustPolicy, err = s.lookupInstallAndTrustPolicy(ctx, request.Scope, request.Identity)
-	if err != nil {
-		return nil, err
-	}
-	clog.FromContext(ctx).Infof("trust policy: %#v", e.TrustPolicy)
-
 	// Check the token against the federation rules.
 	e.Actor, err = e.TrustPolicy.CheckToken(tok, s.domain)
 	if err != nil {

pkg/octosts/octosts_test.go

@@ -37,6 +37,7 @@ import (
 	"github.com/google/go-github/v69/github"
 	"google.golang.org/grpc/metadata"
 
+	"github.com/octo-sts/app/pkg/jwks"
 	"github.com/octo-sts/app/pkg/provider"
 )
 
@@ -121,17 +122,26 @@ func TestExchange(t *testing.T) {
 	provider.AddTestKeySetVerifier(t, iss, &oidc.StaticKeySet{
 		PublicKeys: []crypto.PublicKey{pk.Public()},
 	})
-	ctx = metadata.NewIncomingContext(ctx, metadata.MD{"authorization": []string{"Bearer " + token}})
+	signedTokenCtx := metadata.NewIncomingContext(ctx, metadata.MD{"authorization": []string{"Bearer " + token}})
+
+	// This is an expired token.
+	const jwksToken = `eyJhbGciOiJSUzI1NiIsImtpZCI6IkxIVkdQOGtxek4xTXVLUk1Uc3JvSWNSLTdoZGljWFdkcGFxdUVXY0FoOVEifQ.eyJhdWQiOlsiaHR0cHM6Ly9rdWJlcm5ldGVzLmRlZmF1bHQuc3ZjLmNsdXN0ZXIubG9jYWwiXSwiZXhwIjoxNzQ0NzYzODI0LCJpYXQiOjE3NDQ3NjMyMjQsImlzcyI6Imh0dHBzOi8va3ViZXJuZXRlcy5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsIiwianRpIjoiODU2YTA2OWItZmUyZi00OTI4LTgzNGMtOTUwNGYwMmU4MzQzIiwia3ViZXJuZXRlcy5pbyI6eyJuYW1lc3BhY2UiOiJkZWZhdWx0Iiwic2VydmljZWFjY291bnQiOnsibmFtZSI6ImRlZmF1bHQiLCJ1aWQiOiIxYjg3OTNjZC02YTYyLTQ2ZmYtOWNmNy1lN2ZlOWU3Y2RiODYifX0sIm5iZiI6MTc0NDc2MzIyNCwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OmRlZmF1bHQ6ZGVmYXVsdCJ9.NF8UW6O8nqQ0HIKNxc2UuRBOZ5QRQhosS9_2zd0I9sCdE5OL6YWarYLb9-1_hDqEZkve5drvTTUx6fcgP3_mn10RKDg18mxbHL1dGHNTm3ZnfeTEw6XBndBocLs_Ytb8E_du_PozoKkEKDktVb98YTdgF-J3mhJTt_KBPNTkwSaFSzH6RDMq38LQaF-SKDcv2qzdzj8L6edUHNWZxf4UvqFLlEwVcmXjkh1XWmNQ-rvgc4oK7NGPuWQThkozrIsjlgKsG8ueFiATUx7I9SuRRGiOl4Vz6KfMUoCkeKLFfLXNRdVSP1C3KNtOOZWdlIJBye7pz-9VydB3DzkWVtsfAA`
+	jwksTokenCtx := metadata.NewIncomingContext(ctx, metadata.MD{"authorization": []string{"Bearer " + jwksToken}})
 
 	sts := &sts{
 		atr: atr,
+		jwksConfigOpts: []jwks.ConfigOption{
+			func(c *oidc.Config) { c.SkipExpiryCheck = true },
+		},
 	}
 	for _, tc := range []struct {
+		ctx  context.Context
 		name string
 		req  *v1.ExchangeRequest
 		want *github.InstallationTokenOptions
 	}{
 		{
+			ctx:  signedTokenCtx,
 			name: "repo",
 			req: &v1.ExchangeRequest{
 				Identity: "foo",
@@ -145,6 +155,7 @@ func TestExchange(t *testing.T) {
 			},
 		},
 		{
+			ctx:  signedTokenCtx,
 			name: "org",
 			req: &v1.ExchangeRequest{
 				Identity: "foo",
@@ -156,9 +167,23 @@ func TestExchange(t *testing.T) {
 				},
 			},
 		},
+		{
+			ctx:  jwksTokenCtx,
+			name: "repo with jwks",
+			req: &v1.ExchangeRequest{
+				Identity: "jwks",
+				Scope:    "org/repo",
+			},
+			want: &github.InstallationTokenOptions{
+				Repositories: []string{"repo"},
+				Permissions: &github.InstallationPermissions{
+					PullRequests: github.Ptr("write"),
+				},
+			},
+		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
-			tok, err := sts.Exchange(ctx, tc.req)
+			tok, err := sts.Exchange(tc.ctx, tc.req)
 			if err != nil {
 				t.Fatalf("Exchange failed: %v", err)
 			}

pkg/octosts/testdata/org/repo/jwks.sts.yaml

@@ -0,0 +1,22 @@
+# Copyright 2024 Chainguard, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+issuer: https://kubernetes.default.svc.cluster.local
+audience: https://kubernetes.default.svc.cluster.local
+subject: system:serviceaccount:default:default
+jwks: |
+  {
+    "keys": [
+      {
+        "use": "sig",
+        "kty": "RSA",
+        "kid": "LHVGP8kqzN1MuKRMTsroIcR-7hdicXWdpaquEWcAh9Q",
+        "alg": "RS256",
+        "n": "s5XuFpodwhj6my_gTUHDKbHmQIx-3Tf40OduMZRWlU6_B_nSdjX01kS1UQSGw_G5eVQARooI-tY1vj3bBwn4dEEFa2TlnNnAJca0hj2Izef8A8Uw-mT0fgGI4Hs3xS84Mn_WXNlKXEiPLiFyOGNr0GQBKZDyTps8JUlvnwuWCv1gkzudUHa8B0i8ITSEUclK9_LqZj4zXUAN0Wj_4DVfI_PQ0IHci9K5Q9bgCV0j1EvTsyrwGyLFwyhktUmNhjREAfgYmxvbIRhPSP4YuO2Et1KM7YmjA75cQ9oE3i-QLrOZDripyMRop5RmWttQCEdEWLQWPzBd7aZ5CLbmZuIlIQ",
+        "e": "AQAB"
+      }
+    ]
+  }
+
+permissions:
+  pull_requests: write

pkg/octosts/trust_policy.go

@@ -20,6 +20,8 @@ type TrustPolicy struct {
 	IssuerPattern string         `json:"issuer_pattern,omitempty"`
 	issuerPattern *regexp.Regexp `json:"-"`
 
+	JWKS string `json:"jwks,omitempty"`
+
 	Subject        string         `json:"subject,omitempty"`
 	SubjectPattern string         `json:"subject_pattern,omitempty"`
 	subjectPattern *regexp.Regexp `json:"-"`