revise docs to reflect ACM design, upate terms.

docs/Collab-Spaces-APIs.rst

@@ -2,6 +2,9 @@
 Collaboration Spaces APIs
 ===========================
 
+.. attention:: This document has been superseded by the Access Control Manager documentation referred to in the
+   UAA-CC-ACM-VMC-Interactions document.
+
 .. contents:: Table of Contents
 
 .. .. sectnum::

docs/Collab-Spaces-Model.rst

@@ -2,6 +2,10 @@
 Collaboration Spaces Model
 ============================
 
+.. attention:: This document was current as of Sept 2011 and has been superseded by the Access Control Manager documentation 
+   referred to in the UAA-CC-ACM-VMC-Interactions document as of Nov 2011. However, many of the requirements, principles and 
+   goals of this document are still valid and are left here until this document is refactored into a new form. 
+
 .. contents:: Table of Contents
 
 Introduction

docs/UAA-APIs.md

@@ -58,6 +58,15 @@ The `/userinfo`, `/check_id`, and `/token` endpoints are specified in the [OpenI
 [OAuth2]: http://tools.ietf.org/html/draft-ietf-oauth-v2-22 "OAuth2, draft 22"
 [OpenID Connect]: http://openid.net/openid-connect "OpenID Connect Spec Suite"
 
+## A Note on OAuth Scope
+
+The OAuth2 spec includes a `scope` parameter as part of the token granting request (actually it is a set of scope values).  The spec leaves the business content of the scope up to the participants in the protocol - i.e. the scope values are completely arbitrary and can in principle be chosen by any Resource Server using the tokens.  Clients of the Resource Server have to ask for a valid scope to get a token, but the Authorization Server itself attaches no meaning to the scope - it just passes the value through to the Resource Server.  The UAA implementation of the Authorization Server has a couple of extra scope-related features (by virtue of being implemented in Spring Security where the features originate).
+
+1. There is an optional step in client registration, where a client declares which scopes it will ask for, or alternatively where the Authorization Server can limit the scopes it can ask for. The Authorization Server can then check that token requests contain a valid scope (i.e. one of the set provided on registration).
+
+2. The Resource Servers can each have a unique ID (e.g. a URI). And aother optional part of a client registration is to provide a set of allowed resource ids for the client in question.  The Authorization Server binds the allowed resource ids to the token and then provides the information via the `/check_token` endpoint, so that a Resource Server can check that its own ID is on the allowed list for the token before serving a resource.
+
+Resource IDs have some of the character of a scope, except that the clients themselves don't need to know about them - it is information exchanged between the Authorization and Resource Servers.  The examples in this document use a `scope` parameter that is obvisouly itself a URI, e.g. for a Cloud Controller instance. This is a suggested usage, but whether it is adopted by the real Cloud Controller is not crucial to the system.  Similarly any Resource Server that wants to can check the allowed resource IDs if there are any, but it is not mandatory to do so.
 
 ### <a id="authorize"/>OAuth2 Authorization Approval
 
@@ -73,8 +82,6 @@ N.B. a GET is used in the [relevant section](http://tools.ietf.org/html/draft-ie
 
 All requests to this endpoint MUST be over SSL. 
 
-For our initial use we will use the OAuth2 `scope` parameter to bind any resulting access\_tokens to a cloud foundry instance. In the future scopes could be further refined such that the user could restrict the authorizations represented by the access\_token to a specific subset of resources (such as within an Org) or to a subset of permissions (such as read-only).
-
 ### Implicit Grant
 
 * Request: `POST /authorize`
@@ -158,9 +165,9 @@ An endpoint that allows a resource server such as the cloud controller to valida
 
 OAuth2 access\_tokens could contain all needed information such as userID, scope(s), lifetime, user attributes and be encrypted with the resource server's (e.g. cloud countroller's) secret key. That way the resource server could validate and use the token with no contact with the UAA. However, it may be useful -- at least during development -- for the UAA to specify a short, opaque token and then provide a way for the resource server to return it to the UAA to validate and open. That is what this endpoint does. It does not return general user account information like the /userinfo endpoint, it is specifically to validate and return the information represented by access\_token that the user presented to the resource server.
 
-This endpoint mirrors the OpenID Connect `/check_id` endpoint, so not very RESTful, but we want to make it look and feel like the others. 
+This endpoint mirrors the OpenID Connect `/check_id` endpoint, so not very RESTful, but we want to make it look and feel like the others. The endpoint is not part of any spec, but it is a useful took to have for anyone implementing an OAuth2 Resource Server.
 
-* Request: the basic authorization is as per OAuth2 spec, assuming the resource server is a registered client: `base64(resource_server:shared_secret)`
+* Request: the basic authorization is as per OAuth2 spec, assuming the caller (a resource server) is a registered client: `base64(resource_server:shared_secret)`
 
         POST /check_token HTTP/1.1
         Host: server.example.com
@@ -175,11 +182,25 @@ This endpoint mirrors the OpenID Connect `/check_id` endpoint, so not very RESTf
         Content-Type: application/json
 
         {
-            "user_id":"9017092310y301qhe",
-            "user_name":"bjensen",
+            "user_id":"bjensen",
+			"id":9017092310y301qhe",
             "scope": "https://api.cloudfoundry.example.com",
-            "expiration": "231231231231"
+            "expiration": "231231231231",
+			"email":"bjensen@example.com",
+			"user_authorities":["ROLE_USER"],
+			"resource_ids":["https://api.cloudfoundry.example.com", "https://www.cloudfoundry.example.com"],
+			"client_id":"vmc",
+			"client_secret":"KHfdsfjahsdgfkj=",
+			"client_authorities":["ROLE_CLIENT"]
         }
+		
+    Notes:
+
+    * The `user_id` is the same as you get from the (OpenID Connect) `/userinfo` endpoint.  The `id` field is the same as you would use to get the full user profile from `/User`.
+
+    * Many of the fields in the response are a courtesy allow the caller to avoid further round trip queries to pick up the same information (e.g. via the `/User` endpoint).  
+
+    * The `client_*` data represent the client that the token was granted for, not the caller.  They can be used by the caller, for example, to verify that the client has been granted permission to access a resource.
 
 * Error Responses: see [OAuth2 Error reponses](http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-5.2) and this addition:
 
@@ -223,7 +244,7 @@ An OAuth2 protected resource and an OpenID Connect endpoint. Given an appropriat
 
         {
 		  "user_id":"olds",
-		  "email":olds@vmare.com
+		  "email":"olds@vmare.com"
         }
 
 ### <a id="login_info"/>Login Information Endpoint
@@ -241,8 +262,8 @@ This call will be unauthenticated.
 
         "prompt": {
             "email":["text", "validated email address"],
-            "password": ["hidden", "your UAA password" ]
-            "otp":["hidden", "security code"],
+            "password": ["password", "your UAA password" ]
+            "otp":["password", "security code"],
         }
 
 
@@ -322,7 +343,7 @@ See [SCIM - Modifying with PUT](http://www.simplecloud.info/specs/draft-scim-res
 
         {
           "schemas":["urn:scim:schemas:core:1.0"],
-          "id":"uid=bjensen,dc=example,dc=com",
+          "id":"123456",
           "userName":"bjensen",
           "externalId":"bjensen",
           "name":{
@@ -344,6 +365,7 @@ See [SCIM - Modifying with PUT](http://www.simplecloud.info/specs/draft-scim-res
 
 * Response Body:
         As for create operation, returns the entire, updated record, with the Location header pointing to the resource.
+
 * Response Codes:
 
         200 - Updated successfully

docs/UAA-CC-ACM-VMC-Interactions.rst

@@ -0,0 +1,225 @@
+==============================================
+Interactions Between the UAA, CC, ACM and VMC
+==============================================
+
+.. contents:: Table of Contents
+
+Introduction
+=============
+
+This document describes interactions between 4 components:
+
+UAA - The `User Account and Authentication Service`_
+    A new, separate process accessible via HTTP endpoints.
+
+ACM - The `Access Control Manager`_
+    An initial collaboration spaces module to be included in the cloud controller.
+
+CC - The `Cloud Controller and Collaboration Spaces`_
+    What changes would be required to the existing code.
+
+VMC - The `VMC Command Line`_ tool
+    What changes would be required to existing code.
+
+After discussing each component we walk through a series of `vmc flows`_ of what happens for a specific set of operations. 
+
+Lastly we will illustrate `web application flows`_.
+
+The relationships between these components can be illustrated like this:
+
+.. image:: diagrams/UAA-CC-ACM-VMC.png
+    :alt: Interactions Block Diagram"
+
+User Account and Authentication Service
+========================================
+
+Overview
+--------------
+
+The User Account and Authentication Service (UAA) is:
+
+* A new, separate application from the Cloud Controller
+* Owns the user accounts and authentication sources
+* Called via REST APIs
+* Support for standard protocols to provide single sign-on and delegated 
+  authorization to web applications in addition to REST APIs to support 
+  the Cloud Controller and Collaboration Spaces
+
+For more information see the `UAA detailed API documentation <UAA-APIs>`_
+
+UAA and OAuth2 Scopes
+----------------------
+
+OAuth2 specifies that access tokens can bound to a set of strings called "scopes" -- the exact content and meaning
+of the scope is left to the UAA and any servers that will control access to resources. In some uses the scope is
+simply the URL of the resource server. Resource servers should only grant access that is with a scope that has been 
+authorized by the user -- which may be a more narrow scope than what the client application requested. 
+
+Initially we will use the scope parameter of OAuth to scope an access_token to a specific cloud foundry instance. The 
+UAA and all associated resource servers, e.g. cloud controller, need to agree on scope meanings. In our case, this 
+means that a resource server should check that the scope is their own URL. They should not honor access tokens for other scopes. 
+
+Access Control Manager
+==================================
+
+The Access Control Manager (ACM) `source code repository`__ contains a `detailed API document`__.
+
+__ https://github.com/vmware-ac/acm
+__ https://github.com/vmware-ac/acm/blob/master/docs/Access-Control-Manager-APIs.rst
+
+Overview
+----------
+
+The ACM:
+
+* contains a series of permission sets as defined by the ACM client.
+* contains a set of objects with access control lists (ACL). Entries in each ACL control when a user has a permission within a set that is allowed on that object.
+* contains a set of objects which represent groups. Access to the group and roup membership are controlled by the ACL in an associated object.
+* handles access control calculations for client services by calculating what permissions users have to specific objects.
+
+  - In the case of the cloud controller, objects may represent orgs or app spaces. However, the design
+    is intended to be as general as possible so that it an be used in other cloud foundry components
+    as well.
+
+* Configuration options
+
+  - Shared secret used for authentication by the client service.
+  - Database configuration
+
+Features
+----------
+
+Cloud foundry services want the ability to perform the following types of operations to enable
+collaboration spaces.
+
+* Control access to organizational objects such as Org, Groups, and App Spaces
+* Create and manage groups of users that can be used to manage access to Orgs and App Spaces
+* Assign permissions to organizational objects for specific users or groups.
+* Control what permissions are allowed and calculated for specific object ACLs.
+
+Cloud Controller and Collaboration Spaces
+================================================
+
+General Changes
+-----------------------------------------
+
+* Recognition that the user is operating in the context of a particular org and app space.
+
+    Each operation needs to recognize its org and project and operate in that context. 
+
+Database Changes
+-----------------------------------------
+
+* User accounts => orgs, add app spaces
+
+    Orgs will replace users as the owners of apps and services. Therefore the apps and services that
+    are currently linked to users will now be linked to orgs. The schema will need to be updated for
+    this.
+
+* New operation support
+
+    Cloud controller will need to support an info call per org that can return the URL of the UAA for that org.
+
+* User account updates
+
+    The ACM will only operate in terms of unique identifiers for users retrieved from the UAA.
+
+* Org and App Space object management within the ACM
+
+    The cloud controller will need to create permission sets for objects it wants to control access via the ACM. Then, for
+    each object such as an Org or App Space, it needs to create an object and record its ID in the CC database.
+
+Code changes
+-----------------------------------------
+
+* Authorize an operation
+
+    The cloud controller will need to make calls to the ACM to authorize each operation.
+
+* Add authorization filters
+
+* operate on object IDs based received from the ACM, and user ID received from token in the UAA. 
+
+New API endpoints of UAA and ACM
+----------------------------------------------------------
+
+* Create User, etc.
+* Manage ACLs and groups
+
+Resource Garbage Collection
+-----------------------------------------
+
+There are failure cases where resources can get out of sync between the CC and ACM. Need a periodic sync process to clean up dangling references. 
+
+VMC Command Line
+=====================================
+
+* Add orgs and appspaces to existing target contexts. vmc may need new options to simplify user's understanding of orgs and appspaces instead of just appending them to the URL of the cloud foundry instance.
+
+* Get UAA endpoint and process dynamic login info. vmc needs to be able to get the URL of the UAA for the target org and then request the login info from that UAA. It then needs to handle different prompt types to collect the users credentials and then request a token from the UAA. 
+
+* Each token needs to be stored with it's UAA and CFInstance URLs. When changing context to another org or project that uses the same UAA and CFInstance URLs, the user does not need to log in again but can continue to use the same token.
+
+* vmc would also need to communicate the org and appspace to the user in an info call as well as in the call to push so that the user is aware of the context that is being pushed to.
+
+A POC implementation of some of these changes, especially the interactions with the UAA and the dynamic login info is available here: https://github.com/daleolds/vmc .
+
+
+VMC Flows
+==================================
+
+Login flow for vmc to UAA, cloud controller and ACM:
+
+.. image:: diagrams/vmc-login-flow.png
+    :alt: vmc login block diagram
+
+Web sequence diagrams for various operations
+
+1. vmc login
+
+.. image:: diagrams/flow-login.png
+   :alt: vmc login
+   :target: diagrams/flow-login.txt
+
+2. vmc push app
+
+.. image:: diagrams/flow-push-app.png
+   :alt: vmc push app
+   :target: diagrams/flow-push-app.txt
+
+3. vmc delete app
+
+.. image:: diagrams/flow-delete-app.png
+   :alt: vmc delete app
+   :target: diagrams/flow-delete-app.txt
+
+#. `vmc login <diagrams/flow-login.png>`_ -- (`text <diagrams/flow-login.txt>`__)
+#. `vmc push app <diagrams/flow-push-app.png>`_ -- (`text <diagrams/flow-push-app.txt>`__)
+#. `vmc delete app <diagrams/flow-delete-app.png>`_ -- (`text <diagrams/flow-delete-app.txt>`__)
+#. `vmc create org <diagrams/flow-create-org.png>`_ -- (`text <diagrams/flow-create-org.txt>`__)
+#. `vmc add permissions <diagrams/flow-add-permissions.png>`_ -- (`text <diagrams/flow-add-permissions.txt>`__)
+#. `vmc bind service <diagrams/flow-bind-service.png>`_ -- (`text <diagrams/flow-bind-service.txt>`__)
+#. `bosh add stem_cell <diagrams/flow-bosh-add-stem.png>`_ -- (`text <diagrams/flow-bosh-add-stem.txt>`__)
+
+Web Application Flows
+======================================
+
+Delegated Access to Cloud Controller APIs
+-----------------------------------------
+
+.. image:: diagrams/delegated-access-to-cc.png
+    :alt: delegated access diagram
+
+SSO to CloudFoundry Support Apps
+-----------------------------------------
+
+.. image:: diagrams/sso-to-support-apps.png
+    :alt: sso diagram
+
+Open Issues
+========================================
+
+* New LDAP user -- expect UAA to be able to provide Just In Time provisioning, i.e. create an account as the user authenticates.
+* Design database user account migration
+* we have now allowed for multiple UAAs per CC/BOSH, but we should also support multiple CC/BOSH per UAA -- and should get single signon between them. Really need a refresh token. Need to consider OAuth2 authcode flow vs. implicit flow (as Dave has suggested). 
+* Need more info on BOSH model. Doesn't need Orgs, but has similar concepts of group/project, object/resource. BOSH could actually be an org within a CS instance also used by CC -- though more likely would want the separation of their own instance.