More Goals and less impl details of Authn.

Expanded discussion of projects in the REST API based on feedback.

docs/access.md

@@ -162,54 +162,53 @@ In the Simple Profile:
    - There is a single default `project`.  No need to specify `project` when making an API call.
 
 Project versus userAccount vs Labels:
-- `userAccount`s are intended for audit logging, and to define who has access to `project`s.
+- `userAccount`s are intended for audit logging (both name and UID should be logged), and to define who has access to `project`s.
 - `labels` (see docs/labels.md) should be used to distinguish pods, users, and other objects that cooperate towards a common goal but are different in some way, such as version, or responsibilities.  
 - `project`s provide a namespace for objects.
 
 
-how is `project` selected when making a REST call?
-- default to only project if there is only one.
+*To Be Determined*
+How is project selected when making a REST call?
+- subdomain, e.g. http://myproject.kubernetes.example.com
+  - In hosted environment, may need to avoid profane or vanity names.
+  - Requires that the apiservers be tied into DNS, which is onerous to configure in some environments. Nice in some contexts.
 - query parameter
-- subdomain, e.g. http://myproject.kubernetes.example.com.  nginx proxy can translate that to a query parameter
-  - Subdomains have potential scaling limits. If using project names to identify the domain, you have to defend against profane or vanity names, and probably support blacklist limits on new project names. In non-hosted environments is less of an issue. Requires that the apiservers be tied into DNS, which is onerous to configure in some environments. Nice in some contexts.
-- offering a project API scope /projects/<id>/<kubernetes api>
-- global access via globally unique id (where supported, which isn't very consistent today) /pods/<uuid>
+  - e.g. `/pods/<name>?project=<projectid>`
+  - tedious to add to every request, but necessary to disambiguate object names 
+- project in resource name 
+  - e.g. `/projects/<id>/<kubernetes api>`
 
 ## Authentication
 
+Goals for K8s authentication:
+- Include a built-in authentication system with no configuration required to use in single-user mode, and little configuration required to add several user accounts, and no https proxy required.
+- Allow for authentication to be handled by a system external to Kubernetes, to allow integration with existing to enterprise authorization systems.  The kubernetes project itself should avoid taking contributions of multiple authorization schemes.  Instead, a trusted proxy in front of the apiserver can be used to authenticate users.
+  - For organizations whose security requirements only allow FIPS compliant implementations (e.g. apache) for authentication.
+  - So the proxy can terminate SSL, and isolate the CA-signed certificate from less trusted, higher-touch APIserver.
+  - For organizations that already have existing SaaS web services (e.g. storage, VMs) and want a common authentication portal. 
+- Avoid mixing authentication and authorization, so that authorization policies be centrally managed, and to allow changes in authentication methods without affecting authorization code.
+
 Initially:
-- Use bearer tokens to authenticate users.  
-- Each API request must include a "Authorization: Bearer <token>" header.
-- A token identifies a particular `userAccount`.  
+- Tokens used to authenticate a user.
+- Long lived tokens identify a particular `userAccount`.  
 - Administrator utility generates tokens at cluster setup.
-- Tokens are long lived.
-- Tokens are just long random strings base64 encoded.  No content.
+- OAuth2.0 Bearer tokens protocol, http://tools.ietf.org/html/rfc6750
+- No scopes for tokens.  Authorization happens in the API server
+- Tokens dynamically generated by apiserver to identify pods which are making API calls.
+- Tokens checked in a module of the APIserver.  
+- Authentication in apiserver can be disabled by flag, to allow testing without authorization enabled, and to allow use of an authenticating proxy.  In this mode, a query parameter or header added by the proxy will identify the caller.
 
 Improvements:
-- make it harder for the wrong party to use the token.  
-  - shorter lived tokens
-  - use tokens that are bound to the channel between the client and the api server
+- Refresh of tokens.
+- SSH keys to access inside containers.
 
-Things to consider for Improved implementation:
-- JWT http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-13
-  - Possible library: http://code.google.com/p/goauth2/oauth/jwt
-  - Use with endpoint that generates short-term bearer token.
-- tokens that are bound to the channel between the client and the api server
+To be considered for subsequent versions:
+- Fuller use of OAuth (http://tools.ietf.org/html/rfc6749)
+- Scoped tokens.
+- Tokens that are bound to the channel between the client and the api server
      - http://www.ietf.org/proceedings/90/slides/slides-90-uta-0.pdf
      - http://www.browserauth.net
 
-Where to do authentication.  Either:
-- Authenticate in reverse proxy (currently nginx, could easily be apache+mod_auth).  Proxy either rejects invalid token or appends authorized_user identifier to the request before passing to APIserver.
-- Apiserver checks token.
-
-Considerations:
-- In some arrangements, the proxy might terminate SSL, and use a CA-signed certificate, while the APIserver might just use a self-signed or organization-signed certificate.
-- some large orgs will already have existing SaaS web services (e.g. storage, VMs).  Some will already have a gateway that handles auth for multiple services.  If K8s does auth in the proxy, then those orgs can just replace the proxy with their existing web service gateway.
-- Apache or nginx is more stable than K8s code.  Prefer to put secrets (tokens, SSL cert.) in lower-touch place.
-- Admins configuring K8s for enterprise use are more likely to know how to config a proxy than to modify Go code of apiserver. 
-
-Based on above considerations, auth should happen in the proxy.
-
 
 ## Authorization