Merge pull request #946 from InQuicker/authz-verbs

Authz: Explain how to determine request verbs.

docs/admin/authorization.md

@@ -37,30 +37,36 @@ If multiple modes are provided the set is unioned, and only a single authorizer
 
 will always allow.
 
-## ABAC Mode
+## Request Attributes
-
-### Request Attributes
 
 A request has the following attributes that can be considered for authorization:
 
   - user (the user-string which a user was authenticated as).
   - group (the list of group names the authenticated user is a member of).
+  - "extra" (a map of arbitrary string keys to string values, provided by the authentication layer)
   - whether the request is for an API resource.
   - the request path.
-    - allows authorizing access to miscellaneous endpoints like `/api` or
+    - allows authorizing access to miscellaneous non-resource endpoints like `/api` or `/healthz` (see [kubectl](#kubectl)).
-`/healthz` (see [kubectl](#kubectl)).
   - the request verb.
-    - API verbs like `get`, `list`, `create`, `update`, `watch`, `delete`, and
+    - API verbs `get`, `list`, `create`, `update`, `patch`, `watch`, `proxy`, `redirect`, `delete`, and `deletecollection` are used for resource requests
-`deletecollection` are used for API requests
+    - HTTP verbs `get`, `post`, `put`, and `delete` are used for non-resource requests
-    - HTTP verbs like `get`, `post`, `put`, and `delete` are used for non-API
+  - what resource is being accessed (for resource requests only)
-requests
+  - what subresource is being accessed (for resource requests only)
-  - what resource is being accessed (for API requests only)
+  - the namespace of the object being accessed (for namespaced resource requests only)
-  - the namespace of the object being accessed (for namespaced API requests
+  - the API group being accessed (for resource requests only)
-only)
-  - the API group being accessed (for API requests only)
 
-We anticipate adding more attributes to allow finer grained access control and
+The request verb for a resource API endpoint can be determined by the HTTP verb used and whether or not the request acts on an individual resource or a collection of resources:
-to assist in policy management.
+
+HTTP verb | request verb
+----------|---------------
+POST      | create
+GET, HEAD | get (for individual resources), list (for collections)
+PUT       | update
+PATCH     | patch
+DELETE    | delete (for individual resources), deletecollection (for collections)
+
+
+## ABAC Mode
 
 ### Policy File Format
 
@@ -101,17 +107,17 @@ A request has attributes which correspond to the properties of a policy object.
 When a request is received, the attributes are determined.  Unknown attributes
 are set to the zero value of its type (e.g. empty string, 0, false).
 
-A property set to "*" will match any value of the corresponding attribute.
+A property set to `"*"` will match any value of the corresponding attribute.
 
 The tuple of attributes is checked for a match against every policy in the
 policy file. If at least one line matches the request attributes, then the
 request is authorized (but may fail later validation).
 
 To permit any user to do something, write a policy with the user property set to
-"*".
+`"*"`.
 
 To permit a user to do anything, write a policy with the apiGroup, namespace,
-resource, and nonResourcePath properties set to "*".
+resource, and nonResourcePath properties set to `"*"`.
 
 ### Kubectl
 
@@ -134,11 +140,31 @@ up the verbosity:
 
 ### Examples
 
- 1. Alice can do anything to all resources:                  `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}`
+ 1. Alice can do anything to all resources:
- 2. Kubelet can read any pods:                               `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}`
+
- 3. Kubelet can read and write events:                       `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}`
+    ```json
- 4. Bob can just read pods in namespace "projectCaribou":    `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}`
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}
- 5. Anyone can make read-only requests to all non-API paths: `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "*", "readonly": true, "nonResourcePath": "*"}}`
+    ```
+ 2. Kubelet can read any pods:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}}
+    ```
+ 3. Kubelet can read and write events:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}}
+    ```
+ 4. Bob can just read pods in namespace "projectCaribou":
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}}
+    ```
+ 5. Anyone can make read-only requests to all non-resource paths:
+
+    ```json
+    {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "*", "readonly": true, "nonResourcePath": "*"}}
+    ```
 
 [Complete file example](http://releases.k8s.io/{{page.githubbranch}}/pkg/auth/authorizer/abac/example_policy_file.jsonl)
 
@@ -151,7 +177,7 @@ according to the naming convention:
 system:serviceaccount:<namespace>:<serviceaccountname>
 ```
 Creating a new namespace also causes a new service account to be created, of
-this form:*
+this form:
 
 ```shell
 system:serviceaccount:<namespace>:default