Add non-resource and API group support to ABAC authorizer, version ABAC policy rules

docs/admin/authorization.md

@@ -57,16 +57,18 @@ The following implementations are available, and are selected by flag:
 
 ### Request Attributes
 
-A request has 5 attributes that can be considered for authorization:
+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).
-  - whether the request is readonly (GETs are readonly).
-  - what resource is being accessed.
-    - applies only to the API endpoints, such as
-        `/api/v1/namespaces/default/pods`.  For miscellaneous endpoints, like `/version`, the
-        resource is the empty string.
-  - the namespace of the object being access, or the empty string if the
-        endpoint does not support namespaced objects.
+  - whether the request is for an API resource.
+  - the request path.
+    - allows authorizing access to miscellaneous endpoints like `/api` or `/healthz` (see [kubectl](#kubectl)).
+  - the request verb.
+    - API verbs like `get`, `list`, `create`, `update`, and `watch` are used for API requests
+    - HTTP verbs like `get`, `post`, and `put` are used for non-API requests
+  - what resource is being accessed (for API requests only)
+  - the namespace of the object being accessed (for namespaced API requests only)
+  - the API group being accessed (for API requests only)
 
 We anticipate adding more attributes to allow finer grained access control and
 to assist in policy management.
@@ -79,18 +81,29 @@ The file format is [one JSON object per line](http://jsonlines.org/).  There sho
 one map per line.
 
 Each line is a "policy object".  A policy object is a map with the following properties:
-  - `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user.
-  - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user.
-  - `readonly`, type boolean, when true, means that the policy only applies to GET
-      operations.
-  - `resource`, type string; a resource from an URL, such as `pods`.
-  - `namespace`, type string; a namespace string.
+  - Versioning properties:
+    - `apiVersion`, type string; valid values are "abac.authorization.kubernetes.io/v1beta1". Allows versioning and conversion of the policy format.
+    - `kind`, type string: valid values are "Policy". Allows versioning and conversion of the policy format.
+
+  - `spec` property set to a map with the following properties:
+    - Subject-matching properties:
+      - `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user. `*` matches all requests.
+      - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user. `*` matches all requests.
+
+    - `readonly`, type boolean, when true, means that the policy only applies to get, list, and watch operations.
+
+    - Resource-matching properties:
+      - `apiGroup`, type string; an API group, such as `extensions`. `*` matches all API groups.
+      - `namespace`, type string; a namespace string. `*` matches all resource requests.
+      - `resource`, type string; a resource, such as `pods`. `*` matches all resource requests.
+
+    - Non-resource-matching properties:
+    - `nonResourcePath`, type string; matches the non-resource request paths (like `/version` and `/apis`). `*` matches all non-resource requests. `/foo/*` matches `/foo/` and all of its subpaths.
 
 An unset property is the same as a property set to the zero value for its type (e.g. empty string, 0, false).
 However, unset should be preferred for readability.
 
-In the future, policies may be expressed in a JSON format, and managed via a REST
-interface.
+In the future, policies may be expressed in a JSON format, and managed via a REST interface.
 
 ### Authorization Algorithm
 
@@ -99,21 +112,35 @@ 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).
 
-An unset property will match any value of the corresponding
-attribute.  An unset attribute will match any value of the corresponding property.
+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 unset.
-To permit an action Policy with an unset namespace applies regardless of namespace.
+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 "*".
+
+### Kubectl
+
+Kubectl uses the `/api` and `/apis` endpoints of api-server to negotiate client/server versions. To validate objects sent to the API by create/update operations, kubectl queries certain swagger resources. For API version `v1` those would be `/swaggerapi/api/v1` & `/swaggerapi/experimental/v1`.
+
+When using ABAC authorization, those special resources have to be explicitly exposed via the `nonResourcePath` property in a policy (see [examples](#examples) below):
+
+* `/api`, `/api/*`, `/apis`, and `/apis/*` for API version negotiation.
+* `/version` for retrieving the server version via `kubectl version`.
+* `/swaggerapi/*` for create/update operations.
+
+To inspect the HTTP calls involved in a specific kubectl operation you can turn up the verbosity:
+
+    kubectl --v=8 version
 
 ### Examples
 
- 1. Alice can do anything: `{"user":"alice"}`
- 2. Kubelet can read any pods: `{"user":"kubelet", "resource": "pods", "readonly": true}`
- 3. Kubelet can read and write events: `{"user":"kubelet", "resource": "events"}`
- 4. Bob can just read pods in namespace "projectCaribou": `{"user":"bob", "resource": "pods", "readonly": true, "namespace": "projectCaribou"}`
+ 1. Alice can do anything to all resources:                  `{"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}}`
+ 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"}}`
+ 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}}`
+ 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": "*"}}`
 
 [Complete file example](http://releases.k8s.io/HEAD/pkg/auth/authorizer/abac/example_policy_file.jsonl)
 
@@ -134,7 +161,7 @@ system:serviceaccount:<namespace>:default
 For example, if you wanted to grant the default service account in the kube-system full privilege to the API, you would add this line to your policy file:
 
 ```json
-{"user":"system:serviceaccount:kube-system:default"}
+{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"}
 ```
 
 The apiserver will need to be restarted to pickup the new policy lines.