root / docs / source / devguide.rst @ 890b0eaf
History | View | Annotate | Download (5.7 kB)
1 |
Astakos Developer Guide |
---|---|
2 |
======================= |
3 |
|
4 |
Introduction |
5 |
------------ |
6 |
|
7 |
Astakos is a identity management service implemented by GRNET (http://www.grnet.gr). Users can create and manage their account, invite others and send feedback for GRNET services. During the account creation the user can select against which provider wants to authenticate: |
8 |
|
9 |
* Astakos |
10 |
|
11 |
* Shibboleth |
12 |
|
13 |
Astakos provides also an administrative interface for managing user accounts. |
14 |
|
15 |
Astakos is build over django and extends its authentication mechanism. |
16 |
|
17 |
This document's goals are: |
18 |
|
19 |
* Define the Astakos ReST API that allows the GRNET services to retrieve user information via HTTP calls |
20 |
* Describe the Astakos views and provide guidelines for a developer to extend them |
21 |
|
22 |
The present document is meant to be read alongside the Django documentation. Thus, it is suggested that the reader is familiar with associated technologies. |
23 |
|
24 |
Document Revisions |
25 |
^^^^^^^^^^^^^^^^^^ |
26 |
|
27 |
========================= ================================ |
28 |
Revision Description |
29 |
========================= ================================ |
30 |
0.1 (Jub 24, 2012) Initial release. |
31 |
========================= ================================ |
32 |
|
33 |
Astakos Users and Authentication |
34 |
-------------------------------- |
35 |
|
36 |
Astakos extends django User model. |
37 |
|
38 |
Each user is uniquely identified by the ``username`` field. An astakos user instance is assigned also with a ``auth_token`` field used by the astakos clients to authenticate a user. All API requests require a token. |
39 |
|
40 |
Logged on users can perform a number of actions: |
41 |
|
42 |
* access and edit their profile via: ``https://hostname/im/profile``. |
43 |
* change their password via: ``https://hostname/im/password`` |
44 |
* invite somebody else via: ``https://hostname/im/invite`` |
45 |
* send feedback for grnet services via: ``https://hostname/im/send_feedback`` |
46 |
* logout via: ``https://hostname/im/logout`` |
47 |
|
48 |
User entries can also be modified/added via the management interface available at ``https://hostname/im/admin``. |
49 |
|
50 |
A superuser account can be created the first time you run the manage.py syncdb django command. At a later date, the manage.py createsuperuser command line utility can be used. |
51 |
|
52 |
Astakos is also compatible with Twitter and Shibboleth (http://shibboleth.internet2.edu/). The connection between Twitter and Astakos is done by ``https://hostname/im/target/twitter/login``. The connection between Shibboleth and Astakos is done by ``https://hostname/im/target/shibboleth/login``. An application that wishes to connect to Astakos, but does not have a token, should redirect the user to ``https://hostname/im/login``. |
53 |
|
54 |
The login URI accepts the following parameters: |
55 |
|
56 |
====================== ========================= |
57 |
Request Parameter Name Value |
58 |
====================== ========================= |
59 |
next The URI to redirect to when the process is finished |
60 |
renew Force token renewal (no value parameter) |
61 |
====================== ========================= |
62 |
|
63 |
In case the user wants to authenticate via Astakos fills the login form and post it to ``https://hostname/im/local/login``. |
64 |
|
65 |
Otherwise (the user selects a third party authentication) the login process starts by redirecting the user to an external URI (controlled by the third party), where the actual authentication credentials are entered. Then, the user is redirected back to the login URI, with various identification information in the request headers. |
66 |
|
67 |
If the user does not exist in the database, Astakos adds the user and creates a random token. If the user exists, the token has not expired and ``renew`` is not set, the existing token is reused. Finally, the login URI redirects to the URI provided with ``next``, adding the ``user`` and ``token`` parameters, which contain the ``Uniq`` and ``Token`` fields respectively. |
68 |
|
69 |
The Astakos API |
70 |
--------------- |
71 |
|
72 |
Authenticate |
73 |
^^^^^^^^^^^^ |
74 |
|
75 |
==================================== ========= ================== |
76 |
Uri Method Description |
77 |
==================================== ========= ================== |
78 |
``https://hostname/im/authenticate`` GET Authenticate user using token |
79 |
==================================== ========= ================== |
80 |
|
81 |
| |
82 |
|
83 |
==================== =========================== |
84 |
Request Header Name Value |
85 |
==================== =========================== |
86 |
X-Auth-Token Authentication token |
87 |
==================== =========================== |
88 |
|
89 |
Extended information on the user serialized in the json format will be returned: |
90 |
|
91 |
=========================== ============================ |
92 |
Name Description |
93 |
=========================== ============================ |
94 |
uniq User uniq identifier |
95 |
auth_token Authentication token |
96 |
auth_token_expires Token expiration date |
97 |
auth_token_created Token creation date |
98 |
=========================== ============================ |
99 |
|
100 |
Example reply: |
101 |
|
102 |
:: |
103 |
|
104 |
{"uniq": "admin", |
105 |
"auth_token": "0000", |
106 |
"auth_token_expires": "Tue, 11-Sep-2012 09:17:14 ", |
107 |
"auth_token_created": "Sun, 11-Sep-2011 09:17:14 "} |
108 |
|
109 |
| |
110 |
|
111 |
========================= ===================== |
112 |
Return Code Description |
113 |
========================= ===================== |
114 |
204 (No Content) The request succeeded |
115 |
400 (Bad Request) The request is invalid |
116 |
401 (Unauthorized) Missing token or inactive user |
117 |
503 (Service Unavailable) The request cannot be completed because of an internal error |
118 |
========================= ===================== |
119 |
|
120 |
The Astakos views |
121 |
----------------- |
122 |
|
123 |
Astakos incorporates the ``django.contrib.auth`` mechanism for handling user login, |
124 |
logout, password change and password reset. |
125 |
|
126 |
============================== ===================== |
127 |
Uri view |
128 |
============================== ===================== |