root / docs / design / pithos-view-authorization.rst @ 4bf0ab85
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_UNSAFE_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. |