Synnefo

* Extend astakosclient to request and validate OAuth 2.0 access tokens

* Implement OAuth 2.0 Authorization Code Grant

  Add API calls for authorization code and access token generation

* Add API call for validating OAuth 2.0 access tokens

	 * oauth2-client-add (register OAuth 2.0 client)

	 * oauth2-client-list (list registered oauth 2.0 clients)

	 * oauth2-client-remove (remove OAuth 2.0 client)

* Change view authentication

  The pithos views do not use the cookie information for user authentication.

  They request (from Astakos) and use a short-term access token for a

  specific resource.

* Remove PITHOS_ASTAKOS_COOKIE_NAME setting, since it is no longer useful

* Add PITHOS_OAUTH2_CLIENT_CREDENTIALS setting to authenticate the views with

  astakos during the resource access token generation procedure

* Add PITHOS_SERVE_API_DOMAIN setting to restrict file serving endpoints to a

  specific host

oauth2-client-add             Create an oauth2 client

oauth2-client-list            List oauth2 clients

oauth2-client-remove          Remove an oauth2 client along with its registered redirect urls

0.15 (December 02, 2013)   Extent token api with validate token call

Validate token

^^^^^^^^^^^^^^

This calls validates an access token and confirms that it belongs to a

specified scope.

========================================= =========  ==================

Uri                                       Method     Description

========================================= =========  ==================

``/identity/v2.0/tokens/<token_id>``      GET        Validates an access token and confirms that it belongs to a specified scope.

========================================= =========  ==================

|

======================  =========================

Request Parameter Name  Value

======================  =========================

belongsTo               Validates that a access token has the specified scope.

                        The belongsTo parameter is optional.

======================  =========================

Example response

::

    {"access": {

        "token": {

            "expires": "2013-12-02T15:57:34.300266+00:00",

            "id": "2YotnFZFEjr1zCsicMWpAA",

            "tenant": {

                "id": "c18088be-16b1-4263-8180-043c54e22903",

                "name": "Firstname Lastname"

            }

        },

         "user": {

             "roles_links": [],

             "id": "c18088be-16b1-4263-8180-043c54e22903",

             "roles": [{"id": 1, "name": "default"}],

             "name": "Firstname Lastname"}}}

|

=========================== =====================

Return Code                 Description

=========================== =====================

404                         Unknown or expired access token or the access token does not belong to the specified scope

=========================== =====================

Serve untrusted user content

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.

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.

Pithos view registration to astakos

===================================

The pithos view has to authenticate itself with astakos since the later 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.

We can register an oauth 2.0 client with the following command::

    snf-manage oauth2-client-add <client_id> --secret=<secret> --is-trusted --url <redirect_uri>

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

====================================

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.

The value should be a (<client_id>, <client_secret>) tuple.

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 responses 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

the following parameters to the query component using the

"application/x-www-form-urlencoded" format:

    response_type:

        'code'

    client_id:

        'pithos-view'

    redirect_uri:

        the absolute path of the view request

    scope:

        the user specific part of the view request path

For example, the client directs the user-agent to make the following HTTP

request using TLS (with extra line breaks for display purposes only)::

    GET /astakos/oauth2/auth?response_type=code&client_id=pithos-view

        &redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png

        &scope=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1

        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

(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

request entity-body:

    grant_type:

        "authorization_code"

    code:

        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

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=

     Content-Type: application/x-www-form-urlencoded

     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)

response::

     HTTP/1.1 200 OK

     Content-Type: application/json;charset=UTF-8

     Cache-Control: no-store

     Pragma: no-cache

     {

       "access_token":"2YotnFZFEjr1zCsicMWpAA",

       "token_type":"Bearer",

       "expires_in":20

     }

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::

    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

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.

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 later 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.

Authorization code and access token invalidation

================================================

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.

Tokens granted to a user are deleted after user logout or authentication token

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

60 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_SERVE_API_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.

   Pithos view authorization <design/pithos-view-authorization.rst>

.. _pithos_view_registration:

Register pithos view as an OAuth 2.0 client

-------------------------------------------

Starting from synnefo version 0.15, the pithos view, in order to get access to

the data of a protect pithos resource, has to be granted authorization for the

specific resource by astakos.

During the authorization grant procedure, it has to authenticate itself with

astakos since the later has to prevent serving requests by unknown/unauthorized

clients.

To register the pithos view as an OAuth 2.0 client in astakos, we have to run

the following command::

    snf-manage oauth2-client-add pithos-view --secret=<secret> --is-trusted --url https://node2.example.com/pithos/ui/view

The ``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting is used by the pithos view

in order to authenticate itself with astakos during the authorization grant

procedure and it should container the credentials issued for the pithos view

in `the pithos view registration step`__.

__ pithos_view_registration_

.. _pithos_view_registration:

2.3 Register pithos view as an oauth 2.0 client in astakos

----------------------------------------------------------

Starting from synnefo version 0.15, the pithos view, in order to get access to

the data of a protect pithos resource, has to be granted authorization for the

specific resource by astakos.

During the authorization grant procedure, it has to authenticate itself with

astakos since the later has to prevent serving requests by unknown/unauthorized

clients.

To register the pithos view as an OAuth 2.0 client in astakos, use the

following command::

    snf-manage oauth2-client-add pithos-view --secret=<secret> --is-trusted --url https://pithos.synnefo.live/pithos/ui/view

2.4 Update configuration files

In addition to this, we have to change the ``PITHOS_OAUTH2_CLIENT_CREDENTIALS``

setting in the ``20-snf-pithos-app-settings.conf`` file to set the credentials

issued for the pithos view in `the previous step`__.

__ pithos_view_registration_

    help = "Create an oauth2 client"