What Is Impersonation in Kubernetes?

Detailed Answer

Impersonation is a Kubernetes API feature that lets an authenticated user make API requests as if they were a different user, group, or ServiceAccount. The API server checks the impersonator's permissions first, then evaluates the request as the impersonated identity.

How Impersonation Works

When a request includes impersonation headers, the API server:

1. Authenticates the actual caller
2. Checks if the caller has permission to impersonate the target identity
3. If authorized, processes the request as the target identity
4. Authorization and admission are evaluated against the impersonated identity

Using Impersonation with kubectl

# Test what jane can do
kubectl auth can-i create deployments --as=jane@example.com
# yes

# Test what the dev-team group can do
kubectl auth can-i delete pods --as=jane@example.com --as-group=dev-team
# no

# List pods as a ServiceAccount
kubectl get pods --as=system:serviceaccount:production:deployer

# Run any command as another identity
kubectl get secrets --as=system:serviceaccount:kube-system:default

Granting Impersonation Permissions

Impersonation requires explicit RBAC permissions with the impersonate verb:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonate-users
rules:
  # Allow impersonating specific users
  - apiGroups: [""]
    resources: ["users"]
    verbs: ["impersonate"]
    resourceNames:
      - "jane@example.com"
      - "bob@example.com"
  # Allow impersonating specific groups
  - apiGroups: [""]
    resources: ["groups"]
    verbs: ["impersonate"]
    resourceNames:
      - "dev-team"
      - "staging-deployers"
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-impersonate
subjects:
  - kind: User
    name: platform-admin@example.com
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: impersonate-users
  apiGroup: rbac.authorization.k8s.io

Impersonation Resources

| Resource | Description | Example | |----------|-------------|---------| | users | Impersonate a user identity | --as=jane@example.com | | groups | Impersonate group membership | --as-group=dev-team | | serviceaccounts | Impersonate a ServiceAccount | --as=system:serviceaccount:ns:sa | | userextras/* | Impersonate extra attributes | Custom authentication attributes |

Security Best Practices

Always Use resourceNames

# DANGEROUS: Can impersonate ANY user including cluster-admin
rules:
  - apiGroups: [""]
    resources: ["users"]
    verbs: ["impersonate"]
    # No resourceNames = can impersonate anyone

# SAFE: Can only impersonate specific users
rules:
  - apiGroups: [""]
    resources: ["users"]
    verbs: ["impersonate"]
    resourceNames:
      - "developer@example.com"

Without resourceNames, the impersonator can act as any user — including system:masters group members — effectively becoming a cluster super-admin.

Never Allow Group Impersonation Without Restrictions

# EXTREMELY DANGEROUS: Can impersonate system:masters
rules:
  - apiGroups: [""]
    resources: ["groups"]
    verbs: ["impersonate"]
    # No resourceNames restriction!

API Gateway Pattern

A common production pattern uses impersonation in API gateways that front the Kubernetes API:

User → API Gateway → Kubernetes API
         │
         ├── Authenticates user via OIDC/LDAP
         ├── Maps user to Kubernetes identity
         └── Sends request with Impersonate-User header

The API gateway ServiceAccount has impersonation permissions. The gateway authenticates users externally and proxies requests with the appropriate impersonation headers:

Impersonate-User: jane@example.com
Impersonate-Group: dev-team
Impersonate-Group: staging-deployers

Impersonation for Debugging

Platform engineers commonly use impersonation to debug access issues reported by users:

# Reproduce a user's permission error
kubectl get pods -n production --as=jane@example.com
# Error from server (Forbidden): pods is forbidden

# Check what permissions they have
kubectl auth can-i --list --as=jane@example.com -n production

# Check if a specific permission exists
kubectl auth can-i get secrets --as=jane@example.com -n production
# no

# Test with their group memberships
kubectl auth can-i get pods --as=jane@example.com \
  --as-group=dev-team --as-group=system:authenticated

Audit Trail

Impersonation is logged in the Kubernetes audit log with both the actual user and the impersonated identity:

{
  "user": {
    "username": "platform-admin@example.com",
    "groups": ["platform-admins"]
  },
  "impersonatedUser": {
    "username": "jane@example.com",
    "groups": ["dev-team"]
  },
  "verb": "get",
  "resource": "pods"
}

This provides a clear audit trail of who impersonated whom and what they did.

Common Pitfalls

1. Granting blanket impersonation: Always restrict with resourceNames
2. Forgetting group impersonation: A user who can impersonate system:masters has cluster-admin access
3. Not auditing impersonation events: Set up alerts for impersonation usage
4. Using impersonation instead of proper RBAC: Impersonation is for debugging and proxying, not for regular access