Commit 6d965b36 authored by Constantinos Venetsanopoulos's avatar Constantinos Venetsanopoulos
Browse files

docs: minor fixes in Pithos view design doc

Also rename it to "pithos-separate-view domain.rst"
parent f83ca2bd
Serve untrusted user content
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pithos separate view domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
This document describes how the Pithos view accesses the protected Pithos
resources and proposes a new design for granting access to 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. Therefore, we would like the pithos view to be
deployed in a domain outside the astakos cookie domain.
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
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
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/.
Current state and shortcomings
==============================
Until now, 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 Astakos
cookie.
Proposed changes
================
We propose to alter the view to obtain authorization according to the
We propose to alter the Pithos view to obtain authorization according to the
authorization code grant flow.
The general flow includes the following steps:
The general flow comprises 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
#. The user requests to view the content of a protected resource.
#. The view requests an authorization 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
Once 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
#. 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
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
#. 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 a 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
Pithos view registration to Astakos
-----------------------------------
The pithos view has to authenticate itself with astakos since the latter has to
The Pithos view has to authenticate itself with Astakos since the latter has to
prevent serving requests by unknown/unauthorized clients.
Each oauth client is identified by a client identifier (client_id). Moreover,
the confidential clients are authenticated via a password (client_secret).
Then, each client has to declare at least a redirect URI so
that astakos will be able to validate the redirect URI provided during the
authorization code request. If a client is trusted (like a pithos view) astakos
grants access on behalf of the resource owner, otherwise the resource owner has
to be asked.
Each OAuth client is identified by a client identifier (``client_id``).
Moreover, the confidential clients are authenticated via a password
(``client_secret``). Then, each client has to declare at least one redirect
URI, so that Astakos will be able to validate the redirect URI provided during
the authorization code request. If a client is trusted (like the Pithos view),
Astakos grants access on behalf of the resource owner, otherwise the resource
owner has to be asked.
We can register an oauth 2.0 client with the following command::
We register an OAuth 2.0 client with the following command::
snf-manage oauth2-client-add <client_id> --secret=<secret> --is-trusted --url <redirect_uri>
......@@ -90,27 +93,28 @@ For example::
snf-manage oauth2-client-add pithos-view --secret=12345 --is-trusted --url https://pithos.synnefo.live/pithos/ui/view
Configure view credentials in pithos
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
change the ``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting.
We set the credentials used by the Pithos view to authenticate itself
with Astakos during the resource access token generation procedure, in the
``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting.
The value should be a (<client_id>, <client_secret>) tuple.
The value should be a ``(<client_id>, <client_secret>)`` tuple.
For example::
PITHOS_OAUTH2_CLIENT_CREDENTIALS = ('pithos-view', 12345)
PITHOS_OAUTH2_CLIENT_CREDENTIALS = ("pithos-view", 12345)
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
code. In that case it redirects to Astakos' authorization endpoint by adding
the following parameters to the query component using the
"application/x-www-form-urlencoded" format:
``application/x-www-form-urlencoded`` format:
::
response_type:
'code'
......@@ -132,30 +136,33 @@ request using TLS (with extra line breaks for display purposes only)::
Access token request
--------------------
Astakos's authorization endpoint responses to a valid authorization code
Astakos' authorization endpoint responses to a valid authorization code
request by redirecting the user-agent back to the requested view
(redirect_uri parameter).
(``redirect_uri`` parameter).
The view receives the request which includes the authorization code and
makes a POST request to the astakos's token endpoint by sending the following
parameters using the "application/x-www-form-urlencoded" format in the HTTP
makes a POST request to the Astakos' token endpoint by sending the following
parameters using the ``application/x-www-form-urlencoded`` format in the HTTP
request entity-body:
::
grant_type:
"authorization_code"
code:
the authorization code received from the astakos.
the authorization code received from the Astakos.
redirect_uri:
the "redirect_uri" parameter was included in the authorization request
Since the pithos view is registered as a confidential client it MUST
authenticate with astakos by providing an Authorization header including the
Since the Pithos view is registered as a confidential client it MUST
authenticate with Astakos by providing an Authorization header including the
encoded client credentials as described in
http://tools.ietf.org/html/rfc2617#page-11.
For example, the view makes the following HTTP request using TLS (with extra
line breaks for display purposes only)::
POST /astakos/oauth2/token HTTP/1.1
Host: accounts.synnefo.live
Authorization: Basic cGl0aG9zLXZpZXc6MTIzNDU=
......@@ -164,11 +171,10 @@ line breaks for display purposes only)::
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png
Access to the protected resource
--------------------------------
Astakos's token endpoint replies to a valid token request with a (200 OK)
Astakos' token endpoint replies to a valid token request with a `200 OK`
response::
HTTP/1.1 200 OK
......@@ -186,31 +192,31 @@ The view redirects the user-agent to itself by adding to the query component
the access token.
The view receives the request which includes an access token and requests
from astakos to validate the token by making a GET HTTP request to the
astakos's validation endpoint::
from Astakos to validate the token by making a GET HTTP request to the
Astakos' validation endpoint::
GET /astakos/identity/v2.0/tokens/2YotnFZFEjr1zCsicMWpAA?belongsTo=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1
Host: accounts.synnefo.live
The astakos's validation endpoint checks whether the token is valid, has not
The Astakos' validation endpoint checks whether the token is valid, has not
expired and that the ``belongsTo`` parameter matches with the ``scope``
parameter that was included in the token request.
If not valid returns a 404 NOT FOUND response.
If valid, returns the information of the user to whom the token was assigned.
parameter that was included in the token request. If not valid returns a `404
NOT FOUND` response. If valid, returns the information of the user to whom the
token was assigned.
In the former case the view redirects to the requested path
(without the access token or the authorization code) in order to re-initiate
the procedure by requesting an new authorization code.
In the former case the view redirects to the requested path (without the access
token or the authorization code) in order to re-initiate the procedure by
requesting an new authorization code.
In the latter case the view proceeds with the request and if the user has access
to the requested resource the resource's data are returned, otherwise the
access to resource is forbidden.
In the latter case, the view proceeds with the request and if the user has
access to the requested resource the resource's data are returned, otherwise
the access to the resource is forbidden.
Authorization code and access token invalidation
------------------------------------------------
Authorization codes can be used only once (they are deleted after a
successful token creation)
Authorization codes can be used only once (they are deleted after a successful
token creation)
Token expiration can be set by changing the ``OAUTH2_TOKEN_EXPIRES`` setting.
By default it is set to 20 seconds.
......@@ -224,19 +230,19 @@ Authorization code and access token length
------------------------------------------
Authorization code length is adjustable by the
``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to
60 characters.
``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to 60
characters.
Token length is adjustable by the ``OAUTH2_TOKEN_LENGTH`` setting.
By default it is set to 30 characters.
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_UNSAFE_DOMAIN`` has been introduced. When set,
all api views that serve pithos file contents will be restricted to be served
only under the domain specified in the setting value.
A new setting ``PITHOS_UNSAFE_DOMAIN`` has been introduced. When set, all API
views that serve Pithos file contents will be restricted to be served only
under the domain specified in the setting value.
If an invalid host is identified and request HTTP method is one
of ``GET``, ``HOST``, the server will redirect using a clone of the request
with host replaced to the one the restriction applies to.
If an invalid host is identified and request HTTP method is one of ``GET``,
``HOST``, the server will redirect using a clone of the request with host
replaced to the one the restriction applies to.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment