Skip to content

Agent Mesh

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

Antonio Ojea4e06c27918fd
diff --git a/api/network.go b/api/network.go
index 40a8ac99..f073f5cb 100644
--- a/api/network.go
+++ b/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
diff --git a/cmd/sam-control-plane/main.go b/cmd/sam-control-plane/main.go
index 00aa67e2..5ab2e1d5 100644
--- a/cmd/sam-control-plane/main.go
+++ b/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)")
diff --git a/internal/controlplane/config.go b/internal/controlplane/config.go
index fd7ef22b..b090a47a 100644
--- a/internal/controlplane/config.go
+++ b/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.
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index ead125fa..8a155cc9 100644
--- a/internal/controlplane/server.go
+++ b/internal/controlplane/server.go
@@ -552,12 +552,21 @@ 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)
@@ -565,8 +574,6 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
return
}
- // Session TTL is 90 days for OIDC interactive enrollment
- sessionExpiresAt := time.Now().Add(api.OIDCSessionTTL)
primaryRole := req.RequestedRole
claimsBytes, err := json.Marshal(claims)
diff --git a/internal/controlplane/server_test.go b/internal/controlplane/server_test.go
index 9bea6ce2..48d58a15 100644
--- a/internal/controlplane/server_test.go
+++ b/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
diff --git a/site/content/docs/user/control-plane-configuration.md b/site/content/docs/user/control-plane-configuration.md
index e103c2c1..3792bd4c 100644
--- a/site/content/docs/user/control-plane-configuration.md
+++ b/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. |