Where are groups in Kubernetes?

Architectural evaluations of Kubernetes frequently introduce operational friction for platform engineers encountering a missing core primitive: user groups. Executing administrative commands such as kubectl create group results in execution errors because native group objects do not exist within the Kubernetes API hierarchy. This design decision stems from the strict decoupling of authentication and authorization within the Kubernetes control plane. Kubernetes purposefully abstracts identity management to delegate authentication to external systems, relying entirely on string-based claims embedded in verified tokens, certificates, or cloud provider headers during RBAC evaluation.

Understanding this architecture is critical for engineering secure production environments across self-hosted enterprise clusters and managed platforms like Amazon EKS, Google Kubernetes Engine (GKE), and Azure Kubernetes Service (AKS). Misconfiguring identity federation or treating groups as first-class, mutable API resources leads to severe security misconfigurations, privilege escalation vulnerabilities, and compliance failures.

Problem Statement & Impact

The core challenge in Kubernetes identity management lies in the architectural boundary between the API server and external identity providers (IdPs). Kubernetes does not maintain a database of users, passwords, or groups. Instead, the API server acts as an evaluation engine that ingests cryptographically signed tokens or certificates, extracts claims, and matches them against Role-Based Access Control (RBAC) rules.

In environments running heterogeneous infrastructure stacks, this decoupled model introduces significant security risks:

• Orphaned Mappings: Deleting an identity in an external provider (such as an LDAP directory or Cloud IAM role) does not automatically purge RBAC bindings, leaving stale group strings vulnerable to claim spoofing or re-assignment.
• Privilege Escalation via Claim Manipulation: If an OIDC provider or webhook authenticator is misconfigured, malicious actors can inject arbitrary group claims (e.g., system:masters) into JSON Web Tokens (JWTs), bypassing authorization checks.
• Audit Blind Spots: When authentication layers map cloud identities to opaque group strings without centralized logging, tracking which specific human operator executed an administrative command becomes practically impossible.

Failing to secure this boundary exposes cluster control planes to unauthorized API access, cluster-wide container breakouts, and compromise of underlying cloud infrastructure via over-privileged service accounts or mapped roles.

Root Cause Analysis & Architecture

To understand why groups are absent from the Kubernetes API, examine the API server request lifecycle. When an HTTPS request hits the kube-apiserver, it passes through three mandatory phases:

1. Authentication: Identifies *who* is making the request.
2. Authorization: Determines *what* the authenticated identity is allowed to do.
3. Admission Control: Modifies or validates requests after authorization succeeds.

During the authentication phase, authentication modules process incoming credentials:

• X.509 Client Certificates: The API server extracts the Common Name (CN) for the username and Organization (O) fields for groups. A certificate with CN=devops-engineer and O=platform-team results in the user object Username: devops-engineer and Groups: ["platform-team"].
• OIDC Tokens: The API server validates the cryptographic signature of the JWT against the provider’s JSON Web Key Set (JWKS). It then extracts the username claim (configured via --oidc-username-claim, typically sub or email) and the groups claim (configured via --oidc-groups-claim).
• Webhook Token Authentication: The API server delegates validation to a remote HTTPS endpoint, which responds with a JSON structure containing the verified user, UID, and an array of group strings.

Crucially, once these strings are parsed into the internal user.Info struct within the Go runtime of the API server, the original authentication artifact is discarded for the duration of the authorization phase. The Kubernetes RBAC engine simply iterates through the provided list of group strings and evaluates them against active RoleBinding and ClusterRoleBinding objects.

# Conceptual internal user structure evaluated by the API server
User: "[email protected]"
UID: "110158421890327318524"
Groups: [
  "system:authenticated",
  "engineers",
  "database-admins"
]

Because groups are merely array elements passed in memory during request evaluation, running commands like kubectl get groups or kubectl describe groups database-admins fails with a the server could not find the requested resource error. The API server does not register a REST endpoint for group resources.

Step-by-Step Implementation & Remediation Guide

Configuring and securing group-based access requires coordinating an external identity source with internal Kubernetes RBAC objects. Below is a comprehensive workflow demonstrating how to configure OIDC group extraction, map groups using modern Amazon EKS Access Entries, and enforce least-privilege RBAC bindings.

Step 1: Configure OIDC Authentication on the API Server

For self-hosted clusters (e.g., deployed via kubeadm), configure the API server manifest located at /etc/kubernetes/manifests/kube-apiserver.yaml to ingest OIDC tokens and extract group claims.

apiVersion: v1
kind: Pod
metadata:
  name: kube-apiserver
  namespace: kube-system
spec:
  containers:
  - name: kube-apiserver
    image: k8s.gcr.io/kube-apiserver:v28.0.0
    command:
    - kube-apiserver
    - --oidc-issuer-url=https://auth.example.com/realms/production
    - --oidc-client-id=kubernetes-cluster
    - --oidc-username-claim=email
    - --oidc-groups-claim=groups
    - --oidc-ca-file=/etc/kubernetes/pki/oidc-ca.crt

Restart the kubelet service on control plane nodes to apply the manifest changes:

sudo systemctl daemon-reload
sudo systemctl restart kubelet

Step 2: Implement Modern EKS Access Entries (Replacing aws-auth)

In managed AWS environments, avoid legacy aws-auth ConfigMaps where possible. Instead, use EKS Access Entries to map IAM principals directly to Kubernetes groups.

# Create an access entry for an IAM role mapping it to custom Kubernetes groups
aws eks create-access-entry \
    --cluster-name production-cluster \
    --principal-arn arn:aws:iam::111122223333:role/PlatformEngineeringRole \
    --type STANDARD

# Associate the access entry with specific Kubernetes groups
aws eks associate-access-policy \
    --cluster-name production-cluster \
    --principal-arn arn:aws:iam::111122223333:role/PlatformEngineeringRole \
    --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSAdminPolicy \
    --access-scope type=cluster

# Alternatively, map custom group strings for fine-grained RBAC
aws eks create-access-entry \
    --cluster-name production-cluster \
    --principal-arn arn:aws:iam::111122223333:role/DatabaseOperationsRole \
    --type STANDARD

# Note: Custom group assignment via AWS CLI or Terraform
# associates the IAM principal with the string "database-operators"

Step 3: Define Least-Privilege RBAC Roles and Bindings

Once your authentication layer successfully injects group strings (e.g., database-operators), create the corresponding RBAC objects to authorize their access.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: database-secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  resourceNames: ["db-credentials", "tls-certs"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: bind-database-secret-reader
subjects:
- kind: Group
  name: database-operators
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: database-secret-reader
  apiGroup: rbac.authorization.k8s.io

Apply the RBAC manifests using kubectl:

kubectl apply -f database-rbac.yaml

Production Hardening & Edge Cases

Deploying group-based authorization in production requires accounting for caching behaviors, naming collisions, and propagation delays.

• Group Claim Token Bloat: If an OIDC provider embeds hundreds of group strings into a user’s JWT, the HTTP header size can exceed the API server’s maximum request header limits (default 8KB or 32KB). This results in HTTP 431 (Request Header Fields Too Large) errors. Mitigate this by scoping OIDC groups to application-specific scopes or using backend token introspection.
• System Group Prefixing: Kubernetes reserves groups starting with the system: prefix (e.g., system:masters, system:authenticated). Never map external identity groups to prefixed system namespaces unless granting absolute cluster administrative privileges.
• RBAC Propagation Latency: Changes to cloud IAM mappings or OIDC group memberships are subject to token expiration times. If a user’s group membership is revoked in Keycloak or AWS IAM, their existing JWT remains valid until its expiration timestamp (TTL). Implement short-lived tokens (e.g., 15-minute TTL) to minimize vulnerability windows.
• Staging Validation: Always validate RBAC configurations using Kubernetes’ built-in impersonation flags before rolling out permissions to production engineering teams.

# Test authorization from the perspective of a user in the database-operators group
kubectl auth can-i get secrets db-credentials \
    [email protected] \
    --as-group=database-operators

Diagnostic Verification & Checklist

Use the following verification matrix and troubleshooting commands to validate group propagation and authorization health across your Kubernetes clusters.

Routine auditing of these diagnostic parameters ensures that external identity federation remains tightly coupled to internal cluster security policies, preventing unauthorized escalation paths and maintaining operational resilience.