root / docs / design / pithos-separate-view-domain.rst @ d8e8581b
History | View | Annotate | Download (9.5 kB)
1 |
Pithos separate view domain |
---|---|
2 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
3 |
|
4 |
This document describes how the Pithos view accesses the protected Pithos |
5 |
resources and proposes a new design for granting access to specific resources. |
6 |
It sketches implementation details and configuration concerns. |
7 |
|
8 |
|
9 |
Abstract |
10 |
======== |
11 |
|
12 |
We want to serve untrusted user content in a domain which does not have access |
13 |
to sensitive information. Therefore, we would like the Pithos view to be |
14 |
deployed in a domain outside the Astakos cookie domain. |
15 |
|
16 |
We propose a design for the Pithos view to grant access to the |
17 |
access-restricted resource without consulting the cookie. |
18 |
|
19 |
Briefly, the Pithos view will request a short-term access token for a specific |
20 |
resource from Astakos. Before requesting the access token, the view should |
21 |
obtain an authorization grant (authorization code) from Astakos, which will be |
22 |
presented by the view during the request for the access token. |
23 |
|
24 |
The proposed scheme follows the guidelines of the OAuth 2.0 authentication |
25 |
framework as described in http://tools.ietf.org/html/rfc6749/. |
26 |
|
27 |
|
28 |
Current state and shortcomings |
29 |
============================== |
30 |
|
31 |
Until now, Pithos, in order to identify the user who requests to view a Pithos |
32 |
resource, uses the information stored by Astakos in the cookie after a |
33 |
successful user authentication login. |
34 |
|
35 |
The main drawback of this design is that the Pithos view which serves untrusted |
36 |
user content has access to the sensitive information stored in the Astakos |
37 |
cookie. |
38 |
|
39 |
|
40 |
Proposed changes |
41 |
================ |
42 |
|
43 |
We propose to alter the Pithos view to obtain authorization according to the |
44 |
authorization code grant flow. |
45 |
|
46 |
The general flow comprises the following steps: |
47 |
|
48 |
#. The user requests to view the content of a protected resource. |
49 |
#. The view requests an authorization code from Astakos by providing its |
50 |
identifier, the requested scope, and a redirection URI. |
51 |
#. Astakos authenticates the user and validates that the redirection URI |
52 |
matches with the registered redirect URIs of the view. |
53 |
Once the Pithos view is considered a trusted client, Astakos grants the |
54 |
access request on behalf of the user. |
55 |
#. Astakos redirects the user-agent back to the view using the redirection URI |
56 |
provided earlier. The redirection URI includes an authorisation code. |
57 |
#. The view requests an access token from Astakos by including the |
58 |
authorisation code in the request. The view also posts its client identifier |
59 |
and its client secret in order to authenticate itself with Astakos. It also |
60 |
supplies the redirection URI used to obtain the authorisation code for |
61 |
verification. |
62 |
#. Astakos authenticates the view, validates the authorization code, and ensures |
63 |
that the redirection URI received matches the URI used to redirect the |
64 |
client. If valid, Astakos responds back with a short-term access token. |
65 |
#. The view exchanges with Astakos the access token for the information of the |
66 |
user to whom the authoritativeness was granted. |
67 |
#. The view responds with the resource contents if the user has access to the |
68 |
specific resource. |
69 |
|
70 |
|
71 |
Implementation details |
72 |
====================== |
73 |
|
74 |
Pithos view registration to Astakos |
75 |
----------------------------------- |
76 |
|
77 |
The Pithos view has to authenticate itself with Astakos since the latter has to |
78 |
prevent serving requests by unknown/unauthorized clients. |
79 |
|
80 |
Each OAuth client is identified by a client identifier (``client_id``). |
81 |
Moreover, the confidential clients are authenticated via a password |
82 |
(``client_secret``). Then, each client has to declare at least one redirect |
83 |
URI, so that Astakos will be able to validate the redirect URI provided during |
84 |
the authorization code request. If a client is trusted (like the Pithos view), |
85 |
Astakos grants access on behalf of the resource owner, otherwise the resource |
86 |
owner has to be asked. |
87 |
|
88 |
We register an OAuth 2.0 client with the following command:: |
89 |
|
90 |
snf-manage oauth2-client-add <client_id> --secret=<secret> --is-trusted --url <redirect_uri> |
91 |
|
92 |
For example:: |
93 |
|
94 |
snf-manage oauth2-client-add pithos-view --secret=12345 --is-trusted --url https://pithos.synnefo.live/pithos/ui/view |
95 |
|
96 |
Configure view credentials in Pithos |
97 |
------------------------------------ |
98 |
|
99 |
We set the credentials used by the Pithos view to authenticate itself |
100 |
with Astakos during the resource access token generation procedure, in the |
101 |
``PITHOS_OAUTH2_CLIENT_CREDENTIALS`` setting. |
102 |
|
103 |
The value should be a ``(<client_id>, <client_secret>)`` tuple. |
104 |
|
105 |
For example:: |
106 |
|
107 |
PITHOS_OAUTH2_CLIENT_CREDENTIALS = ("pithos-view", 12345) |
108 |
|
109 |
Authorization code request |
110 |
-------------------------- |
111 |
|
112 |
The view receives a request without either an access token or an authorization |
113 |
code. In that case it redirects to Astakos' authorization endpoint by adding |
114 |
the following parameters to the query component using the |
115 |
``application/x-www-form-urlencoded`` format: |
116 |
|
117 |
:: |
118 |
|
119 |
response_type: |
120 |
'code' |
121 |
client_id: |
122 |
'pithos-view' |
123 |
redirect_uri: |
124 |
the absolute path of the view request |
125 |
scope: |
126 |
the user specific part of the view request path |
127 |
|
128 |
For example, the client directs the user-agent to make the following HTTP |
129 |
request using TLS (with extra line breaks for display purposes only):: |
130 |
|
131 |
GET /astakos/oauth2/auth?response_type=code&client_id=pithos-view |
132 |
&redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png |
133 |
&scope=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1 |
134 |
Host: accounts.synnefo.live |
135 |
|
136 |
Access token request |
137 |
-------------------- |
138 |
|
139 |
Astakos' authorization endpoint responses to a valid authorization code |
140 |
request by redirecting the user-agent back to the requested view |
141 |
(``redirect_uri`` parameter). |
142 |
|
143 |
The view receives the request which includes the authorization code and |
144 |
makes a POST request to the Astakos' token endpoint by sending the following |
145 |
parameters using the ``application/x-www-form-urlencoded`` format in the HTTP |
146 |
request entity-body: |
147 |
|
148 |
:: |
149 |
|
150 |
grant_type: |
151 |
"authorization_code" |
152 |
code: |
153 |
the authorization code received from the Astakos. |
154 |
redirect_uri: |
155 |
the "redirect_uri" parameter was included in the authorization request |
156 |
|
157 |
Since the Pithos view is registered as a confidential client it MUST |
158 |
authenticate with Astakos by providing an Authorization header including the |
159 |
encoded client credentials as described in |
160 |
http://tools.ietf.org/html/rfc2617#page-11. |
161 |
|
162 |
For example, the view makes the following HTTP request using TLS (with extra |
163 |
line breaks for display purposes only):: |
164 |
|
165 |
|
166 |
POST /astakos/oauth2/token HTTP/1.1 |
167 |
Host: accounts.synnefo.live |
168 |
Authorization: Basic cGl0aG9zLXZpZXc6MTIzNDU= |
169 |
Content-Type: application/x-www-form-urlencoded |
170 |
|
171 |
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA |
172 |
&redirect_uri=https%3A//pithos.synnefo.live/pithos/ui/view/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png |
173 |
|
174 |
Access to the protected resource |
175 |
-------------------------------- |
176 |
|
177 |
Astakos' token endpoint replies to a valid token request with a `200 OK` |
178 |
response:: |
179 |
|
180 |
HTTP/1.1 200 OK |
181 |
Content-Type: application/json;charset=UTF-8 |
182 |
Cache-Control: no-store |
183 |
Pragma: no-cache |
184 |
|
185 |
{ |
186 |
"access_token":"2YotnFZFEjr1zCsicMWpAA", |
187 |
"token_type":"Bearer", |
188 |
"expires_in":20 |
189 |
} |
190 |
|
191 |
The view redirects the user-agent to itself by adding to the query component |
192 |
the access token. |
193 |
|
194 |
The view receives the request which includes an access token and requests |
195 |
from Astakos to validate the token by making a GET HTTP request to the |
196 |
Astakos' validation endpoint:: |
197 |
|
198 |
GET /astakos/identity/v2.0/tokens/2YotnFZFEjr1zCsicMWpAA?belongsTo=/b0ee4760-9451-4b9a-85f0-605c48bebbdd/pithos/image.png HTTP/1.1 |
199 |
Host: accounts.synnefo.live |
200 |
|
201 |
The Astakos' validation endpoint checks whether the token is valid, has not |
202 |
expired and that the ``belongsTo`` parameter matches with the ``scope`` |
203 |
parameter that was included in the token request. If not valid returns a `404 |
204 |
NOT FOUND` response. If valid, returns the information of the user to whom the |
205 |
token was assigned. |
206 |
|
207 |
In the former case the view redirects to the requested path (without the access |
208 |
token or the authorization code) in order to re-initiate the procedure by |
209 |
requesting an new authorization code. |
210 |
|
211 |
In the latter case, the view proceeds with the request and if the user has |
212 |
access to the requested resource the resource's data are returned, otherwise |
213 |
the access to the resource is forbidden. |
214 |
|
215 |
Authorization code and access token invalidation |
216 |
------------------------------------------------ |
217 |
|
218 |
Authorization codes can be used only once (they are deleted after a successful |
219 |
token creation) |
220 |
|
221 |
Token expiration can be set by changing the ``OAUTH2_TOKEN_EXPIRES`` setting. |
222 |
By default it is set to 20 seconds. |
223 |
|
224 |
Tokens granted to a user are deleted after user logout or authentication token |
225 |
renewal. |
226 |
|
227 |
Expired tokens presented to the validation endpoint are also deleted. |
228 |
|
229 |
Authorization code and access token length |
230 |
------------------------------------------ |
231 |
|
232 |
Authorization code length is adjustable by the |
233 |
``OAUTH2_AUTHORIZATION_CODE_LENGTH`` setting. By default it is set to 60 |
234 |
characters. |
235 |
|
236 |
Token length is adjustable by the ``OAUTH2_TOKEN_LENGTH`` setting. By default |
237 |
it is set to 30 characters. |
238 |
|
239 |
Restrict file serving endpoints to a specific host |
240 |
-------------------------------------------------- |
241 |
|
242 |
A new setting ``PITHOS_UNSAFE_DOMAIN`` has been introduced. When set, all API |
243 |
views that serve Pithos file contents will be restricted to be served only |
244 |
under the domain specified in the setting value. |
245 |
|
246 |
If an invalid host is identified and request HTTP method is one of ``GET``, |
247 |
``HOST``, the server will redirect using a clone of the request with host |
248 |
replaced to the one the restriction applies to. |