root / docs / design / pithos-view-authentication.rst @ 9f541b00
History | View | Annotate | Download (8.8 kB)
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. |