Statistics
| Branch: | Tag: | Revision:

root / docs / design / pithos-view-authorization.rst @ 999bf7b6

History | View | Annotate | Download (9.5 kB)

1
Serve untrusted user content
2
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3

    
4
The current document describes how the pithos view accesses the protected
5
pithos resources and proposes a new design for granting access to
6
the specific resources. It sketches implementation details and configuration
7
concerns.
8

    
9
Current state and shortcomings
10
==============================
11

    
12
Pithos in order to identify the user who requests to view a pithos resource
13
uses the information stored by astakos in the cookie after a successful user
14
authentication login.
15

    
16
The main drawback of this design is that the pithos view which serves untrusted
17
user content has access to the sensitive information stored in the cookie.
18

    
19
Abstract
20
========
21

    
22
We want to serve untrusted user content in a domain which does not have access
23
to sensitive information. Therefore, we would like the pithos view to be
24
deployed in a domain outside the astakos cookie domain.
25

    
26
We propose a design for the pithos view to grant access to the
27
access-restricted resource without consulting the cookie.
28

    
29
Briefly the pithos view will request a short-term access token for a specific
30
resource from astakos. Before requesting the access token, the view should
31
obtain an authorization grant (authorization code) from astakos, which will be
32
presented by the view during the request for the access token.
33

    
34
The proposed scheme follows the guidelines of the OAuth 2.0 authentication
35
framework as described in http://tools.ietf.org/html/rfc6749/.
36

    
37
Proposed changes
38
================
39

    
40
We propose to alter the view to obtain authorization according to the
41
authorization code grant flow.
42

    
43
The general flow includes the following steps:
44

    
45
#. The user requests to view the content of the protected resource.
46
#. The view requests an authorisation code from astakos by providing its
47
   identifier, the requested scope, and a redirection URI.
48
#. Astakos authenticates the user and validates that the redirection URI
49
   matches with the registered redirect URIs of the view.
50
   As far as the pithos view is considered a trusted client, astakos grants the
51
   access request on behalf of the user.
52
#. Astakos redirects the user-agent back to the view using the redirection URI
53
   provided earlier. The redirection URI includes an authorisation code.
54
#. The view requests an access token from astakos by including the
55
   authorisation code in the request. The view also posts its client identifier
56
   and its client secret in order to authenticate itself with astakos. It also
57
   supplies the redirection URI used to obtain the authorisation code for
58
   verification.
59
#. Astakos authenticates the view, validates the authorization code,
60
   and ensures that the redirection URI received matches the URI
61
   used to redirect the client.
62
   If valid, astakos responds back with an short-term access token.
63
#. The view exchanges with astakos the access token for the information of the
64
   user to whom the authoritativeness was granted.
65
#. The view responds with the resource contents if the user has access to the
66
   specific resource.
67

    
68
Implementation details
69
======================
70

    
71
Pithos view registration to astakos
72
-----------------------------------
73

    
74
The pithos view has to authenticate itself with astakos since the latter has to
75
prevent serving requests by unknown/unauthorized clients.
76

    
77
Each oauth client is identified by a client identifier (client_id). Moreover,
78
the confidential clients are authenticated via a password (client_secret).
79
Then, each client has to declare at least a redirect URI so
80
that astakos will be able to validate the redirect URI provided during the
81
authorization code request. If a client is trusted (like a pithos view) astakos
82
grants access on behalf of the resource owner, otherwise the resource owner has
83
to be asked.
84

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

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

    
89
For example::
90

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

    
93

    
94
Configure view credentials in pithos
95
------------------------------------
96

    
97
To set the credentials issued to pithos view in order to authenticate itself
98
with astakos during the resource access token generation procedure we have to
99
change the ``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting.
100

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

    
103
For example::
104

    
105
    PITHOS_OAUTH2_CLIENT_CREDENTIALS = ('pithos-view', 12345)
106

    
107
Authorization code request
108
--------------------------
109

    
110
The view receives a request without either an access token or an authorization
111
code. In that case it redirects to astakos's authorization endpoint by adding
112
the following parameters to the query component using the
113
"application/x-www-form-urlencoded" format:
114

    
115
    response_type:
116
        'code'
117
    client_id:
118
        'pithos-view'
119
    redirect_uri:
120
        the absolute path of the view request
121
    scope:
122
        the user specific part of the view request path
123

    
124
For example, the client directs the user-agent to make the following HTTP
125
request using TLS (with extra line breaks for display purposes only)::
126

    
127
    GET /astakos/oauth2/auth?response_type=code&client_id=pithos-view
128
        &redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png
129
        &scope=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1
130
        Host: accounts.synnefo.live
131

    
132
Access token request
133
--------------------
134

    
135
Astakos's authorization endpoint responses to a valid authorization code
136
request by redirecting the user-agent back to the requested view
137
(redirect_uri parameter).
138

    
139
The view receives the request which includes the authorization code and
140
makes a POST request to the astakos's token endpoint by sending the following
141
parameters using the "application/x-www-form-urlencoded" format in the HTTP
142
request entity-body:
143

    
144
    grant_type:
145
        "authorization_code"
146
    code:
147
        the authorization code received from the astakos.
148
    redirect_uri:
149
        the "redirect_uri" parameter was included in the authorization request
150

    
151
Since the pithos view is registered as a confidential client it MUST
152
authenticate with astakos by providing an Authorization header including the
153
encoded client credentials as described in
154
http://tools.ietf.org/html/rfc2617#page-11.
155

    
156
For example, the view makes the following HTTP request using TLS (with extra
157
line breaks for display purposes only)::
158

    
159
     POST /astakos/oauth2/token HTTP/1.1
160
     Host: accounts.synnefo.live
161
     Authorization: Basic cGl0aG9zLXZpZXc6MTIzNDU=
162
     Content-Type: application/x-www-form-urlencoded
163

    
164
     grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
165
     &redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png
166

    
167

    
168
Access to the protected resource
169
--------------------------------
170

    
171
Astakos's token endpoint replies to a valid token request with a (200 OK)
172
response::
173

    
174
     HTTP/1.1 200 OK
175
     Content-Type: application/json;charset=UTF-8
176
     Cache-Control: no-store
177
     Pragma: no-cache
178

    
179
     {
180
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
181
       "token_type":"Bearer",
182
       "expires_in":20
183
     }
184

    
185
The view redirects the user-agent to itself by adding to the query component
186
the access token.
187

    
188
The view receives the request which includes an access token and requests
189
from astakos to validate the token by making a GET HTTP request to the
190
astakos's validation endpoint::
191

    
192
    GET /astakos/identity/v2.0/tokens/2YotnFZFEjr1zCsicMWpAA?belongsTo=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1
193
    Host: accounts.synnefo.live
194

    
195
The astakos's validation endpoint checks whether the token is valid, has not
196
expired and that the ``belongsTo`` parameter matches with the ``scope``
197
parameter that was included in the token request.
198
If not valid returns a 404 NOT FOUND response.
199
If valid, returns the information of the user to whom the token was assigned.
200

    
201
In the former case the view redirects to the requested path
202
(without the access token or the authorization code) in order to re-initiate
203
the procedure by requesting an new authorization code.
204

    
205
In the latter case the view proceeds with the request and if the user has access
206
to the requested resource the resource's data are returned, otherwise the
207
access to resource is forbidden.
208

    
209
Authorization code and access token invalidation
210
------------------------------------------------
211

    
212
Authorization codes can be used only once (they are deleted after a
213
successful token creation)
214

    
215
Token expiration can be set by changing the ``OAUTH2_TOKEN_EXPIRES`` setting.
216
By default it is set to 20 seconds.
217

    
218
Tokens granted to a user are deleted after user logout or authentication token
219
renewal.
220

    
221
Expired tokens presented to the validation endpoint are also deleted.
222

    
223
Authorization code and access token length
224
------------------------------------------
225

    
226
Authorization code length is adjustable by the
227
``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to
228
60 characters.
229

    
230
Token length is adjustable by the ``OAUTH2_TOKEN_LENGTH`` setting.
231
By default it is set to 30 characters.
232

    
233
Restrict file serving endpoints to a specific host
234
--------------------------------------------------
235

    
236
A new setting ``PITHOS_SERVE_API_DOMAIN`` has been introduced. When set,
237
all api views that serve pithos file contents will be restricted to be served
238
only under the domain specified in the setting value.
239

    
240
If an invalid host is identified and request HTTP method is one
241
of ``GET``, ``HOST``, the server will redirect using a clone of the request
242
with host replaced to the one the restriction applies to.