Statistics
| Branch: | Tag: | Revision:

root / docs / source / devguide.rst @ 863193cb

History | View | Annotate | Download (5.4 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
* Twitter
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
500 (Internal Server Error) The request cannot be completed because of an internal error
118
=========================== =====================