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