Merge pull request #21 from spiffe/hint

Add hint support

Author: kfox1111

.github/workflows/test.yaml

@@ -25,4 +25,17 @@ jobs:
         uses: golangci/golangci-lint-action@v7
         with:
           version: v2.12.2
-          skip-go-installation: true
+
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: 'go.mod'
+      - name: Test
+        run: go test ./...

README.md

@@ -8,9 +8,45 @@ A Kubernetes exec auth plugin using the SPIFFE Workload API to get JWTs for auth
 ## Building
 
 ```
-go build .
+go build -o k8s-spiffe-workload-jwt-exec-auth ./cmd
 ```
 
+## Configuration
+
+The plugin is configured entirely through environment variables, set via the `env:` list of the
+kubeconfig `exec` block:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SPIFFE_ENDPOINT_SOCKET` | `unix:///tmp/spire-agent/public/api.sock` | Address of the SPIFFE Workload API socket. |
+| `SPIFFE_JWT_AUDIENCE` | `k8s` | Audience requested for the JWT-SVID. Must match an entry in the API server's `AuthenticationConfiguration`. |
+| `SPIFFE_JWT_HINT` | *(unset)* | Selects which JWT-SVID to use by hint, when the Workload API returns more than one. See below. |
+| `EXEC_CREDENTIAL_VERSION` | `v1` | The `client.authentication.k8s.io` version emitted. Use `v1beta1` for older clients. Must match the `apiVersion` in the `exec` block. |
+
+There is also one flag, passed via `args:` rather than `env:`:
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-timeout` | `0` | Max time to wait for the JWT-SVID from the Workload API socket, e.g. `-timeout=5s`. `0` waits forever. |
+
+### Selecting an identity with `SPIFFE_JWT_HINT`
+
+Hints are operator-set strings on SPIRE registration entries, used "to provide guidance on how this
+identity should be used by a workload when more than one SVID is returned". If the Workload API
+returns several JWT-SVIDs — for example a SPIRE HA broker fronting multiple entry-scoped SVIDs — then
+which one comes first is arbitrary, and the plugin may authenticate to the cluster as an identity you
+did not intend.
+
+Set `SPIFFE_JWT_HINT` to pin a specific one:
+
+- **Unset or empty**: use the first JWT-SVID returned. This is the original behavior.
+- **Set and matched**: use the JWT-SVID with that hint.
+- **Set and unmatched**: exit non-zero with an error on stderr listing the hints that *were*
+  available, rather than silently authenticating as a different identity.
+
+Matching is exact — no case folding or whitespace trimming. SPIRE keeps only the first SVID for each
+non-empty hint, so hints are effectively unique.
+
 ## Usage
 
 ### Setup the Kubernetes cluster auth
@@ -50,6 +86,10 @@ Remove the "user" block from the "users" section and replace it with:
       #    value: "unix:///var/run/spire/agent/sockets/main/public/api.sock"
       #  - name: SPIFFE_JWT_AUDIENCE
       #    value: "k8s-one"
+      #  - name: SPIFFE_JWT_HINT
+      #    value: "k8s-one"
+      #args:
+      #  - "-timeout=5s"
 ```
 
 ### Kubelet kubeconfig file
@@ -68,4 +108,8 @@ Modify `/etc/kubernetes/kubelet.conf`, and remove `client-certificate` and `clie
       #    value: "unix:///var/run/spire/agent/sockets/main/public/api.sock"
       #  - name: SPIFFE_JWT_AUDIENCE
       #    value: "k8s-one"
+      #  - name: SPIFFE_JWT_HINT
+      #    value: "k8s-one"
+      #args:
+      #  - "-timeout=5s"
 ```

cmd/main.go

@@ -2,10 +2,12 @@ package main
 
 import (
 	"context"
+	"errors"
 	"flag"
 	"fmt"
 	"log"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/spiffe/go-spiffe/v2/svid/jwtsvid"
@@ -15,6 +17,12 @@ import (
 )
 
 func main() {
+	// client-go inherits this process's stderr and reports only "failed with exit
+	// code N", so anything logged here is the operator's entire diagnostic. Drop
+	// log's timestamp and name the plugin instead.
+	log.SetFlags(0)
+	log.SetPrefix("k8s-spiffe-workload-jwt-exec-auth: ")
+
 	timeout := flag.Duration("timeout", 0,
 		"max time to wait for the JWT-SVID from the workload API socket (e.g. 5s). 0 = wait forever")
 	flag.Parse()
@@ -29,6 +37,12 @@ func main() {
 		audience = "k8s"
 	}
 
+	// Unset or empty means "no preference": use the first JWT-SVID the Workload API
+	// returns, which is what this plugin has always done. Set this when the Workload
+	// API returns several JWT-SVIDs (for example a SPIRE HA broker fronting multiple
+	// entry-scoped SVIDs) to pin a specific one.
+	hint := os.Getenv("SPIFFE_JWT_HINT")
+
 	execCredentialVersion, ok := os.LookupEnv("EXEC_CREDENTIAL_VERSION")
 	if !ok {
 		execCredentialVersion = "v1"
@@ -49,12 +63,19 @@ func main() {
 		log.Fatal(err)
 
 	}
-	svid, err := jwtSource.FetchJWTSVID(ctx, jwtsvid.Params{
+	svids, err := jwtSource.FetchJWTSVIDs(ctx, jwtsvid.Params{
 		Audience: audience,
 	})
 	if err != nil {
 		log.Fatal(err)
 	}
+	// Everything that can fail must fail before the first write to stdout below:
+	// client-go decodes stdout as an ExecCredential, so a half-written document
+	// would surface as a confusing decode error instead of the real problem.
+	svid, err := selectSVIDByHint(svids, hint)
+	if err != nil {
+		log.Fatal(err)
+	}
 
 	now := time.Now()
 	expiry, err := metav1.NewTime(credentialExpiration(now, svid.Expiry)).MarshalJSON()
@@ -73,3 +94,27 @@ func main() {
 func credentialExpiration(now, jwtExpiry time.Time) time.Time {
 	return now.Add(jwtExpiry.Sub(now) / 2)
 }
+
+// selectSVIDByHint returns the JWT-SVID whose hint matches the requested hint. An
+// empty hint means no preference, in which case the first JWT-SVID is returned. If
+// a hint is requested but nothing matches, an error naming the available hints is
+// returned rather than a JWT-SVID for a different identity.
+func selectSVIDByHint(svids []*jwtsvid.SVID, hint string) (*jwtsvid.SVID, error) {
+	if len(svids) == 0 {
+		return nil, errors.New("the workload API returned no JWT-SVIDs")
+	}
+	if hint == "" {
+		return svids[0], nil
+	}
+
+	available := make([]string, 0, len(svids))
+	for _, svid := range svids {
+		if svid.Hint == hint {
+			return svid, nil
+		}
+		available = append(available, fmt.Sprintf("%q", svid.Hint))
+	}
+
+	return nil, fmt.Errorf("no JWT-SVID with hint %q (SPIFFE_JWT_HINT); available hints: %s",
+		hint, strings.Join(available, ", "))
+}

cmd/main_test.go

@@ -1,8 +1,11 @@
 package main
 
 import (
+	"strings"
 	"testing"
 	"time"
+
+	"github.com/spiffe/go-spiffe/v2/svid/jwtsvid"
 )
 
 func TestCredentialExpirationIsHalfwayToJWTExpiry(t *testing.T) {
@@ -14,3 +17,111 @@ func TestCredentialExpirationIsHalfwayToJWTExpiry(t *testing.T) {
 		t.Fatalf("credentialExpiration() = %s, want %s", got, want)
 	}
 }
+
+func TestSelectSVIDByHint(t *testing.T) {
+	// Named variables rather than a constructor helper, so the cases below can
+	// assert which of two indistinguishable SVIDs was picked by pointer identity.
+	one := &jwtsvid.SVID{Hint: "one"}
+	two := &jwtsvid.SVID{Hint: "two"}
+	three := &jwtsvid.SVID{Hint: "three"}
+	upperOne := &jwtsvid.SVID{Hint: "One"}
+	dupFirst := &jwtsvid.SVID{Hint: "dup"}
+	dupSecond := &jwtsvid.SVID{Hint: "dup"}
+	blankFirst := &jwtsvid.SVID{}
+	blankSecond := &jwtsvid.SVID{}
+
+	tests := []struct {
+		name  string
+		svids []*jwtsvid.SVID
+		hint  string
+		want  *jwtsvid.SVID
+		// wantErrs lists substrings the error must contain. Empty means expect success.
+		wantErrs []string
+	}{
+		{
+			name:  "no hint returns the only SVID",
+			svids: []*jwtsvid.SVID{blankFirst},
+			want:  blankFirst,
+		},
+		{
+			name:  "no hint returns the first of many",
+			svids: []*jwtsvid.SVID{one, two},
+			want:  one,
+		},
+		{
+			name:  "hint matches the first SVID",
+			svids: []*jwtsvid.SVID{one, two},
+			hint:  "one",
+			want:  one,
+		},
+		{
+			name:  "hint matches a later SVID",
+			svids: []*jwtsvid.SVID{one, two, three},
+			hint:  "three",
+			want:  three,
+		},
+		{
+			name:  "duplicate hints return the first",
+			svids: []*jwtsvid.SVID{dupFirst, dupSecond},
+			hint:  "dup",
+			want:  dupFirst,
+		},
+		{
+			name:     "unmatched hint errors and lists the available hints",
+			svids:    []*jwtsvid.SVID{one, two},
+			hint:     "three",
+			wantErrs: []string{`"three"`, `"one"`, `"two"`, "SPIFFE_JWT_HINT"},
+		},
+		{
+			name:     "unmatched hint lists unhinted SVIDs as empty",
+			svids:    []*jwtsvid.SVID{blankFirst, blankSecond},
+			hint:     "one",
+			wantErrs: []string{`"one"`, `"", ""`},
+		},
+		{
+			name:     "hint matching is case sensitive",
+			svids:    []*jwtsvid.SVID{upperOne},
+			hint:     "one",
+			wantErrs: []string{`"one"`, `"One"`},
+		},
+		{
+			name:     "no SVIDs errors",
+			svids:    nil,
+			wantErrs: []string{"no JWT-SVIDs"},
+		},
+		{
+			name:     "no SVIDs errors when a hint is requested",
+			svids:    []*jwtsvid.SVID{},
+			hint:     "one",
+			wantErrs: []string{"no JWT-SVIDs"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := selectSVIDByHint(tt.svids, tt.hint)
+
+			if len(tt.wantErrs) == 0 {
+				if err != nil {
+					t.Fatalf("selectSVIDByHint() returned unexpected error: %v", err)
+				}
+				if got != tt.want {
+					t.Fatalf("selectSVIDByHint() = %+v, want %+v", got, tt.want)
+				}
+				return
+			}
+
+			if err == nil {
+				t.Fatalf("selectSVIDByHint() = %+v, want an error", got)
+			}
+			if got != nil {
+				t.Errorf("selectSVIDByHint() returned %+v alongside an error, want nil", got)
+			}
+			for _, want := range tt.wantErrs {
+				if !strings.Contains(err.Error(), want) {
+					t.Errorf("selectSVIDByHint() error = %q, want it to contain %s", err, want)
+				}
+			}
+		})
+	}
+}