Revision 949f8393

b/docs/astakos-api-guide.rst
20 20
=========================  ================================
21 21
Revision                   Description
22 22
=========================  ================================
23
0.6 (June 06, 2012)        Split service and admin API.
23 24
0.1 (Feb 10, 2012)         Initial release.
24 25
=========================  ================================
25 26

  
26
API Operations
27
--------------
27
Admin API Operations
28
--------------------
29

  
30
The operations described in this chapter allow users to authenticate themselves and priviledged users (ex. helpdesk) to access other user information.
31

  
32
Most of the operations require a valid token assigned to users having the necessary permissions.
28 33

  
29 34
.. _authenticate-api-label:
30 35

  
......
59 64
auth_token_created           Token creation date
60 65
has_credits                  Whether user has credits
61 66
has_signed_terms             Whether user has aggred on terms
67
groups                       User groups
62 68
===========================  ============================
63 69

  
64 70
Example reply:
......
66 72
::
67 73

  
68 74
  {"username": "4ad9f34d6e7a4992b34502d40f40cb",
69
  "uniq": "papagian@example.com"
75
  "uniq": "user@example.com"
70 76
  "auth_token": "0000",
71
  "auth_token_expires": "Tue, 11-Sep-2012 09:17:14 ",
72
  "auth_token_created": "Sun, 11-Sep-2011 09:17:14 ",
77
  "auth_token_expires": "Fri, 29 Jun 2012 10:03:37 GMT",
78
  "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
73 79
  "has_credits": false,
74 80
  "has_signed_terms": true}
75 81

  
......
79 85
Return Code                 Description
80 86
=========================== =====================
81 87
204 (No Content)            The request succeeded
82
400 (Bad Request)           The request is invalid
88
400 (Bad Request)           Method not allowed or no user found
83 89
401 (Unauthorized)          Missing token or inactive user or penging approval terms
84 90
500 (Internal Server Error) The request cannot be completed because of an internal error
85 91
=========================== =====================
86 92

  
93
Get User by email
94
^^^^^^^^^^^^^^^^^
95

  
96
Returns a json formatted dictionary containing information about a specific user
97

  
98
============================== =========  ==================
99
Uri                            Method     Description
100
============================== =========  ==================
101
``/im/admin/api/v2.0/users/``  GET        Get user information by email
102
============================== =========  ==================
103

  
104
|
105

  
106
====================  ===========================
107
Request Header Name   Value
108
====================  ===========================
109
X-Auth-Token          Authentication token owned by
110
                      a user has or inherits ``im.can_access_userinfo`` permission
111
====================  ===========================
112

  
113
|
114

  
115
======================  =========================
116
Request Parameter Name  Value
117
======================  =========================
118
name                    Email
119
======================  =========================
120

  
121

  
122
|
123

  
124
=========================== =====================
125
Return Code                 Description
126
=========================== =====================
127
200 (OK)                    The request succeeded
128
400 (Bad Request)           Method not allowed
129
401 (Unauthorized)          Missing or invalid token or unauthorized user
130
404 (Not Found)             Missing email or inactive user
131
500 (Internal Server Error) The request cannot be completed because of an internal error
132
=========================== =====================
133

  
134
Example reply:
135

  
136
::
137

  
138
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
139
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
140
    "name": "Firstname Surname",
141
    "groups": ["default"],
142
    "user_permissions": [],
143
    "has_credits": false,
144
    "auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT",
145
    "enabled": true,
146
    "email": ["user@example.com"],
147
    "id": 4}
148

  
149
Get User by username
150
^^^^^^^^^^^^^^^^^^^^
151

  
152
Returns a json formatted dictionary containing information about a specific user
153

  
154
======================================== =========  ==================
155
Uri                                      Method     Description
156
======================================== =========  ==================
157
``/im/admin/api/v2.0/users/{username}``  GET        Get user information by username
158
======================================== =========  ==================
159

  
160
|
161

  
162
====================  ===========================
163
Request Header Name   Value
164
====================  ===========================
165
X-Auth-Token          Authentication token owned
166
                      by a user has or inherits ``im.can_access_userinfo`` permission
167
====================  ===========================
168

  
169
|
170

  
171
=========================== =====================
172
Return Code                 Description
173
=========================== =====================
174
200 (OK)                    The request succeeded
175
400 (Bad Request)           Method not allowed
176
401 (Unauthorized)          Missing or invalid token or unauthorized user
177
404 (Not Found)             Invalid username
178
500 (Internal Server Error) The request cannot be completed because of an internal error
179
=========================== =====================
180

  
181
Example reply:
182

  
183
::
184

  
185
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
186
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
187
    "name": "Firstname Surname",
188
    "groups": ["default"],
189
    "user_permissions": [],
190
    "has_credits": false,
191
    "auth_token_expires":
192
    "Fri, 29 Jun 2012 10:03:37 GMT",
193
    "enabled": true,
194
    "email": ["user@example.com"],
195
    "id": 4}
196

  
87 197
Get Services
88 198
^^^^^^^^^^^^
89 199

  
......
99 209

  
100 210
::
101 211

  
102
[{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "cloud"},
103
 {"url": "/okeanos.html", "name": "~okeanos", "id": "okeanos"},
104
 {"url": "/ui/", "name": "pithos+", "id": "pithos"}]
105
 
212
    [{"url": "/", "icon": "home-icon.png", "name": "grnet cloud", "id": "1"},
213
    {"url": "/okeanos.html", "name": "~okeanos", "id": "2"},
214
    {"url": "/ui/", "name": "pithos+", "id": "3"}]
215

  
216

  
106 217
Get Menu
107 218
^^^^^^^^
108 219

  
......
114 225
``/im/get_menu``     GET        Get cloud bar menu
115 226
==================== =========  ==================
116 227

  
228
Example reply if request user is not authenticated:
229

  
230
::
231

  
232
    [{"url": "/im/", "name": "Sign in"}]
233

  
234
Example reply if request user is authenticated:
235

  
236
::
237

  
238
    [{"url": "/im/login", "name": "user@example.com"},
239
    {"url": "/im/profile", "name": "My account"},
240
    {"url": "/im/logout", "name": "Sign out"}]
241

  
242
Service API Operations
243
----------------------
244

  
245
The operations described in this chapter allow services to access user information and perform specific tasks.
246

  
247
The operations require a valid service token.
248

  
249
Send feedback
250
^^^^^^^^^^^^^
251

  
252
Via this operaton services can post user feedback requests.
253

  
254
========================= =========  ==================
255
Uri                       Method     Description
256
========================= =========  ==================
257
``/im/service/feedback``  POST       Send feedback
258
========================= =========  ==================
259

  
260
|
261

  
262
====================  ============================
263
Request Header Name   Value
264
====================  ============================
265
X-Auth-Token          Service Authentication token
266
====================  ============================
267

  
117 268
|
118 269

  
119 270
======================  =========================
120 271
Request Parameter Name  Value
121 272
======================  =========================
122
location                Location to pass in the next parameter
273
auth_token              User token
274
feedback_msg            Feedback message
275
feedback_data           Additional information about service client status
123 276
======================  =========================
124 277

  
125
Example reply if request user is not authenticated:
278
|
279

  
280
=========================== =====================
281
Return Code                 Description
282
=========================== =====================
283
200 (OK)                    The request succeeded
284
400 (Bad Request)           Method not allowed or missing or invalid user token parameter or invalid message data
285
401 (Unauthorized)          Missing or expired service token
286
500 (Internal Server Error) The request cannot be completed because of an internal error
287
=========================== =====================
288

  
289
Get User by email
290
^^^^^^^^^^^^^^^^^
291

  
292
Returns a json formatted dictionary containing information about a specific user
293

  
294
================================ =========  ==================
295
Uri                              Method     Description
296
================================ =========  ==================
297
``/im/service/api/v2.0/users/``  GET        Get user information by email
298
================================ =========  ==================
299

  
300
|
301

  
302
====================  ============================
303
Request Header Name   Value
304
====================  ============================
305
X-Auth-Token          Service Authentication token
306
====================  ============================
307

  
308
|
309

  
310
======================  =========================
311
Request Parameter Name  Value
312
======================  =========================
313
name                    Email
314
======================  =========================
315

  
316
|
317

  
318
=========================== =====================
319
Return Code                 Description
320
=========================== =====================
321
200 (OK)                    The request succeeded
322
400 (Bad Request)           Method not allowed
323
401 (Unauthorized)          Missing or expired or invalid service token
324
404 (Not Found)             Missing email or inactive user
325
500 (Internal Server Error) The request cannot be completed because of an internal error
326
=========================== =====================
327

  
328
Example reply:
126 329

  
127 330
::
128 331

  
129
[{"url": "/im/login?next=", "name": "login..."}]
332
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
333
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
334
    "name": "Firstname Surname",
335
    "groups": ["default"],
336
    "user_permissions": [],
337
    "has_credits": false,
338
    "auth_token_expires":"Fri, 29 Jun 2012 10:03:37 GMT",
339
    "enabled": true,
340
    "email": ["user@example.com"],
341
    "id": 4}
342

  
343
Get User by username
344
^^^^^^^^^^^^^^^^^^^^
130 345

  
131
Example reply if request user is authenticated::
346
Returns a json formatted dictionary containing information about a specific user
132 347

  
133
    [{"url": "/im/profile", "name": "user@grnet.gr"},
134
     {"url": "/im/profile", "name": "view your profile..."},
135
     {"url": "/im/password", "name": "change your password..."},
136
     {"url": "/im/feedback", "name": "feedback..."},
137
     {"url": "/im/logout", "name": "logout..."}]
348
========================================== =========  ==================
349
Uri                                        Method     Description
350
========================================== =========  ==================
351
``/im/service/api/v2.0/users/{username}``  GET        Get user information by username
352
========================================== =========  ==================
353

  
354
|
138 355

  
356
====================  ============================
357
Request Header Name   Value
358
====================  ============================
359
X-Auth-Token          Service Authentication token
360
====================  ============================
139 361

  
362
|
140 363

  
364
=========================== =====================
365
Return Code                 Description
366
=========================== =====================
367
200 (OK)                    The request succeeded
368
400 (Bad Request)           Method not allowed
369
401 (Unauthorized)          Missing or expired or invalid service token
370
404 (Not Found)             Invalid username
371
500 (Internal Server Error) The request cannot be completed because of an internal error
372
=========================== =====================
373

  
374
Example reply:
375

  
376
::
141 377

  
378
    {"username": "7e530044f90a4e7ba2cb94f3a26c40",
379
    "auth_token_created": "Wed, 30 May 2012 10:03:37 GMT",
380
    "name": "Firstname Surname",
381
    "groups": ["default"],
382
    "user_permissions": [],
383
    "has_credits": false,
384
    "auth_token_expires":
385
    "Fri, 29 Jun 2012 10:03:37 GMT",
386
    "enabled": true,
387
    "email": ["user@example.com"],
388
    "id": 4}
b/docs/astakos.rst
84 84
~~~~~~~~~~~~~~~~~~
85 85

  
86 86
Alice requests a specific resource from a cloud service ex. Pithos+. In the
87
request supplies the `X-Auth-Token`` to identify whether she is eligible to
87
request supplies the `X-Auth-Token` to identify whether she is eligible to
88 88
perform the specific task. The service contacts Astakos through its
89 89
``/im/authenticate`` api call (see :ref:`authenticate-api-label`) providing the
90 90
specific ``X-Auth-Token``. Astakos checkes whether the token belongs to an
......
97 97
Registration Flow
98 98
-----------------
99 99

  
100
Responsible for handling the account registration and activation requests is the ``signup`` view. This view checks whether it is a request for a local account. If this is not the case, the user is navigated to the third-party provider to authenticate against it and upon success is redirected back in the ``signup`` view. If the supplied information is valid an inactive account is created. Then the appropriate ``ActivationBackend`` handles the account activation: the ``InvitationsBackend`` if the invitation mechanism is enabled and the ``SimpleBackend`` otherwise. 
100
Responsible for handling the account registration and activation requests is the ``signup`` view. This view checks whether it is a request for a local account. If this is not the case, the user is navigated to the third-party provider to authenticate against it and upon success is redirected back in the ``signup`` view. If the supplied information is valid and an inactive account is created. Then the appropriate ``ActivationBackend`` handles the account activation: the ``InvitationsBackend`` if the invitation mechanism is enabled and the ``SimpleBackend`` otherwise. 
101 101

  
102 102
In the first case, if the request is accompanied with a valid invitation code the user is automatically activated and since it's email address (where received the invitation) is verified, acquires a valid token and is logged in the system. If there is no invitation associated with the request, the system check whether the email matches any of the ASTAKOS_RE_USER_EMAIL_PATTERNS and if it does it sends an email to the user to verify the email address, otherwise the system sends a notification email to the administrators and informs the user that the account activation will be moderated by them.
103 103

  
......
131 131

  
132 132
In case there are later approval terms that the user has not signed, the ``signed_terms_required`` view decorator redirects to the ``approval_terms`` view.
133 133

  
134
Service Registration
135
--------------------
136

  
137
Services (ex. cyclades, pithos+) are registered in astakos via ``snf-manage registerservice``. This command generates and prints a service token useful for accessing the service API.
138
Registered services can be viewed by ``snf-manage showservices`` command and ``snf-manage unregisterservice`` can be used to unregister a service.
139

  
134 140
.. _authentication-label:
135 141

  
136 142
Astakos Users and Authentication
......
161 167

  
162 168
Internal Astakos requests are handled using cookie-based django user sessions.
163 169

  
164
External systems can delgate ``/login`` URI. The server,
170
External systems should forward to the ``/login`` URI. The server,
165 171
depending on its configuration will redirect to the appropriate login page.
166 172
When done with logging in, the service's login URI should redirect to the URI
167 173
provided with next, adding user and token parameters, which contain the email

Also available in: Unified diff