Kubernetes Identity Subject Model

Kubernetes Identity Subject Model is the conceptual framework describing the kinds of principals — subjects — that the Kubernetes API server recognizes when making authentication and authorization decisions. Rather than storing user accounts internally, Kubernetes defines a small, fixed vocabulary of subject types and lets external systems supply the concrete identities that fill those slots. Every access-control decision in the cluster, from an RBAC binding to an admission webhook, ultimately resolves to one of these subject kinds.

The Three Subject Kinds

User

A User represents a human or an external system authenticating to the cluster. Kubernetes has no User API object; the username is simply the string extracted from the authentication method in use — the Common Name of a client certificate, the sub or email claim of an OIDC token, or the identity returned by a webhook authenticator. Because there is no backing object, users cannot be listed, created, or deleted through the Kubernetes API; they exist only as an artifact of successful authentication.

Group

A Group is a named collection of users, also derived from the authentication layer rather than stored in Kubernetes. X.509 certificates encode groups in the Organization field; OIDC tokens encode them in a configurable claim (commonly groups). Groups let cluster administrators bind permissions once to a group name and have every current and future member of that group inherit the binding, without editing RBAC objects each time membership changes.

ServiceAccount

A ServiceAccount is the only subject kind that Kubernetes manages as a first-class API object (kind: ServiceAccount). It represents the identity of a workload — a pod, a controller, an operator — running inside the cluster. Service accounts are namespaced, are created and deleted like any other resource, and are automatically issued signed tokens that the workload uses to authenticate back to the API server.

How Subjects Attach to Permissions

RoleBinding and ClusterRoleBinding

Subjects gain permissions exclusively through binding objects. A RoleBinding or ClusterRoleBinding contains a subjects list, where each entry specifies a kind (User, Group, or ServiceAccount), a name, and, for service accounts, a namespace. The binding also references a roleRef pointing to the Role or ClusterRole whose rules apply to every listed subject.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: read-pods
  namespace: payments
subjects:
- kind: ServiceAccount
  name: billing-worker
  namespace: payments
- kind: Group
  name: platform-sre
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

Default and Well-Known Group Names

Kubernetes recognizes several built-in group names that carry special meaning during authorization. system:authenticated matches any subject that passed authentication; system:unauthenticated matches anonymous requests; system:serviceaccounts matches every service account cluster-wide; and system:serviceaccounts:<namespace> matches every service account within a specific namespace.

Resolving a Subject's Identity

From Credential to Subject

When a request arrives, the authentication chain runs each configured authenticator (client certificates, bearer tokens, webhook) until one succeeds, producing a UserInfo structure containing the username, the UID, the group list, and any extra attributes. This UserInfo is what every authorizer subsequently evaluates — it is the canonical, in-memory representation of "who is making this request" for the lifetime of that single API call.

Impersonation

Kubernetes allows a sufficiently privileged subject to impersonate another subject by setting the Impersonate-User, Impersonate-Group, or Impersonate-Extra-* headers on a request, provided they hold the impersonate verb on the target subject kind. This is used by tooling that needs to act "as" another identity for testing or delegation, and it is itself subject to RBAC control.

Service Account Token Structure

Bound Service Account Tokens

Modern clusters issue service account tokens as JWTs bound to a specific pod, audience, and expiry, generated through the TokenRequest API and mounted via a projected volume. The claims embedded in the token — sub (the service account), kubernetes.io/pod.name, kubernetes.io/pod.uid, and the audience list — allow the API server and other services to verify not just which service account is calling, but from which specific pod instance.

Legacy Auto-Mounted Tokens

Older clusters mount a long-lived token stored in a Secret of type kubernetes.io/service-account-token, automatically attached to every pod using the associated service account unless explicitly disabled. These tokens have no expiry and no audience restriction, making them more valuable to an attacker and less auditable, which is why bound tokens are the current recommended default.

Practical Implications

Modeling Workload Identity Correctly

Because ServiceAccount is the only subject kind Kubernetes truly owns, workload identity design should treat one service account per distinct workload role as the baseline pattern, rather than sharing a single broadly-scoped service account across unrelated deployments.

Group Membership Is External

Since group membership for User subjects is entirely determined by the authentication provider, any change to group assignment (adding someone to an admin group, for instance) takes effect the moment the identity provider is updated — Kubernetes itself has no mechanism to review or override group claims once the token is trusted.