Skip to content

Agent Mesh

docs: a bootstrap token, not a binding, decides the enrolled role

Tomas Tormoc87d1ab93ee2
diff --git a/charts/agentmesh/values.yaml b/charts/agentmesh/values.yaml
index 7e158efc..20010595 100644
--- a/charts/agentmesh/values.yaml
+++ b/charts/agentmesh/values.yaml
@@ -204,8 +204,8 @@ bootstrap:
bindings: []
# Identities that may enroll as mesh:role:node ("user:<sub>", "group:<name>",
# "email:<addr>", or "mesh: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.
+ # mesh). Empty means no node can enroll with an OIDC identity until an
+ # operator grants it (fail closed). Ignored when bindings is set: then you own the whole list.
nodeMembers: []
# Services mesh:role:node may call, as "type://name" entries (e.g.
# "mcp://calculator"). Any authenticated identity can claim mesh:role:node,
diff --git a/site/content/docs/concepts/authorization.md b/site/content/docs/concepts/authorization.md
index 8fa13ad3..6ae5dd38 100644
--- a/site/content/docs/concepts/authorization.md
+++ b/site/content/docs/concepts/authorization.md
@@ -99,8 +99,10 @@ Roles are never members and never claims. `role:x` is not a valid member,
and an identity provider cannot give out a mesh role by putting it in a
`roles` claim. Such a claim becomes an `idp_role` fact, and a binding can
choose to honour it. The two built-in roles, `mesh:role:node` and
-`mesh:role:router`, follow the same rule: a binary can only enroll if a
-binding gives its identity the role it needs.
+`mesh:role:router`, follow the same rule. A binary that enrolls with an
+OIDC identity gets the role only if a binding gives the role to that
+identity. A binary that enrolls with a bootstrap token gets the token's
+role without a binding.
The control plane validates a policy when it is posted. It rejects a policy
that references an undefined role, uses an unknown member prefix, or would
diff --git a/site/content/docs/concepts/identity.md b/site/content/docs/concepts/identity.md
index a16403db..b13c823f 100644
--- a/site/content/docs/concepts/identity.md
+++ b/site/content/docs/concepts/identity.md
@@ -64,17 +64,20 @@ spent as soon as one node is approved with it. This is how machines without
an identity of their own enroll, and how `agentmesh-one` enrolls devices by QR
code.
-For all three paths, the control plane checks the same things before it
+For all three paths, the control plane checks these things before it
mints a credential:
1. The peer ID matches the submitted public key, and the challenge signature
verifies under that key. This proves that the requester holds the key it
is registering.
2. Neither the peer ID nor the identity behind it is banned.
-3. The identity resolves, through the bindings in the mesh policy, to the
- role being requested. `agentmesh-node` requests `mesh:role:node` and `agentmesh-router`
- requests `mesh:role:router`. If the policy binds nobody to `mesh:role:node`,
- no node can enroll.
+3. The requester may hold the role it requests. `agentmesh-node` requests
+ `mesh:role:node` and `agentmesh-router` requests `mesh:role:router`. On
+ the two OIDC paths, the identity must resolve to that role through the
+ bindings in the mesh policy. If the policy binds nobody to
+ `mesh:role:node`, no node can enroll with an OIDC identity. On the
+ bootstrap token path, the requested role must be the token's role. The
+ control plane does not consult the bindings for the role.
4. Every label the node declared is permitted by the `allowed_labels` of a
role it holds. A role without `allowed_labels` permits no labels.
diff --git a/site/content/docs/guides/kubernetes.md b/site/content/docs/guides/kubernetes.md
index acbbbdc9..83e39602 100644
--- a/site/content/docs/guides/kubernetes.md
+++ b/site/content/docs/guides/kubernetes.md
@@ -55,7 +55,7 @@ does not need the flag.
The four `bootstrap.*` values write the initial policy:
- `nodeMembers`: the identities that may enroll as `mesh:role:node`. If
- empty, no node can join until you post a policy.
+ empty, no node can enroll with an OIDC identity until you post a policy.
- `nodeServices`: the services that nodes may call. If empty, nodes can call
nothing.
- `nodePublish`: the services that nodes may serve: announce to the