Basic ACL file.

Added function to read basic ACL from a CSV file.
Added implementation of Authorize based on that file's policies.
Added docs on authentication and authorization.
Added example file and tested it.

docs/authentication.md

@@ -0,0 +1,19 @@
+# Authentication Plugins
+
+Kubernetes uses tokens to authenticate users for API calls.
+
+Authentication is enabled by passing the `--token_auth_file=SOMEFILE` option
+to apiserver.  Currently, tokens last indefinitely, and the token list cannot
+be changed without restarting apiserver.  We plan in the future for tokens to
+be short-lived, and to be generated as needed rather than stored in a file.
+
+The token file format is implemented in `pkg/auth/authenticator/tokenfile/...`
+and is a csv file with 3 columns: token, user name, user uid.
+
+## Plugin Development
+
+We plan for the Kubernetes API server to issue tokens
+after the user has been (re)authenticated by a *bedrock* authentication
+provider external to Kubernetes.  We plan to make it easy to develop modules
+that interface between kubernetes and a bedrock authentication provider (e.g.
+github.com, google.com, enterprise directory, kerberos, etc.)  

docs/authorization.md

@@ -0,0 +1,103 @@
+# Authorization Plugins
+
+
+In Kubernetes, authorization happens as a separate step from authentication.
+See the [authentication documentation](../authn_plugins/README.md) for an 
+overview of authentication.
+
+Authorization applies to all HTTP accesses on the main apiserver port. (The
+readonly port is not currently subject to authorization, but is planned to be
+removed soon.)
+
+The authorization check for any request compares attributes of the context of
+the request, (such as user, resource kind, and namespace) with access
+policies.  An API call must be allowed by some policy in order to proceed.
+
+The following implementations are available, and are selected by flag:
+  - `--authoriation_mode=AlwaysDeny`
+  - `--authoriation_mode=AlwaysAllow`
+  - `--authoriation_mode=ABAC`
+
+`AlwaysDeny` blocks all requests (used in tests).
+`AlwaysAllow` allows all requests; use if you don't need authorization.
+`ABAC` allows for user-configured authorization policy.  ABAC stands for Attribute-Based Access Control.
+
+## ABAC Mode
+### Request Attributes
+
+A request has 4 attributes that can be considered for authorization:
+  - user (the user-string which a user was authenticated as).
+  - whether the request is readonly (GETs are readonly)
+  - what kind of object is being accessed 
+    - applies only to the API endpoints, such as 
+        `/api/v1beta1/pods`.  For miscelaneous endpoints, like `/version`, the
+        kind is the empty string.
+  - the namespace of the object being access, or the empty string if the
+        endpoint does not support namespaced objects.
+
+We anticipate adding more attributes to allow finer grained access control and
+to assist in policy management.
+
+### Policy File Format
+
+For mode `ABAC`, also specify `--authorization_policy_file=SOME_FILENAME`.
+
+The file format is [one JSON object per line](http://jsonlines.org/).  There should be no enclosing list or map, just
+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`
+    - `readonly`, type boolean, when true, means that the policy only applies to GET
+      operations.
+    - `kind`, type string; a kind of object, from an URL, such as `pods`.
+    - `namespace`, type string; a namespace string.
+
+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.
+
+### Authorization Algorithm
+
+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.
+
+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.
+
+### Examples
+ 1. Alice can do anything: `{"user":"alice"}`
+ 2. Kubelet can read any pods: `{"user":"kubelet", "kind": "pods", "readonly": true}`
+ 3. Kubelet can read and write events: `{"user":"kubelet", "kind": "events"}`
+ 4. Bob can just read pods in namespace "projectCaribou": `{"user":"bob", "kind": "pods", "readonly": true, "ns": "projectCaribou"}`
+
+[Complete file example](../pkg/auth/authorizer/abac/example_policy_file.jsonl)
+
+## Plugin Developement
+
+Other implementations can be developed fairly easily.
+The APIserver calls the Authorizer interface:
+```go
+type Authorizer interface {
+  Authorize(a Attributes) error
+}
+```
+to determine whether or not to allow each API action.
+
+An authorization plugin is a module that implements this interface.
+Authorization plugin code goes in `pkg/auth/authorization/$MODULENAME`.
+
+An authorization module can be completely implemented in go, or can call out
+to a remote authorization service.  Authorization modules can implement
+their own caching to reduce the cost of repeated authorization calls with the
+same or similar arguments.  Developers should then consider the interaction between
+caching and revokation of permissions.