Skip to content

Agent Mesh

controlplane: require an explicit policy binding to enroll, on every path

Antonio Ojea95685207bebd
diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
index 7f8669ab..a43dc848 100644
--- a/.github/workflows/deploy.yaml
+++ b/.github/workflows/deploy.yaml
@@ -404,6 +404,7 @@ jobs:
"bindings": [
{"role": "sam-canary", "members": ["user:system:serviceaccount:sam-canary-'"${ENV_NAME}"':sam-node-sa", "user:system:serviceaccount:sam-canary-'"${ENV_NAME}"':sam-box-sa"]},
{"role": "sam:role:router", "members": ["group:routers", "user:system:serviceaccount:'"${NAMESPACE}"':sam-router-sa"]},
+ {"role": "sam:role:node", "members": ["sam:system:authenticated"]},
{"role": "public-mesh", "members": ["sam:system:authenticated"]}
]
}' \
diff --git a/charts/sam-mesh/templates/bootstrap-job.yaml b/charts/sam-mesh/templates/bootstrap-job.yaml
index 88dc086b..a6247548 100644
--- a/charts/sam-mesh/templates/bootstrap-job.yaml
+++ b/charts/sam-mesh/templates/bootstrap-job.yaml
@@ -107,8 +107,10 @@ spec:
{{- $bindings = list
(dict "role" "sam:role:router" "members" (list "group:routers" $defaultRouterSA))
(dict "role" "sam:role:sambox" "members" (list (printf "user:system:serviceaccount:%s:sam-box-sa" .Release.Namespace)))
- (dict "role" "sam:role:node" "members" (list "group:data-scientist" "group:users"))
-}}
+ {{- if .Values.bootstrap.nodeMembers -}}
+ {{- $bindings = append $bindings (dict "role" "sam:role:node" "members" .Values.bootstrap.nodeMembers) -}}
+ {{- end -}}
{{- end }}
curl -sf -X POST \
-H "Content-Type: application/json" \
diff --git a/charts/sam-mesh/tests/bootstrap-job_test.yaml b/charts/sam-mesh/tests/bootstrap-job_test.yaml
index d02a98bf..cbdc6e03 100644
--- a/charts/sam-mesh/tests/bootstrap-job_test.yaml
+++ b/charts/sam-mesh/tests/bootstrap-job_test.yaml
@@ -51,6 +51,27 @@ tests:
path: spec.template.spec.containers[0].args[0]
pattern: '"name": "sam:role:node", "allowed_services": \[\]'
+ - it: no identity may enroll as a node by default (fail closed)
+ documentSelector:
+ path: kind
+ value: Job
+ asserts:
+ - notMatchRegex:
+ path: spec.template.spec.containers[0].args[0]
+ pattern: '"role":"sam:role:node"'
+
+ - it: node enrollment is granted to exactly the configured members
+ documentSelector:
+ path: kind
+ value: Job
+ set:
+ bootstrap:
+ nodeMembers: ["user:test-user", "group:eng"]
+ asserts:
+ - matchRegex:
+ path: spec.template.spec.containers[0].args[0]
+ pattern: '\{"members":\["user:test-user","group:eng"\],"role":"sam:role:node"\}'
+
- it: node role grants only the configured services
documentSelector:
path: kind
diff --git a/charts/sam-mesh/values.yaml b/charts/sam-mesh/values.yaml
index ac958cd9..e33754e6 100644
--- a/charts/sam-mesh/values.yaml
+++ b/charts/sam-mesh/values.yaml
@@ -180,6 +180,11 @@ console:
bootstrap:
bindings: []
+ # Identities that may enroll as sam:role:node ("user:<sub>", "group:<name>",
+ # "email:<addr>", or "sam:system:authenticated" for an intentionally open
+ # mesh). Empty means no node can enroll until an operator grants it (fail
+ # closed). Ignored when bindings is set: then you own the whole list.
+ nodeMembers: []
# Services sam:role:node may call, as "type://name" entries (e.g.
# "mcp://calculator"). Any authenticated identity can claim sam:role:node,
# so this list is effectively mesh-wide. Empty means nodes can call nothing
diff --git a/development/kind/run.sh b/development/kind/run.sh
index 9b2d9099..96dc8df3 100755
--- a/development/kind/run.sh
+++ b/development/kind/run.sh
@@ -104,6 +104,7 @@ deploy_chart() {
--set controlPlane.allowedAudiences="${ALLOWED_AUDIENCES//,/\\,}" \
--set controlPlane.insecureSkipTlsVerify=true \
--set 'bootstrap.nodeServices={*}' \
+ --set 'bootstrap.nodeMembers={sam:system:authenticated}' \
--set gateway.enabled=true \
--set gateway.className=cloud-provider-kind \
--set gateway.adminRoute=true \
diff --git a/internal/controlplane/policies_admission_test.go b/internal/controlplane/policies_admission_test.go
index 51cf7332..c9abd84c 100644
--- a/internal/controlplane/policies_admission_test.go
+++ b/internal/controlplane/policies_admission_test.go
@@ -45,6 +45,12 @@ func TestPoliciesRequiresAnAdmissibleNode(t *testing.T) {
ctx := context.Background()
client := &http.Client{Timeout: 5 * time.Second}
+ // Enrollment requires the requested role to resolve from a binding.
+ nodeBindings := []*api.PolicyBinding{{Role: api.RoleNode, Members: []string{"group:users"}}}
+ if err := store.SaveMeshPolicy(ctx, nil, nodeBindings); err != nil {
+ t.Fatalf("failed to seed policy: %v", err)
+ }
+
privNode, _, err := crypto.GenerateKeyPair(crypto.Ed25519, -1)
if err != nil {
t.Fatal(err)
diff --git a/internal/controlplane/server.go b/internal/controlplane/server.go
index 6c36597f..5e86afed 100644
--- a/internal/controlplane/server.go
+++ b/internal/controlplane/server.go
@@ -500,27 +500,21 @@ func (s *Server) HandleRegister(w http.ResponseWriter, r *http.Request) {
}
resolvedRoles := resolveRoles(pID.String(), claims, bindings)
- var hasCapabilityRoles bool
var customAccessRoles []string
resolvedMap := make(map[string]bool)
for _, r := range resolvedRoles {
resolvedMap[r] = true
- if strings.HasPrefix(r, "sam:role:") {
- hasCapabilityRoles = true
- } else if r != req.RequestedRole {
+ if !strings.HasPrefix(r, "sam:role:") && r != req.RequestedRole {
customAccessRoles = append(customAccessRoles, r)
}
}
- isAuthorized := false
- if resolvedMap[req.RequestedRole] {
- isAuthorized = true
- } else if req.RequestedRole == api.RoleNode && !hasCapabilityRoles {
- isAuthorized = true
- }
-
- if !isAuthorized {
- http.Error(w, fmt.Sprintf("requested role %q is not authorized for this identity", req.RequestedRole), http.StatusForbidden)
+ // Enrollment is a policy decision like any other: the requested role must
+ // resolve from an explicit binding. There is deliberately no fallback for
+ // sam:role:node — a mesh that wants open enrollment says so by binding it
+ // to sam:system:authenticated, instead of getting it by omission.
+ if !resolvedMap[req.RequestedRole] {
+ http.Error(w, fmt.Sprintf("requested role %q is not bound to this identity; bind it in mesh policy (to sam:system:authenticated to open enrollment to every authenticated identity)", req.RequestedRole), http.StatusForbidden)
return
}
@@ -743,27 +737,19 @@ func (s *Server) HandleRefresh(w http.ResponseWriter, r *http.Request) {
return
}
resolvedRoles := resolveRoles(pID.String(), claims, bindings)
- var hasCapabilityRoles bool
var customAccessRoles []string
resolvedMap := make(map[string]bool)
for _, r := range resolvedRoles {
resolvedMap[r] = true
- if strings.HasPrefix(r, "sam:role:") {
- hasCapabilityRoles = true
- } else if r != nodeRecord.Role {
+ if !strings.HasPrefix(r, "sam:role:") && r != nodeRecord.Role {
customAccessRoles = append(customAccessRoles, r)
}
}
- isAuthorized := false
- if resolvedMap[nodeRecord.Role] {
- isAuthorized = true
- } else if nodeRecord.Role == api.RoleNode && !hasCapabilityRoles {
- isAuthorized = true
- }
-
- if !isAuthorized {
- http.Error(w, fmt.Sprintf("role %q is no longer authorized for this identity", nodeRecord.Role), http.StatusForbidden)
+ // Same rule as enrollment, re-evaluated against current policy: a mesh
+ // that unbinds the role revokes the identity's seat at the next refresh.
+ if !resolvedMap[nodeRecord.Role] {
+ http.Error(w, fmt.Sprintf("role %q is no longer bound to this identity", nodeRecord.Role), http.StatusForbidden)
return
}
diff --git a/internal/controlplane/server_test.go b/internal/controlplane/server_test.go
index bdcacca9..b56293ff 100644
--- a/internal/controlplane/server_test.go
+++ b/internal/controlplane/server_test.go
@@ -290,6 +290,7 @@ func TestNodeAndRouterRegistrationFlow(t *testing.T) {
}
bindings := []*api.PolicyBinding{
{Role: api.RoleRouter, Members: []string{"group:routers"}},
+ {Role: api.RoleNode, Members: []string{"group:users"}},
{Role: "user-role", Members: []string{"group:users"}},
}
if err := store.SaveMeshPolicy(ctx, roles, bindings); err != nil {
@@ -2163,6 +2164,22 @@ func TestAuthDenialPaths(t *testing.T) {
}
})
+ t.Run("node enrollment is closed until a binding grants it", func(t *testing.T) {
+ // No sam:role:node binding exists yet; the removed fallback used to
+ // enroll any authenticated identity here (GHSA-cgmg-9xf6-rrgw).
+ anybodyJWT := mintToken(map[string]interface{}{
+ "sub": "node-anybody",
+ })
+ resp, err := client.Post(baseURL+"/register", "application/x-protobuf", bytes.NewReader(newEnrollBody(anybodyJWT)))
+ if err != nil {
+ t.Fatalf("request failed: %v", err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ if resp.StatusCode != http.StatusForbidden {
+ t.Errorf("expected 403 for unbound sam:role:node enrollment, got %d", resp.StatusCode)
+ }
+ })
+
t.Run("register rejects role not granted by policy", func(t *testing.T) {
if err := store.SaveMeshPolicy(context.Background(), nil, []*api.PolicyBinding{
{Role: api.RoleNode, Members: []string{"group:users"}},
diff --git a/internal/router/router_test.go b/internal/router/router_test.go
index 8d858f15..5798219d 100644
--- a/internal/router/router_test.go
+++ b/internal/router/router_test.go
@@ -141,6 +141,7 @@ func setupControlPlane(t *testing.T, oidcIssuer string) (*controlplane.Server, s
}
bindings := []*api.PolicyBinding{
{Role: api.RoleRouter, Members: []string{"group:routers"}},
+ {Role: api.RoleNode, Members: []string{"group:users"}},
{Role: "user-role", Members: []string{"group:users"}},
}
diff --git a/mobile/mobile_e2e.sh b/mobile/mobile_e2e.sh
index 64d165ca..6b962f33 100755
--- a/mobile/mobile_e2e.sh
+++ b/mobile/mobile_e2e.sh
@@ -130,6 +130,7 @@ curl -s -X POST \
],
"bindings": [
{"role": "admin", "members": ["sam:system:authenticated"]},
+ {"role": "sam:role:node", "members": ["sam:system:authenticated"]},
{"role": "sam:role:router", "members": ["group:routers"]}
]
}' \
diff --git a/site/content/docs/manifests/sam-control-plane.yaml b/site/content/docs/manifests/sam-control-plane.yaml
index bf5efb5b..a92901ce 100644
--- a/site/content/docs/manifests/sam-control-plane.yaml
+++ b/site/content/docs/manifests/sam-control-plane.yaml
@@ -124,7 +124,8 @@ spec:
{"name": "demo-caller", "allowed_services": ["mcp://calculator", "system://sam.catalog"], "allowed_targets": ["user:test-user"]}
],
"bindings": [
- {"role": "demo-caller", "members": ["user:test-user"]}
+ {"role": "demo-caller", "members": ["user:test-user"]},
+ {"role": "sam:role:node", "members": ["user:test-user"]}
]
}' \
http://sam-control-plane:8080/policies
diff --git a/site/content/docs/user/control-plane-configuration.md b/site/content/docs/user/control-plane-configuration.md
index 3d01299d..1603e609 100644
--- a/site/content/docs/user/control-plane-configuration.md
+++ b/site/content/docs/user/control-plane-configuration.md
@@ -107,11 +107,14 @@ To enforce the principle of least privilege, the Sovereign Agent Mesh implements
- `sam-router` requests `sam:role:router` (P2P routing and relay service)
The control plane control plane validates that the enrolling client is authorized for the requested role before issuing the Biscuit identity token:
-1. **Node Fallback**: By default, any successfully authenticated OIDC identity or generic bootstrap token can claim the `sam:role:node` role.
-2. **Explicit Bindings**: The higher-privilege capability roles `sam:role:router` and `sam:role:sambox` must be explicitly authorized to the user/service account by mapping the role name in bindings. For example:
+1. **Explicit Bindings**: Every capability role — including `sam:role:node` — must be bound to the enrolling identity in mesh policy. There is no fallback: a mesh with no `sam:role:node` binding enrolls no nodes. To open node enrollment to every identity the OIDC issuer authenticates (an intentionally public mesh), bind it explicitly:
```json
"bindings": [
+ {
+ "role": "sam:role:node",
+ "members": ["group:eng-team"]
+ },
{
"role": "sam:role:router",
"members": ["group:mesh-routers"]
diff --git a/site/content/docs/user/kubernetes-deployment.md b/site/content/docs/user/kubernetes-deployment.md
index 88d6e803..55c54f60 100644
--- a/site/content/docs/user/kubernetes-deployment.md
+++ b/site/content/docs/user/kubernetes-deployment.md
@@ -141,7 +141,8 @@ curl -sf -X POST \
{"name": "node-role", "allowed_services": ["mcp://calculator", "system://sam.catalog"], "allowed_targets": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]}
],
"bindings": [
- {"role": "node-role", "members": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]}
+ {"role": "node-role", "members": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]},
+ {"role": "sam:role:node", "members": ["user:system:serviceaccount:sam-nodes:sam-node-sa"]}
]
}' \
https://CONTROL-PLANE.YOUR-DOMAIN.COM/policies
diff --git a/tests/e2e/lib/container_mesh.bash b/tests/e2e/lib/container_mesh.bash
index 3dd19273..5caba6c7 100644
--- a/tests/e2e/lib/container_mesh.bash
+++ b/tests/e2e/lib/container_mesh.bash
@@ -400,6 +400,7 @@ if [[ -z "${MESH_HELPERS_LOADED:-}" ]]; then
--set console.enabled=false
--set 'router.externalAddrs={/dns4/sam-router/tcp/4501}'
--set 'bootstrap.nodeServices={mcp://calculator,mcp://db-agent,mcp://http-tool,mcp://stdio-tool,a2a://echo,system://sam.catalog}'
+ --set 'bootstrap.nodeMembers={user:test-user}'
--set 'bootstrap.nodeLabels={region=*}')
if ! "${helm_bin}" "${helm_args[@]}"; then
# The reused cluster may hold StatefulSets whose immutable spec (e.g.
diff --git a/tests/integration/biscuit_expiry_test.go b/tests/integration/biscuit_expiry_test.go
index bd9309ed..60f00af6 100644
--- a/tests/integration/biscuit_expiry_test.go
+++ b/tests/integration/biscuit_expiry_test.go
@@ -66,6 +66,7 @@ func TestBiscuitExpiryIsEnforcedOnEveryPath(t *testing.T) {
cpCmd := exec.Command(cpBin,
"--bind-address", fmt.Sprintf("127.0.0.1:%d", cpPort),
+ "--admin-token-path", tokenPath(t, "test-admin-token"),
"--db-dsn", filepath.Join(tmpDir, "cp-keys.db"),
"--issuer", oidcURL,
"--insecure-skip-tls-verify",
@@ -79,6 +80,16 @@ func TestBiscuitExpiryIsEnforcedOnEveryPath(t *testing.T) {
defer func() { _ = cpCmd.Process.Kill(); _ = cpCmd.Wait() }()
waitForControlPlane(t, cpPort)
+ // Node enrollment requires the requested role to resolve from a binding.
+ // The grants mirror the shape this test always ran with (the no-policy
+ // mint fallback): unrestricted, because the subject here is expiry.
+ policyFile := filepath.Join(tmpDir, "policies.yaml")
+ policyYAML := "roles:\n - name: sam:role:node\n allowed_services: [\"*\"]\n allowed_targets: []\n custom_datalog: [\"target_unrestricted();\"]\nbindings:\n - role: sam:role:node\n members: [\"user:expiry-user\"]\n"
+ if err := os.WriteFile(policyFile, []byte(policyYAML), 0644); err != nil {
+ t.Fatal(err)
+ }
+ injectPolicyYAML(t, cpPort, "test-admin-token", policyFile)
+
privKey, pubKey, err := crypto.GenerateEd25519Key(rand.Reader)
if err != nil {
t.Fatal(err)
diff --git a/tests/integration/debug_endpoints_test.go b/tests/integration/debug_endpoints_test.go
index af384aa9..bf80a9a0 100644
--- a/tests/integration/debug_endpoints_test.go
+++ b/tests/integration/debug_endpoints_test.go
@@ -85,7 +85,9 @@ func TestDebugEndpoints(t *testing.T) {
// Create a mock policy file
policyFile := filepath.Join(tmpDir, "policies.yaml")
- policyContent := `bindings: []
+ policyContent := `bindings:
+ - members: ["user:mock-user"]
+ role: sam:role:node
roles: []
`
if err := os.WriteFile(policyFile, []byte(policyContent), 0644); err != nil {
diff --git a/tests/integration/failover_test.go b/tests/integration/failover_test.go
index 2b1241de..e04f9b47 100644
--- a/tests/integration/failover_test.go
+++ b/tests/integration/failover_test.go
@@ -46,7 +46,9 @@ func TestFailoverUpdatesRelay(t *testing.T) {
// Create a mock policy file
policyFile := filepath.Join(tmpDir, "policies.yaml")
- policyContent := `bindings: []
+ policyContent := `bindings:
+ - members: ["user:mock-user"]
+ role: sam:role:node
roles: []
`
writePolicyWithRouter(t, policyFile, policyContent)
diff --git a/tests/integration/federation_test.go b/tests/integration/federation_test.go
index d8b5aed3..5bb86b73 100644
--- a/tests/integration/federation_test.go
+++ b/tests/integration/federation_test.go
@@ -47,6 +47,8 @@ func TestRouterFederationAndRelay(t *testing.T) {
policyContent := `bindings:
- members: ["user:mock-user"]
role: admin
+ - members: ["user:mock-user"]
+ role: sam:role:node
roles:
- name: admin
allowed_services:
diff --git a/tests/integration/local_policy_test.go b/tests/integration/local_policy_test.go
index 4acd1ba0..41fb680f 100644
--- a/tests/integration/local_policy_test.go
+++ b/tests/integration/local_policy_test.go
@@ -42,6 +42,8 @@ bindings:
members: ["user:unprivileged-user"]
- role: none
members: ["user:nodeB-user"]
+ - role: sam:role:node
+ members: ["user:unprivileged-user", "user:nodeB-user"]
`
if err := os.WriteFile(controlPlanePolicyFile, []byte(controlPlanePolicyYAML), 0644); err != nil {
t.Fatal(err)
@@ -185,6 +187,8 @@ bindings:
members: ["user:client-user"]
- role: restricted-role
members: ["user:nodeB-user"]
+ - role: sam:role:node
+ members: ["user:client-user", "user:nodeB-user"]
`
if err := os.WriteFile(controlPlanePolicyFile, []byte(controlPlanePolicyYAML), 0644); err != nil {
t.Fatal(err)
diff --git a/tests/integration/minimal_helpers_test.go b/tests/integration/minimal_helpers_test.go
index 9a15d735..d2fe2dff 100644
--- a/tests/integration/minimal_helpers_test.go
+++ b/tests/integration/minimal_helpers_test.go
@@ -658,7 +658,10 @@ func writePolicyWithRouter(t *testing.T, path string, yamlContent string) {
routerRole := fmt.Sprintf(` - name: %s
allowed_services: []
- allowed_targets: ["*"]`, api.RoleRouter)
+ allowed_targets: ["*"]
+ - name: %s
+ allowed_services: []
+ allowed_targets: []`, api.RoleRouter, api.RoleNode)
routerBinding := fmt.Sprintf(` - role: %s
members: ["group:routers"]`, api.RoleRouter)
diff --git a/tests/integration/multimaster_test.go b/tests/integration/multimaster_test.go
index 82ea42bf..0277e84b 100644
--- a/tests/integration/multimaster_test.go
+++ b/tests/integration/multimaster_test.go
@@ -41,9 +41,12 @@ func TestMultiMasterControlPlane(t *testing.T) {
tmpDir := t.TempDir()
- // Create a mock policy file
+ // Create a mock policy file. Node enrollment requires the requested role
+ // to resolve from a binding, so bind it to the test node's identity.
policyFile := filepath.Join(tmpDir, "policies.yaml")
- policyContent := `bindings: []
+ policyContent := `bindings:
+ - role: sam:role:node
+ members: ["user:mock-user"]
roles: []
`
writePolicyWithRouter(t, policyFile, policyContent)
diff --git a/tests/integration/policy_permutations_test.go b/tests/integration/policy_permutations_test.go
index a3ed12b9..b8064db6 100644
--- a/tests/integration/policy_permutations_test.go
+++ b/tests/integration/policy_permutations_test.go
@@ -124,6 +124,10 @@ bindings:
members: ["user:admin-user"]
- role: admin
members: ["user:nodeB"]
+ # This suite permutes service/target grants, not enrollment; every identity
+ # (including the deliberately unknown one) must still get a seat.
+ - role: sam:role:node
+ members: ["sam:system:authenticated"]
`
if err := os.WriteFile(controlPlanePolicyFile, []byte(controlPlanePolicyYAML), 0644); err != nil {
t.Fatal(err)
diff --git a/tests/integration/revocation_test.go b/tests/integration/revocation_test.go
index b7f837d8..14d015cb 100644
--- a/tests/integration/revocation_test.go
+++ b/tests/integration/revocation_test.go
@@ -48,6 +48,8 @@ func TestNodeRevocationIntegration(t *testing.T) {
policyContent := `bindings:
- members: ["user:mock-user"]
role: admin
+ - members: ["user:mock-user"]
+ role: sam:role:node
roles:
- name: admin
allowed_services: ["*"]
diff --git a/tests/integration/rotation_test.go b/tests/integration/rotation_test.go
index a25a90af..a188900d 100644
--- a/tests/integration/rotation_test.go
+++ b/tests/integration/rotation_test.go
@@ -43,6 +43,8 @@ func TestKeyRotationIntegration(t *testing.T) {
policyContent := `bindings:
- members: ["user:mock-user"]
role: admin
+ - members: ["user:mock-user"]
+ role: sam:role:node
roles:
- name: admin
allowed_services: ["*"]