controlplane: make the OIDC re-auth cadence an operator decision

One interactive OIDC login produced a session refreshable for a
hardcoded 90 days: refresh needs only the previous biscuit and the node
key's challenge signature, never the issuer, so an identity disabled at
the provider kept its seat until the constant said otherwise. Since
enrollment binding checks (fc9636b) and identity bans (8ae3063), the
mesh has its own revocation levers, but how long the issuer's word is
trusted without renewal is a policy trade-off, not a constant: shorter
keeps the provider authoritative for offboarding, longer keeps headless
nodes unattended.

Add --oidc-session-ttl (default unchanged, 90 days) and cap the
enrollment biscuit at the session boundary, as refresh already did.
Pinned by TestOIDCSessionTTLIsConfigurable: the record and first
biscuit honor the configured TTL, and a lapsed session refuses a
correctly signed refresh with 401.

Part of GHSA-cgmg-9xf6-rrgw (claim: 1h OIDC token yields a 90-day mesh
credential).

Author: aojea

api/network.go

@@ -65,9 +65,10 @@ const (
 	// This is verified locally by each peer on every connection.
 	BiscuitTokenTTL = 24 * time.Hour
 
-	// OIDCSessionTTL is the maximum database-enforced lifespan of a node's OIDC
+	// OIDCSessionTTL is the default database-enforced lifespan of a node's OIDC
 	// interactive enrollment session (90 days). After this period, the node
 	// must re-authenticate with the OIDC provider to establish a new session.
+	// Operators tune the cadence with the control plane's --oidc-session-ttl.
 	OIDCSessionTTL = 90 * 24 * time.Hour
 
 	// TokenRefreshCheckInterval is the frequency at which the node daemon and router check

cmd/sam-control-plane/main.go

@@ -42,6 +42,7 @@ var (
 	keyGracePeriod        time.Duration
 	leaseDuration         time.Duration
 	biscuitTTL            time.Duration
+	oidcSessionTTL        time.Duration
 	adminTokenPath        string
 	insecureSkipTLSVerify bool
 	logLevel              string
@@ -122,6 +123,7 @@ func main() {
 				InsecureSkipTLSVerify: insecureSkipTLSVerify,
 				BiscuitTimeout:        10 * time.Second,
 				BiscuitTTL:            biscuitTTL,
+				OIDCSessionTTL:        oidcSessionTTL,
 				AdminToken:            adminToken,
 				AutoApproveEnrollment: autoApproveEnrollment,
 			}
@@ -156,6 +158,7 @@ func main() {
 	rootCmd.Flags().DurationVar(&keyGracePeriod, "key-grace-period", 1*time.Hour, "Key grace period for rotated keys.")
 	rootCmd.Flags().DurationVar(&leaseDuration, "lease-duration", 15*time.Minute, "Router lease registration TTL.")
 	rootCmd.Flags().DurationVar(&biscuitTTL, "biscuit-ttl", api.BiscuitTokenTTL, "Lifespan minted into every issued Biscuit's expiration fact. Capped to the OIDC token's own expiry when shorter.")
+	rootCmd.Flags().DurationVar(&oidcSessionTTL, "oidc-session-ttl", api.OIDCSessionTTL, "How long an OIDC enrollment stays refreshable before the identity must re-authenticate with the OIDC provider. Shorter values keep the provider authoritative for offboarding at the cost of more frequent interactive re-enrollment.")
 	rootCmd.Flags().StringVar(&adminTokenPath, "admin-token-path", "", "Path to file containing the token for authenticating policy REST API requests (or env SAM_ADMIN_TOKEN)")
 	rootCmd.Flags().BoolVar(&insecureSkipTLSVerify, "insecure-skip-tls-verify", false, "Skip TLS verification for OIDC providers")
 	rootCmd.Flags().StringVar(&logLevel, "log-level", "info", "Log level (debug, info, warn, error)")

internal/controlplane/config.go

@@ -35,6 +35,7 @@ type Options struct {
 	InsecureSkipTLSVerify bool
 	BiscuitTimeout        time.Duration
 	BiscuitTTL            time.Duration // Lifespan minted into every issued Biscuit's expiration() fact; defaults to api.BiscuitTokenTTL
+	OIDCSessionTTL        time.Duration // How long an OIDC enrollment stays refreshable before the identity must re-authenticate interactively; defaults to api.OIDCSessionTTL
 	AdminToken            string        // Optional: administrative bearer token for protecting policy and enrollment queue REST APIs
 	AutoApproveEnrollment bool          // If true, valid bootstrap token enrollment requests are immediately approved without administrative manual gate
 }
@@ -60,6 +61,9 @@ func (o *Options) Default() {
 	if o.BiscuitTTL <= 0 {
 		o.BiscuitTTL = api.BiscuitTokenTTL
 	}
+	if o.OIDCSessionTTL <= 0 {
+		o.OIDCSessionTTL = api.OIDCSessionTTL
+	}
 }
 
 // Validate ensures options are valid.

internal/controlplane/server.go

@@ -552,21 +552,28 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	// The session bounds how long refresh works without the identity proving
+	// itself to the issuer again, so its length is the operator's re-auth
+	// cadence decision (--oidc-session-ttl), not a constant.
+	sessionExpiresAt := time.Now().Add(s.config.OIDCSessionTTL)
+
 	// Mint token. A biscuit must never outlive the OIDC token that vouched
-	// for it, so its expiration is capped at whichever comes first.
+	// for it, nor the session it belongs to; its expiration is capped at
+	// whichever comes first.
 	biscuitExpiry := time.Now().Add(s.config.BiscuitTTL)
 	if token.Expiry.Before(biscuitExpiry) {
 		biscuitExpiry = token.Expiry
 	}
+	if sessionExpiresAt.Before(biscuitExpiry) {
+		biscuitExpiry = sessionExpiresAt
+	}
 	biscuitData, _, err := identity.MintBiscuitToken(privKey, claims, token, pID, biscuitExpiry, finalRoles, policyRoles, req.Labels)
 	if err != nil {
 		logger.Errorw("Biscuit minting failed", "peer_id", req.PeerId, "error", err)
 		http.Error(w, "Failed to mint biscuit: "+err.Error(), http.StatusForbidden)
 		return
 	}
 
-	// Session TTL is 90 days for OIDC interactive enrollment
-	sessionExpiresAt := time.Now().Add(api.OIDCSessionTTL)
 	primaryRole := req.RequestedRole
 
 	claimsBytes, err := json.Marshal(claims)

internal/controlplane/server_test.go

@@ -2207,6 +2207,100 @@ func TestAuthDenialPaths(t *testing.T) {
 	})
 }
 
+// TestOIDCSessionTTLIsConfigurable pins the GHSA-cgmg-9xf6-rrgw session-length
+// answer: how long one OIDC login stays refreshable is the operator's
+// --oidc-session-ttl decision. A lapsed session refuses refresh (forcing
+// interactive re-auth) and the first biscuit never outlives the session.
+func TestOIDCSessionTTLIsConfigurable(t *testing.T) {
+	issuer, mintToken := startCustomMockOIDC(t)
+	const sessionTTL = 2 * time.Second
+	srv, store, baseURL := setupTestServer(t, issuer, func(o *Options) {
+		o.OIDCSessionTTL = sessionTTL
+	})
+	defer func() {
+		_ = srv.Close()
+		_ = store.Close()
+	}()
+
+	ctx := context.Background()
+	client := &http.Client{Timeout: 5 * time.Second}
+
+	if err := store.SaveMeshPolicy(ctx, nil, []*api.PolicyBinding{
+		{Role: api.RoleNode, Members: []string{api.SystemAuthenticated}},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	privNode, pubNode, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	nodePeer, err := peer.IDFromPrivateKey(privNode)
+	if err != nil {
+		t.Fatal(err)
+	}
+	pubBytes, _ := crypto.MarshalPublicKey(pubNode)
+	enrolledAt := time.Now()
+	reqData, _ := proto.Marshal(&api.EnrollRequest{
+		Jwt:           mintToken(map[string]interface{}{"sub": "short-session"}),
+		PeerId:        nodePeer.String(),
+		PublicKey:     pubBytes,
+		RequestedRole: api.RoleNode,
+	})
+	resp, err := client.Post(baseURL+"/register", "application/x-protobuf", bytes.NewReader(reqData))
+	if err != nil {
+		t.Fatalf("/register failed: %v", err)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("/register status %s (body: %s)", resp.Status, body)
+	}
+	var enrollResp api.EnrollResponse
+	if err := proto.Unmarshal(body, &enrollResp); err != nil {
+		t.Fatal(err)
+	}
+
+	// The configured TTL, not the 90-day default, bounds the session record
+	// and the first biscuit alike.
+	nodeRecord, err := store.GetNode(ctx, nodePeer.String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if skew := nodeRecord.ExpiresAt.Sub(enrolledAt.Add(sessionTTL)); skew < -2*time.Second || skew > 2*time.Second {
+		t.Errorf("session ExpiresAt is %v, want ~%v", nodeRecord.ExpiresAt, enrolledAt.Add(sessionTTL))
+	}
+	if reported := time.Unix(enrollResp.Expiration, 0); reported.After(nodeRecord.ExpiresAt.Add(2 * time.Second)) {
+		t.Errorf("biscuit expiration %v outlives the session %v", reported, nodeRecord.ExpiresAt)
+	}
+
+	// Once the session lapses, a correctly signed refresh is refused: the
+	// identity has to go back to the OIDC provider.
+	time.Sleep(sessionTTL + 500*time.Millisecond)
+
+	timestamp := time.Now().UnixMilli()
+	challengeSig, err := privNode.Sign(api.RefreshChallenge(nodePeer.String(), timestamp))
+	if err != nil {
+		t.Fatal(err)
+	}
+	refreshData, _ := proto.Marshal(&api.TokenRefreshRequest{
+		ChallengeSignature: challengeSig,
+		Timestamp:          timestamp,
+	})
+	req, _ := http.NewRequest("POST", baseURL+"/refresh", bytes.NewReader(refreshData))
+	req.Header.Set("Authorization", "Bearer "+base64.StdEncoding.EncodeToString(enrollResp.BiscuitToken))
+	req.Header.Set("Content-Type", "application/x-protobuf")
+	resp, err = client.Do(req)
+	if err != nil {
+		t.Fatalf("refresh failed: %v", err)
+	}
+	body, _ = io.ReadAll(resp.Body)
+	_ = resp.Body.Close()
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("refresh after session expiry: got %s (body: %s), want 401", resp.Status, body)
+	}
+}
+
 // TestBanSurvivesKeypairRegeneration pins the fix for the GHSA-cgmg-9xf6-rrgw
 // ban-bypass claim: bans were keyed only on peer_id, which the node itself
 // mints, so a banned operator regenerated a keypair and re-enrolled. Revoking

site/content/docs/user/control-plane-configuration.md

@@ -23,6 +23,8 @@ The Control Plane is responsible for bridging user identities from trusted OIDC
 | `--allowed-audiences` | *None* | `sam-mesh-audience` | Comma-separated list of allowed JWT audiences. |
 | `--admin-token-path` (or env `SAM_ADMIN_TOKEN`) | *None* | *None* | File containing the secret token required in the HTTP Header `Authorization: Bearer <token>` for admin operations. |
 | `--insecure-skip-tls-verify` | *None* | `false` | Set to `true` to skip certificate validation for development/testing OIDC providers. |
+| `--biscuit-ttl` | *None* | `24h` | Lifespan minted into every issued Biscuit token. Capped to the OIDC token's own expiry when shorter. |
+| `--oidc-session-ttl` | *None* | `2160h` (90 days) | How long an OIDC enrollment stays refreshable before the identity must re-authenticate with the OIDC provider. Shorter values keep the provider authoritative for offboarding, at the cost of more frequent interactive re-enrollment. |
 | `--key-rotation-interval` | *None* | `24h` | Key rotation interval (e.g. `24h`). `0s` disables rotation. |
 | `--key-grace-period` | *None* | `1h` | Key grace period for rotated keys. |
 | `--lease-duration` | *None* | `15m` | Router lease registration TTL. |