kubectl whoami — knowing what the cluster sees

Knowing what the API server thinks you are is the foundation of every RBAC operation. kubectl auth whoami (kubectl 1.30+) returns the UserInfo the API server sees for the current identity. This lesson covers the command, the underlying SelfSubjectReview API, and the operational patterns for verifying kubeconfig contexts.

The basic syntax

kubectl auth whoami

The output is the UserInfo:

ATTRIBUTE   VALUE
Username    alice@example.com
Groups      [idp:dev idp:oncall system:authenticated]

The Username is the UserInfo.username; the Groups are the UserInfo.groups. For an OIDC user, the Username is the email claim (or whatever the API server is configured to map to username). The Groups are the prefixed IdP groups.

# Verbose output
kubectl auth whoami -v=8
# (full request and response)

# JSON output
kubectl auth whoami -o json
{
  "username": "alice@example.com",
  "groups": ["idp:dev", "idp:oncall", "system:authenticated"]
}

The underlying API

kubectl auth whoami calls the SelfSubjectReview API:

POST /apis/authentication.k8s.io/v1/selfsubjectreviews

The API server’s response is the UserInfo. The API is open to any authenticated identity — there is no RBAC check beyond authentication. Anonymous requests are rejected.

# Direct API call (for diagnostics)
kubectl get --raw /apis/authentication.k8s.io/v1/selfsubjectreviews -X POST

Verifying OIDC

After OIDC is configured, whoami confirms the IdP mapping:

# Authenticate
kubectl --context=alice-prod get pods
# (browser opens, OIDC flow, ID token cached)

# Verify the identity
kubectl --context=alice-prod auth whoami
# Username: alice@example.com
# Groups: [idp:dev idp:oncall system:authenticated]

# Verify the group prefix
# The IdP's 'dev' group should appear as 'idp:dev'
# The 'system:authenticated' is the built-in

If the Username is empty or the Groups do not have the prefix, the OIDC configuration is wrong. The fix is to update the AuthenticationConfiguration claim mappings.

Verifying projected tokens

A workload’s projected SA token is verified with whoami from inside the container:

# Inside the Pod
kubectl auth whoami
# Username: system:serviceaccount:prod:api
# Groups: [system:serviceaccounts system:serviceaccounts:prod system:authenticated]

The Username is the SA’s full identity (system:serviceaccount:<namespace>:<name>); the Groups are the built-in SAs groups. The system:authenticated is added because the SA is authenticated.

Verifying impersonation

After kubectl auth impersonate, whoami returns the impersonated identity:

kubectl auth impersonate --as=alice --as-group=idp:dev
kubectl auth whoami
# Username: alice
# Groups: [idp:dev system:authenticated]

kubectl auth impersonate --as=""
kubectl auth whoami
# Username: <real identity>

The output reflects the impersonation. If the impersonation is rejected by RBAC (no impersonate verb), whoami returns an error.

Diagnosing authentication failures

whoami is the first diagnostic step for authentication failures:

# 1. Run whoami
kubectl auth whoami
# Error from server (Unauthorized): ...

# 2. Check the kubeconfig
kubectl config view --minify
# server, certificate-authority, user

# 3. Check the credentials
# For OIDC: ~/.kube/cache/ has the cached ID token
ls -la ~/.kube/cache/oidc-* 2>/dev/null

# 4. Check the API server's authentication log
# (kube-apiserver logs)

# 5. Test with verbose
kubectl auth whoami -v=8

The verbose output shows the request, the response, and any error. A token expired message points to the OIDC cache; a TLS error points to the CA bundle; an unauthorised message points to the kubeconfig context.

flowchart LR
    A[kubectl auth whoami] --> B[SelfSubjectReview]
    B -->|authenticated| C[UserInfo]
    B -->|unauthenticated| D[401 Unauthorized]
    B -->|expired token| E[Token expired]
    C --> F[Output Username + Groups]
    D --> G[Check kubeconfig]
    E --> H[Refresh OIDC cache]

Production failure modes

1. whoami not run before critical operations. An operator runs kubectl delete namespace prod against the wrong cluster. The fix is to run whoami and kubectl config view --minify before every critical operation.
2. OIDC group prefix missing. The output shows dev instead of idp:dev. The IdP groups are not namespaced; a malicious IdP group could impersonate built-in groups. The fix is to set the prefix in the AuthenticationConfiguration.
3. Cached token from a different identity. A developer logs in to their personal IdP on the same workstation; the cached token is the personal one. The fix is to use separate kubeconfig files or to clear the cache.

Cross-course references

• The Observability course covers the audit log entries that show the same UserInfo that whoami returns.
• The Linux course covers the file permissions for the kubeconfig and the OIDC cache.

Quiz

Production discipline

kubectl auth whoami is the first command every operator should run in a new shell. The output confirms the kubeconfig context, the OIDC identity, and the group prefix. A session that begins with kubectl whoami and kubectl config current-context is a session that operates with full knowledge of the identity; a session that begins with kubectl apply without verification is a session that risks acting against the wrong cluster, namespace, or identity. The discipline is to verify before every critical operation.