Kubernetes authentication resources ——Detailed explanation of SubjectAccessReview

1. Overview

In a Kubernetes cluster,AuthorizationIt is one of the core mechanisms for ensuring safety. Whether it is a user, ServiceAccount or automation tool, the operation of resources requires strict permission control. SubjectAccessReview is a dynamic authentication resource provided by Kubernetes, allowing developers or administrators toVerify in real time whether a principal has permission to perform specific operations. This article will deeply analyze the design principles, usage methods and actual scenarios of SubjectAccessReview to help you thoroughly master this key authentication tool.

Note: In SubjectAccessReview, the meaning of the word "Review" is more inclined toRevieworReview。

2. What is SubjectAccessReview

2.1 Definition and Positioning

2.2 Core Value

1. Permission pre-check: Verify permissions before the operation is executed to avoid failure due to insufficient permissions.

2. Security Audit: Record the results of permission inspections for post-audit audits or compliance reports.

3. Dynamic authorization: Combined with a Webhook or a custom controller to achieve flexible access control logic.

3. How does SubjectAccessReview work

3.1 Request and Response Process

+-----------------+    (1) create SubjectAccessReview ask   +----------------+
|   Client         | ------------------------------------> |   API Server   |
| （External Services/tool）  |                                       | （Authorization module processing） |
+-----------------+ <------------------------------------ +----------------+
                      (2) Return permission check results（allowed/denied）

1. Client initiates a request: The client constructs a SubjectAccessReview object, specifying the subject and operation to be verified.
2. API Server processing: The authorization module of API Server (such as RBAC, Webhook) verify permissions according to the rules.
3. Return result: API Server returns allowed or denied with the decision reason.

3.2 Core field analysis

Request structure:

apiVersion: authorization./v1
kind: SubjectAccessReview
spec:
  user: "username"                # Username to check (optional)  groups: ["group1", "group2"]    # The group to which the user belongs (optional)  uid: "user-uid"                 # User unique ID (optional)  extra:                          # Additional information (such as fields in a certificate)    key: ["value"]
  resourceAttributes:             # Resource level operation check    namespace: "default"          # Namespace (optional)    verb: "get"                   # Operation type (required)    group: "apps"                 # API group (such as apps/v1)    resource: "deployments"       # Resource type (such as deployments)    name: "my-deployment"         # Resource name (optional)    subresource: "status"         # Subresources (such as pods/exec)  nonResourceAttributes:          # Non-resource operation check (such as accessing /healthz)    path: "/healthz"              # Path    verb: "get"                   # Operation Type

Response structure:

status:
  allowed: true           # Whether to allow operations  denied: false           # Whether to explicitly reject (priority higher than allowed)  reason: "User can list pods"  # Decision-making reasons  evaluationError: ""     # Check the errors (such as configuration errors)

4. Use scenarios and cases

Scenario 1: Permission pre-check in the CI/CD pipeline

Before deploying the application to the cluster, verify that the ServiceAccount used by the CI/CD tool has permission to create a Deployment.

Sample request:

apiVersion: authorization./v1
kind: SubjectAccessReview
spec:
  user: "system:serviceaccount:ci-cd:tekton"  # CI/CD ServiceAccount  resourceAttributes:
    namespace: "prod"
    verb: "create"
    group: "apps"
    resource: "deployments"

Response results:

status:
  allowed: true
  reason: "RBAC: allowed by ClusterRoleBinding 'tekton-deployer'"

Scenario 2: Dynamic authentication of custom access controllers

In the Admission Controller, a fine-grained access control is achieved in combination with SubjectAccessReview. For example, a specific user is forbidden to delete a production environment's ConfigMap.

Example logic:

// Triggered when processing a delete request in a webhookif  == "DELETE" &&  == "configmaps" {
    sar := &{
        Spec: {
            User: ,
            Groups: ,
            ResourceAttributes: &{
                Namespace: ,
                Verb:      "delete",
                Group:     "",
                Resource:  "configmaps",
                Name:      ,
            },
        },
    }
    // Call the Kubernetes API to perform authentication    response, err := clientset.AuthorizationV1().SubjectAccessReviews().Create(ctx, sar, {})
    if ! {
        return deny("User not allowed to delete this ConfigMap")
    }
}

Script example:

# Get all ServiceAccountskubectl get serviceaccounts --all-namespaces -o jsonpath='{range .items[*]}{.}/{.}{"\n"}{end}' > 

# traverse and check permissions for each SAwhile read sa; do
    namespace=$(echo $sa | cut -d/ -f1)
    name=$(echo $sa | cut -d/ -f2)
    kubectl create -f - <<EOF
apiVersion: authorization./v1
kind: SubjectAccessReview
spec:
  user: "system:serviceaccount:${namespace}:${name}"
  resourceAttributes:
    verb: "*"
    group: "*"
    resource: "*"

To call SubjectAccessReview, the client must have create permissions.

Here is an example of ClusterRole:

apiVersion: ./v1
kind: ClusterRole
metadata:
  name: access-reviewer
rules:
- apiGroups: ["authorization."]
  resources: ["SubjectAccessReviews"]
  verbs: ["create"]  # Must be authorized create

The decision results of SubjectAccessReview are directly affected by RBAC rules. For example, if a ClusterRole allows the user to get pods, the corresponding SubjectAccessReview request will return allowed: true.

6. Advanced features and skills

Tips 1: Check non-resource operations

Verify that the user has permission to access a non-resource API path (such as /healthz):

apiVersion: authorization./v1
kind: SubjectAccessReview
spec:
  user: "alice"
  nonResourceAttributes:
    path: "/healthz"
    verb: "get"

Tip 2: Use extra fields to pass context information

In OpenID Connect (OIDC) authentication, additional declarations in the token can be passed through extra:

spec:
  user: "alice"
  extra:
    "oidc-claim/roles": ["cluster-admin"]
  resourceAttributes:
    verb: "update"
    resource: "nodes"

7. Frequently Asked Questions and Solutions

Question 1: Error: MethodNotAllowed

• reason: Not usedPOSTMethod Call API.

• solve: Make sure to use kubectl create -f or curl -X POST.

Question 2: Error: Forbidden

• reason: The client does not have create SubjectAccessReviews permission.

• solve: Bind ClusterRole (see Section 4).

Question 3: The results do not meet expectations

• Checkpoint：

  1. Whether the RBAC rules are correctly defined.

  2. Whether the group, resource, and verb in the request match the resource.

  3. Whether namespace is missing (namespace scope resource must be specified).

8. Performance and best practices

Performance optimization

• Batch inspection: Avoid high-frequency single requests, and can be optimized through batch queries or cached results.

• Reduce redundant checking: In the CI/CD process, the authentication results are cached for repeated operations of the same SA.

Safety practice

• Minimum permission principle: Regularly review the use permissions of SubjectAccessReview.

• Log Audit: Record all authentication requests in conjunction with Kubernetes audit logs.

9. Summary

SubjectAccessReview is a "permission detector" in the Kubernetes authorization system. It provides flexibility and real-time functionality for cluster security through dynamic query mechanism. Whether it is permission pre-checking, security auditing for automated processes, or the implementation of customized access control, SubjectAccessReview is an indispensable tool. Mastering its usage can significantly improve the security and efficiency of cluster management.

Through the detailed explanation of this article, I hope you can be at ease in the following scenarios:

• Pre-check permissions: Ensure permissions compliant before critical operations.

• Debugging Authorization: Quickly locate RBAC configuration issues.

• Build security tools: Develop custom monitoring or auditing systems.