Service Accounts

ServiceAccount Model

A ServiceAccount (SA) is a namespace-scoped Kubernetes object that provides an identity for processes running inside pods. When a pod makes API server calls, it authenticates using the ServiceAccount token that is (optionally) mounted into the pod.

ServiceAccount (namespace-scoped)
  ├── name: my-app
  ├── namespace: production
  ├── automountServiceAccountToken: false   (opt-in for pods that need API access)
  └── imagePullSecrets: [...]               (inherited by pods using this SA)

Pod uses SA:
  spec.serviceAccountName: my-app
    → kubelet mounts token into pod at /var/run/secrets/kubernetes.io/serviceaccount/
    → pod uses token to authenticate to kube-apiserver
    → RBAC authorization: is system:serviceaccount:production:my-app allowed?

Authentication identity string:
  system:serviceaccount::
  e.g.: system:serviceaccount:production:my-app

ServiceAccount Object

CopyapiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app
  namespace: production
  annotations:
    # Cloud workload identity annotations (see Workload Identity section)
    eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/my-app-role"
automountServiceAccountToken: false   # disable auto-mount; opt pods in explicitly
imagePullSecrets:                     # all pods using this SA inherit these
- name: private-registry-creds

Every Namespace Gets a default ServiceAccount

When a namespace is created, Kubernetes automatically creates a ServiceAccount named default. Any pod that does not specify a serviceAccountName automatically uses the default SA. This is the root cause of many SA security issues.

The default ServiceAccount Risk

Harden the Default ServiceAccount

Copy# Apply to every namespace on cluster creation or via admission policy
kubectl patch serviceaccount default \
  -n production \
  --patch '{"automountServiceAccountToken": false}'

# Verify: all namespaces should have default SA with automount disabled
kubectl get serviceaccounts --all-namespaces \
  -o jsonpath='{range .items[?(@.metadata.name=="default")]}{.metadata.namespace}: automount={.automountServiceAccountToken}{"\n"}{end}'

Copy# Enforce via Kyverno: all new namespaces get default SA with automount=false
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: disable-default-sa-automount
spec:
  rules:
  - name: disable-automount-default-sa
    match:
      any:
      - resources:
          kinds: ["ServiceAccount"]
    mutate:
      patchStrategicMerge:
        metadata:
          name: default
        automountServiceAccountToken: false

Token Evolution: Legacy vs Bound

Legacy Tokens (pre-1.22 default)

Before Kubernetes 1.22, service account tokens were stored as Secret objects and auto-mounted into pods. These tokens had critical security weaknesses:

Legacy Token Deprecation Timeline

Projected ServiceAccount Tokens

Bound projected tokens are the modern, secure way to mount SA tokens into pods. They are generated by the kubelet via the TokenRequest API and mounted as projected volumes. They are automatically rotated by the kubelet before expiry.

Copyspec:
  serviceAccountName: my-app
  volumes:
  - name: kube-api-token
    projected:
      sources:
      - serviceAccountToken:
          path: token
          expirationSeconds: 3600        # default; min 600s (10 min); kubelet rotates at 80% of TTL
          audience: "https://kubernetes.default.svc.cluster.local"  # audience claim in JWT
      - configMap:
          name: kube-root-ca.crt         # CA cert for verifying API server
          items:
          - key: ca.crt
            path: ca.crt
      - downwardAPI:
          items:
          - path: namespace
            fieldRef:
              fieldPath: metadata.namespace
  containers:
  - name: app
    volumeMounts:
    - name: kube-api-token
      mountPath: /var/run/secrets/kubernetes.io/serviceaccount
      readOnly: true

TokenRequest API

The TokenRequest API (GA 1.20) allows creating bound tokens for a ServiceAccount programmatically, for any duration and audience. This is used by kubelet internally for projected volumes, and can be used by external systems that need short-lived tokens.

Copy# Create a bound token for a SA via kubectl
kubectl create token my-app \
  --namespace production \
  --duration 3600s \
  --audience "https://kubernetes.default.svc"
# Returns a JWT that expires in 1h, bound to the SA

Copy# TokenRequest API call (used by external authenticators, CSI drivers, OIDC proxies)
apiVersion: authentication.k8s.io/v1
kind: TokenRequest
metadata:
  name: my-app
  namespace: production
spec:
  audiences:
  - "https://kubernetes.default.svc.cluster.local"
  - "vault"                               # custom audience for Vault auth
  expirationSeconds: 7200
  boundObjectRef:                         # optionally bind to a specific pod
    kind: Pod
    name: my-app-xyz
    uid: "abc-123-..."                    # token invalidated if pod UID changes

Copy# RBAC required to create tokens for a SA:
# verb: create, resource: serviceaccounts/token, resourceNames: [sa-name]
# Example: allow a CI system to create tokens for a specific SA
kubectl create role token-creator \
  --verb=create \
  --resource=serviceaccounts/token \
  --resource-name=my-app \
  -n production

automountServiceAccountToken

The automountServiceAccountToken field controls whether a SA token is automatically mounted into pods. It can be set at the ServiceAccount level (applies to all pods using the SA) or at the pod level (overrides the SA setting).

Copy# Pattern: disable at SA level, enable only for pods that need API access
apiVersion: v1
kind: ServiceAccount
metadata:
  name: api-client
  namespace: production
automountServiceAccountToken: false    # default OFF

---
# Pod that needs API access: explicitly opt in
spec:
  serviceAccountName: api-client
  automountServiceAccountToken: true   # explicit opt-in for this specific pod

---
# Pod that doesn't need API access: inherit SA default (false)
spec:
  serviceAccountName: api-client
  # automountServiceAccountToken not set → inherits false from SA
  # result: no token mounted → pod cannot call kube-apiserver at all

Token Inside the Pod

When a token is mounted, three files appear at /var/run/secrets/kubernetes.io/serviceaccount/:

JWT Payload Structure

Copy# Decode a projected token to inspect its claims
cat /var/run/secrets/kubernetes.io/serviceaccount/token | \
  cut -d. -f2 | base64 -d 2>/dev/null | jq .

Copy{
  "aud": ["https://kubernetes.default.svc.cluster.local"],
  "exp": 1735689600,              // expiration timestamp
  "iat": 1735686000,              // issued-at timestamp
  "iss": "https://kubernetes.default.svc.cluster.local",
  "kubernetes.io": {
    "namespace": "production",
    "node": {
      "name": "node-1",
      "uid": "abc-123"
    },
    "pod": {
      "name": "my-app-xyz-abc",
      "uid": "def-456"            // token invalidated when this pod is deleted
    },
    "serviceaccount": {
      "name": "my-app",
      "uid": "ghi-789"
    },
    "warnafter": 1735688400       // kubelet will rotate token after this time
  },
  "nbf": 1735686000,
  "sub": "system:serviceaccount:production:my-app"
}

Using the Token from Within a Pod

Copy# From inside a pod: call the API server using the mounted token
TOKEN=$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)
APISERVER=https://kubernetes.default.svc
CACERT=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
NAMESPACE=$(cat /var/run/secrets/kubernetes.io/serviceaccount/namespace)

# List pods in the same namespace
curl -s --cacert $CACERT \
  -H "Authorization: Bearer $TOKEN" \
  "$APISERVER/api/v1/namespaces/$NAMESPACE/pods" | jq '.items[].metadata.name'

OIDC Discovery & Federation

Kubernetes exposes an OIDC discovery endpoint that allows external systems (AWS IAM, GCP IAM, Vault, etc.) to verify SA tokens without calling the Kubernetes API. This is the foundation for IRSA and Workload Identity.

OIDC Discovery Endpoint:
  https://{apiserver}/.well-known/openid-configuration
  → returns issuer URL, JWKS URI, supported algorithms

JWKS Endpoint:
  https://{apiserver}/openid/v1/jwks
  → returns the public keys used to sign SA tokens

Verification flow (e.g., AWS STS AssumeRoleWithWebIdentity):
  1. Pod presents SA JWT to AWS STS
  2. AWS STS reads iss claim from JWT header
  3. AWS STS fetches JWKS from {iss}/.well-known/openid-configuration
  4. AWS STS verifies JWT signature against JWKS public keys
  5. AWS STS verifies aud claim matches configured value
  6. AWS STS issues temporary credentials if trust policy matches sub claim

Copy# Inspect cluster OIDC discovery (from within cluster)
curl -s https://kubernetes.default.svc/.well-known/openid-configuration | jq

# From external systems: the issuer URL is configured on the API server
# --service-account-issuer=https://oidc.eks.us-east-1.amazonaws.com/id/CLUSTER_ID

# For EKS: the issuer is the EKS OIDC endpoint
# For GKE: https://container.googleapis.com/v1/projects/.../serviceAccounts
# For self-managed: configure --service-account-issuer with a publicly reachable URL

RBAC for Service Accounts

The core principle is one dedicated ServiceAccount per workload, each with minimal RBAC permissions. See 01-rbac.html for full RBAC documentation. Key SA-specific patterns:

Dedicated SA with Minimal Permissions

Copy# Pattern: every workload gets its own SA
apiVersion: v1
kind: ServiceAccount
metadata:
  name: payment-service
  namespace: production
automountServiceAccountToken: false    # explicitly opt pods in
---
# Only grant what's needed — this SA manages its own ConfigMaps only
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: payment-service-config
  namespace: production
rules:
- apiGroups: [""]
  resources: ["configmaps"]
  resourceNames: ["payment-config", "payment-feature-flags"]
  verbs: ["get", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: payment-service-config
  namespace: production
subjects:
- kind: ServiceAccount
  name: payment-service
  namespace: production
roleRef:
  kind: Role
  name: payment-service-config
  apiGroup: rbac.authorization.k8s.io

SA for Cluster-Wide Operators

Copy# Operator SA in its own namespace with ClusterRole
apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-operator
  namespace: my-operator-system
automountServiceAccountToken: true     # operator needs API access
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: my-operator
subjects:
- kind: ServiceAccount
  name: my-operator
  namespace: my-operator-system        # SA namespace must be specified
roleRef:
  kind: ClusterRole
  name: my-operator                    # defined in rbac.html examples
  apiGroup: rbac.authorization.k8s.io

Cross-Namespace SA Reference

Copy# Grant a SA from namespace A access to namespace B's resources
# The SA subject can reference a different namespace than the binding
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: monitoring-pod-reader
  namespace: production               # binding is in production
subjects:
- kind: ServiceAccount
  name: prometheus                    # SA is in monitoring namespace
  namespace: monitoring               # SA's namespace explicitly specified
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

Service Account Patterns

Pattern: SA for Init Containers vs Main Container

Copy# If init container needs API access but main container doesn't,
# disable automount at pod level and add projected volume only to init container.
# However, Kubernetes doesn't support per-container SA tokens natively.
# Workaround: use TokenRequest API from an init container to fetch a scoped token,
# store it in an emptyDir, and have the main container use that file.
spec:
  serviceAccountName: init-job-sa    # SA with init permissions
  automountServiceAccountToken: true # needed for init
  initContainers:
  - name: setup
    image: kubectl:latest
    command: ["/bin/sh", "-c",
      "kubectl create token limited-sa --duration=300s > /shared/app-token"]
    volumeMounts:
    - name: shared
      mountPath: /shared
  containers:
  - name: app
    env:
    - name: KUBE_TOKEN_FILE
      value: /shared/app-token        # use limited scoped token
    volumeMounts:
    - name: shared
      mountPath: /shared
  volumes:
  - name: shared
    emptyDir:
      medium: Memory                  # tmpfs — not written to disk

Pattern: SA Token for External Vault Auth

Copy# Pod requests a token with custom audience for Vault
volumes:
- name: vault-token
  projected:
    sources:
    - serviceAccountToken:
        path: token
        expirationSeconds: 7200
        audience: "vault"             # Vault configured with this audience

# Vault Kubernetes auth method verifies the token:
# vault write auth/kubernetes/login \
#   role=my-app \
#   jwt="$(cat /var/run/secrets/vault/token)"

Pattern: Minimal SA for Read-Only Workloads

Copy# Workloads that don't need API access at all
# (web servers, workers, batch jobs — the majority of workloads)

# 1. Disable default SA automount in the namespace
kubectl patch serviceaccount default -n production \
  -p '{"automountServiceAccountToken": false}'

# 2. Don't create a dedicated SA for pods that don't need API access
# They'll use 'default' SA with automount=false → no token at all

# 3. Only create dedicated SAs for workloads that need API access
kubectl create serviceaccount my-operator -n production

TokenReview API

The TokenReview API allows external systems (or admission webhooks) to validate a Kubernetes SA token and determine the associated identity. This is used by Vault's Kubernetes auth method, OIDC proxies, and custom authentication systems.

Copy# TokenReview request
apiVersion: authentication.k8s.io/v1
kind: TokenReview
spec:
  token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  audiences:                          # optional: validate against specific audiences
  - "https://kubernetes.default.svc"

Copy# Validate a token using kubectl
kubectl create -f - <

Copy# RBAC needed to call TokenReview
rules:
- apiGroups: ["authentication.k8s.io"]
  resources: ["tokenreviews"]
  verbs: ["create"]
# The system:auth-delegator ClusterRole grants this
# Used by: extension API servers, webhook authenticators, Vault K8s auth

Copy# List all roles bound to a specific SA
rbac-lookup prometheus -n monitoring -k sa

# Check what a specific SA can do
kubectl auth can-i --list \
  --as=system:serviceaccount:production:my-app \
  -n production

# Find SAs with cluster-admin binding
kubectl get clusterrolebindings -o json | \
  jq -r '.items[] | select(.roleRef.name=="cluster-admin") |
  "\(.metadata.name): \(.subjects[].kind)/\(.subjects[].namespace // "cluster")/\(.subjects[].name)"'

# Find all SAs that can list secrets
kubectl get rolebindings,clusterrolebindings --all-namespaces -o json | \
  jq -r '.items[] | select(.subjects[]?.kind=="ServiceAccount") |
  "\(.metadata.namespace)/\(.metadata.name) → \(.roleRef.name)"'

Copy# Find all legacy SA token secrets (should migrate to bound tokens)
kubectl get secrets --all-namespaces \
  --field-selector type=kubernetes.io/service-account-token \
  -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,SA:.metadata.annotations.kubernetes\.io/service-account\.name'

# Check when legacy tokens were last used (1.26+ with LegacyServiceAccountTokenTracking)
kubectl get secrets --all-namespaces \
  --field-selector type=kubernetes.io/service-account-token \
  -o json | jq -r '.items[] |
  "\(.metadata.namespace)/\(.metadata.name): last-used=\(.metadata.annotations["kubernetes.io/legacy-token-last-used"] // "never")"'

Copy# Full access matrix for a SA
rakkess --sa my-app -n production

# Compare permissions of two SAs
rakkess --sa my-app -n production > /tmp/my-app-perms.txt
rakkess --sa other-app -n staging > /tmp/other-app-perms.txt
diff /tmp/my-app-perms.txt /tmp/other-app-perms.txt

Copy# Find API calls made by a specific SA (from audit log)
cat audit.log | jq -c 'select(
  .user.username == "system:serviceaccount:production:my-app"
) | {verb, resource: .objectRef.resource, namespace: .objectRef.namespace, responseCode}'

# Find SAs making unexpected API calls (e.g., listing secrets)
cat audit.log | jq -c 'select(
  (.user.username | startswith("system:serviceaccount:")) and
  .objectRef.resource == "secrets" and
  .verb == "list"
)'

# Find pods that have accessed the K8s API (via user-agent of client-go)
cat audit.log | jq -c 'select(
  .userAgent | test("kube-apiserver-admission|kubectl") | not
) | {user: .user.username, verb, resource: .objectRef.resource}'

Copygroups:
- name: serviceaccount.rules
  rules:

  - alert: LegacyServiceAccountTokensInUse
    expr: serviceaccount_legacy_tokens_total > 0
    for: 24h
    annotations:
      summary: "{{ $value }} legacy (non-expiring) SA tokens still in use"
      description: "Migrate to bound projected tokens. Find via: kubectl get secrets --field-selector type=kubernetes.io/service-account-token"
    labels:
      severity: warning

  - alert: DefaultServiceAccountUsed
    # Implement via audit log: user.username=system:serviceaccount:*:default
    # and verb != "get" (some read-only access may be acceptable)
    annotations:
      summary: "Pod using default ServiceAccount made API call: {{ $labels.namespace }}"
    labels:
      severity: warning

  - alert: ServiceAccountAPICallRateHigh
    expr: |
      rate(apiserver_request_total{user=~"system:serviceaccount:.*"}[5m]) > 100
    for: 5m
    annotations:
      summary: "SA {{ $labels.user }} making >100 API calls/sec — possible runaway controller"
    labels:
      severity: warning

  - alert: UnexpectedSecretsListBySA
    # Via audit log: verb=list, resource=secrets, user=system:serviceaccount:*
    annotations:
      summary: "SA {{ $labels.user }} listed secrets — verify this is expected"
    labels:
      severity: high