Kubernetes Impersonation Management

Kubernetes Impersonation Management is the configuration and governance of the API server's built-in impersonation feature, which allows a sufficiently privileged caller to act as a different user, group, or service account for the duration of a single request. Impersonation exists to support legitimate administrative and tooling needs — testing a role's effect as another identity, or having a proxy act on behalf of end users — but because it lets one identity borrow another's authorization outcome, it must be governed as carefully as any other high-privilege capability.

How Impersonation Works

Impersonation Headers

A request carries impersonation intent through HTTP headers: Impersonate-User sets the target username, Impersonate-Group (repeatable) sets target groups, and Impersonate-Extra-<key> sets arbitrary extra attributes. The API server authenticates the original caller normally, then, if impersonation is authorized, evaluates the rest of the request as though it had been made by the impersonated identity.

kubectl get pods --namespace payments \
  --as system:serviceaccount:payments:billing-worker \
  --as-group=payments-readers

The impersonate Verb

Performing impersonation requires the impersonate verb granted on the specific users, groups, or serviceaccounts resource (in the core API group) that matches the target identity; a subject cannot impersonate arbitrary identities simply by holding broad general permissions elsewhere.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonate-billing-worker
rules:
- apiGroups: [""]
  resources: ["serviceaccounts"]
  resourceNames: ["billing-worker"]
  verbs: ["impersonate"]

Legitimate Use Cases

Verifying RBAC Changes

Administrators use impersonation via kubectl --as to confirm that a newly created or modified role behaves as intended from the perspective of the affected identity, without needing to obtain that identity's actual credentials.

Proxies and Gateways Acting on Behalf of End Users

An API gateway or dashboard that authenticates end users through its own mechanism (not native Kubernetes authentication) can impersonate the resolved identity when forwarding requests to the API server, so that RBAC continues to apply per end user rather than per the gateway's own service account.

Auditing as a Specific Identity

Impersonation lets a support engineer reproduce exactly what an affected user or service account can see and do during an incident investigation, without requiring access to that identity's actual credentials, which is both more secure and more auditable than credential sharing.

Governance Considerations

Scoping Impersonation Narrowly

The impersonate verb should be granted for specific named identities or specific groups via resourceNames, rather than broadly across all users, groups, or service accounts — an unrestricted impersonation grant is functionally equivalent to holding the union of every identity's permissions in the cluster.

rules:
- apiGroups: [""]
  resources: ["users"]
  resourceNames: ["alice", "bob"]
  verbs: ["impersonate"]

Auditing Impersonated Requests

Audit logs distinguish the original authenticated identity from the impersonated identity for every request, recording both in separate fields; reviewing audit logs specifically for impersonation events is necessary because the impersonated identity, not the original caller, is what appears in most authorization-relevant log fields by default.

Restricting Who Can Grant Impersonation

Because impersonation access is itself governed by RBAC escalation rules, only subjects who already hold (or are explicitly permitted to grant beyond their own) the target identity's permissions should be able to create bindings granting the impersonate verb for that identity.

Risks of Misconfigured Impersonation

Impersonation as a Privilege Escalation Vector

A subject granted broad impersonate access on groups — particularly system:masters or an equivalent administrative group — can escalate to full cluster control by impersonating that group on any request, regardless of the subject's own otherwise-limited permissions.

Impersonation Obscures the True Actor Without Careful Logging

If audit logging or downstream systems only inspect the impersonated identity and not the original authenticated caller, accountability for an action becomes harder to establish; both identities should be preserved and reviewed together whenever impersonation is used to perform a sensitive operation.