1. Docs
  2. Tutorials
  3. AI agents
  4. RBAC and SSO

Last modified June 21, 2026

Map RBAC and single sign-on

An AI agent acting through Muster has exactly the permissions of the person driving it—no more. Authorization isn’t something Muster grants. It flows from the user’s identity-provider groups through to each cluster’s Kubernetes RBAC. This guide explains how that chain works and how to keep it healthy.

The permission chain

Three layers combine to decide what an agent can do:

  1. Identity provider: the user authenticates through enterprise single sign-on. Their token carries group claims.
  2. Muster: keys all per-user state on the OAuth sub (subject) claim and forwards or exchanges the user’s token to each downstream server. Muster never widens access—it can’t let an agent do something the user’s token doesn’t permit.
  3. Kubernetes RBAC: each cluster binds identity-provider groups to roles. A tool call the user isn’t permitted to make is rejected by the cluster itself.

Because Muster keys visibility on identity, each user only sees tools from servers they’ve personally authenticated with. This is per-user tool visibility: a cluster a user can’t reach simply doesn’t appear in their tool list. See the security model for the mechanics.

Bind identity-provider groups to cluster roles

For an agent to do anything useful on a cluster, the user’s groups must be bound to a Kubernetes role there. This is standard OIDC RBAC: a ClusterRoleBinding (or RoleBinding) whose subject is the group from the identity provider.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: platform-team-view
subjects:
  - kind: Group
    name: "platform-team"
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

Manage these bindings through your usual GitOps pipeline, the same as any other cluster RBAC. The group name must match exactly what the identity provider puts in the token.

Forward or exchange the token

Muster needs the user’s token to reach a downstream server in a form the cluster’s OIDC accepts:

  • Token forwarding (auth.forwardToken: true): reuse the user’s token where the downstream server trusts the same issuer. For Kubernetes OIDC, add the audience the cluster expects with requiredAudiences so the forwarded token is accepted:
spec:
  auth:
    type: oauth
    forwardToken: true
    requiredAudiences:
      - "dex-k8s-authenticator"
  • Token exchange (auth.tokenExchange): for remote clusters with their own identity provider, exchange the central token for one the remote provider issues. See multi-cluster access.

When an agent hits a forbidden error

A message like this in the agent output means RBAC, not a Muster bug:

networkpolicies.networking.k8s.io is forbidden: User "<user>" cannot list
resource "networkpolicies" in API group "networking.k8s.io" in the namespace
"kube-system"

The user authenticated fine, but their groups aren’t bound to a role that allows the action. Fix it by binding the right identity-provider group to an appropriate role on that cluster. The agent picks up the new permission on its next call—no reconnect needed.

Large tokens

Enterprise tokens that carry many group claims can break two limits:

  • Ingress header buffers. A token with many groups can exceed the default nginx header buffer, and the request is rejected before it reaches the server. Raise large_client_header_buffers on the mcp-kubernetes ingress to accept large tokens.
  • Group count. Users in a very large number of groups were once rejected outright. The OAuth layer now truncates excessive groups to a configurable limit instead of rejecting the request, so users in many groups can still authenticate. If a user belongs to more groups than the limit, make sure the groups that matter for cluster RBAC are within it.

If a user can authenticate from a small account but fails from one that belongs to many groups, suspect these limits first.