commit 999bf7b6cc0b9e859cac34d26856da1549a9694c
Author: Sofia Papagiannaki <spapagian@grnet.gr>
Date:   Thu Dec 5 13:59:22 2013 +0200

    docs: Rearrange pithos authorization design document

diff --git a/docs/design/pithos-view-authorization.rst b/docs/design/pithos-view-authorization.rst
index 0a9a29e..4dfa8b2 100644
--- a/docs/design/pithos-view-authorization.rst
+++ b/docs/design/pithos-view-authorization.rst
@@ -1,23 +1,76 @@
 Serve untrusted user content
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+The current document describes how the pithos view accesses the protected
+pithos resources and proposes a new design for granting access to
+the specific resources. It sketches implementation details and configuration
+concerns.
+
+Current state and shortcomings
+==============================
+
+Pithos in order to identify the user who requests to view a pithos resource
+uses the information stored by astakos in the cookie after a successful user
+authentication login.
+
+The main drawback of this design is that the pithos view which serves untrusted
+user content has access to the sensitive information stored in the cookie.
+
+Abstract
+========
+
 We want to serve untrusted user content in a domain which does not have access
-to sensitive information. The information used by pithos view is set by astakos
-in the cookie after a successful user authentication login. Starting from
-synnefo version 0.15, the pithos view will be deployed in a domain outside the
-astakos cookie domain. The current document describes how the pithos view can
-grant access to the protected pithos resources.
+to sensitive information. Therefore, we would like the pithos view to be
+deployed in a domain outside the astakos cookie domain.
+
+We propose a design for the pithos view to grant access to the
+access-restricted resource without consulting the cookie.
+
+Briefly the pithos view will request a short-term access token for a specific
+resource from astakos. Before requesting the access token, the view should
+obtain an authorization grant (authorization code) from astakos, which will be
+presented by the view during the request for the access token.
 
 The proposed scheme follows the guidelines of the OAuth 2.0 authentication
 framework as described in http://tools.ietf.org/html/rfc6749/.
 
-Briefly the pithos view requests a short-term access token for a specific
-resource from astakos. Before requesting the access token, the view obtains
-an authorization grant (authorization code) from astakos, which is then
-presented by the view during the request for the access token.
+Proposed changes
+================
+
+We propose to alter the view to obtain authorization according to the
+authorization code grant flow.
+
+The general flow includes the following steps:
+
+#. The user requests to view the content of the protected resource.
+#. The view requests an authorisation code from astakos by providing its
+   identifier, the requested scope, and a redirection URI.
+#. Astakos authenticates the user and validates that the redirection URI
+   matches with the registered redirect URIs of the view.
+   As far as the pithos view is considered a trusted client, astakos grants the
+   access request on behalf of the user.
+#. Astakos redirects the user-agent back to the view using the redirection URI
+   provided earlier. The redirection URI includes an authorisation code.
+#. The view requests an access token from astakos by including the
+   authorisation code in the request. The view also posts its client identifier
+   and its client secret in order to authenticate itself with astakos. It also
+   supplies the redirection URI used to obtain the authorisation code for
+   verification.
+#. Astakos authenticates the view, validates the authorization code,
+   and ensures that the redirection URI received matches the URI
+   used to redirect the client.
+   If valid, astakos responds back with an short-term access token.
+#. The view exchanges with astakos the access token for the information of the
+   user to whom the authoritativeness was granted.
+#. The view responds with the resource contents if the user has access to the
+   specific resource.
+
+Implementation details
+======================
 
 Pithos view registration to astakos
-===================================
+-----------------------------------
+
 The pithos view has to authenticate itself with astakos since the latter has to
 prevent serving requests by unknown/unauthorized clients.
 
@@ -39,7 +92,7 @@ For example::
 
 
 Configure view credentials in pithos
-====================================
+------------------------------------
 
 To set the credentials issued to pithos view in order to authenticate itself
 with astakos during the resource access token generation procedure we have to
@@ -51,36 +104,8 @@ For example::
 
     PITHOS_OAUTH2_CLIENT_CREDENTIALS = ('pithos-view', 12345)
 
-Authorization Code Grant Flow
-=============================
-The general flow includes the following steps:
-
-#. The user requests to view the content of the protected resource.
-#. The view requests an authorisation code from astakos by providing its
-   identifier, the requested scope, and a redirection URI.
-#. Astakos authenticates the user and validates that the redirection URI
-   matches with the registered redirect URIs of the view.
-   As far as the pithos view is considered a trusted client, astakos grants the
-   access request on behalf of the user.
-#. Astakos redirects the user-agent back to the view using the redirection URI
-   provided earlier. The redirection URI includes an authorisation code.
-#. The view requests an access token from astakos by including the
-   authorisation code in the request. The view also posts its client identifier
-   and its client secret in order to authenticate itself with astakos. It also
-   supplies the redirection URI used to obtain the authorisation code for
-   verification.
-#. Astakos authenticates the view, validates the authorization code,
-   and ensures that the redirection URI received matches the URI
-   used to redirect the client.
-   If valid, astakos responds back with an short-term access token.
-#. The view exchanges with astakos the access token for the information of the
-   user to whom the authoritativeness was granted.
-#. The view responds with the resource contents if the user has access to the
-   specific resource.
-
-
 Authorization code request
-==========================
+--------------------------
 
 The view receives a request without either an access token or an authorization
 code. In that case it redirects to astakos's authorization endpoint by adding
@@ -105,7 +130,7 @@ request using TLS (with extra line breaks for display purposes only)::
         Host: accounts.synnefo.live
 
 Access token request
-====================
+--------------------
 
 Astakos's authorization endpoint responses to a valid authorization code
 request by redirecting the user-agent back to the requested view
@@ -141,7 +166,7 @@ line breaks for display purposes only)::
 
 
 Access to the protected resource
-================================
+--------------------------------
 
 Astakos's token endpoint replies to a valid token request with a (200 OK)
 response::
@@ -182,7 +207,7 @@ to the requested resource the resource's data are returned, otherwise the
 access to resource is forbidden.
 
 Authorization code and access token invalidation
-================================================
+------------------------------------------------
 
 Authorization codes can be used only once (they are deleted after a
 successful token creation)
@@ -196,7 +221,7 @@ renewal.
 Expired tokens presented to the validation endpoint are also deleted.
 
 Authorization code and access token length
-==========================================
+------------------------------------------
 
 Authorization code length is adjustable by the
 ``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to
@@ -206,7 +231,7 @@ Token length is adjustable by the ``OAUTH2_TOKEN_LENGTH`` setting.
 By default it is set to 30 characters.
 
 Restrict file serving endpoints to a specific host
-==================================================
+--------------------------------------------------
 
 A new setting ``PITHOS_SERVE_API_DOMAIN`` has been introduced. When set,
 all api views that serve pithos file contents will be restricted to be served
