Statistics
| Branch: | Tag: | Revision:

root / docs / astakos.rst @ 949f8393

History | View | Annotate | Download (9.1 kB)

1
.. _astakos:
2

    
3
Identity Management Service (Astakos)
4
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5

    
6
Astakos is GRNET project that provides identity management, catalog and policy services.
7
It is designed to be used by the synnefo family software,
8
but is free and open to use by anybody, under a BSD-2 clause license.
9

    
10
Introduction
11
============
12

    
13
Astakos serves as a unique point of authentication for `GRNET <http://www.grnet.gr>`_
14
cloud services. It is a platform-wide service that allows users to manage their accounts.
15

    
16
Users in astakos can be authenticated via several identity providers:
17

    
18
 * Local
19
 * Shibboleth
20

    
21
It extends the ``snf-manage`` command line tool by introducing commands for managing the user accounts.
22

    
23
It is build over django and extends its authentication mechanism.
24

    
25
This document's goals are:
26

    
27
 * present the overall architectural design.
28
 * provide basic use cases.
29

    
30
The present document is meant to be read alongside the `Django documentation
31
<https://www.djangoproject.com/>`_. Thus, it is suggested that the reader is
32
familiar with associated technologies.
33

    
34

    
35
Astakos Architecture
36
====================
37

    
38
Overview
39
--------
40

    
41
Astakos service co-ordinates the access to resources (and the subsequent
42
permission model) and acts as the single point of registry and entry to the
43
GRNET cloud offering, comprising of Cyclades and Pithos+ subsystems.
44

    
45
It also propagates the user state to the Aquarium pricing subsystem.
46

    
47
.. image:: images/astakos-okeanos.jpg
48

    
49
Registration Use Cases
50
----------------------
51

    
52
The following subsections describe two basic registration use cases. All the
53
registration cases are illustrated in :ref:`registration-flow-label`
54

    
55
Invited user
56
~~~~~~~~~~~~
57

    
58
A registered ~okeanos user, invites student Alice to subscribe to ~okeanos
59
services. Alice receives an email and through a link is navigated to Astakos's
60
signup page. The system prompts her to select one of the available
61
authentication mechanisms (Shibboleth, local authentication) in
62
order to register to the system. Alice already has a Shibboleth account so
63
chooses that and then she is redirected to her institution's login page. Upon
64
successful login, her account is created.
65

    
66
Since she is invited her account is automaticaly activated and she is
67
redirected to Astakos's login page. As this is the first time Alice has
68
accessed the system she is redirected to her profile page where she can edit or
69
provide more information.
70

    
71
Not invited user
72
~~~~~~~~~~~~~~~~
73

    
74
Tony while browsing in the internet finds out about ~okeanos services. He
75
visits the signup page and fills the signup form. Since his not an invited
76
user his account has to be activated from an administrator first,
77
in order to be able to login. Upon the account's activation he receives
78
an email and through a link he is redirected to the login page.
79

    
80
Authentication Use Cases
81
------------------------
82

    
83
Cloud service user
84
~~~~~~~~~~~~~~~~~~
85

    
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
88
perform the specific task. The service contacts Astakos through its
89
``/im/authenticate`` api call (see :ref:`authenticate-api-label`) providing the
90
specific ``X-Auth-Token``. Astakos checkes whether the token belongs to an
91
active user and it has not expired and returns a dictionary containing user
92
related information. Finally the service uses the ``uniq`` field included in
93
the dictionary as the account string to identify the user accessible resources.
94

    
95
.. _registration-flow-label:
96

    
97
Registration Flow
98
-----------------
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 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

    
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

    
104
If the invitation mechanism is not enabled, the ``SimpleBackend`` checks if the email address matches any of the ASTAKOS_RE_USER_EMAIL_PATTERNS or the moderation is not enabled and it sends a verification email, otherwise informs the user that the account is pending approval and sends a notification email to the admins.
105

    
106
The verification email contains a link that navigates the user to ``activate`` view through a URI that contains also a temporary user token. If this token is valid the user account is activated and the user is logged in the system, after renewing the token and setting the cookie identified by ASTAKOS_COOKIE_NAME (used by the ~okeanos subcomponents).
107

    
108
If FORCE_PROFILE_UPDATE is set, after the first successful login the user is navigated first to the ``profile`` view, before been redirected to the ``next`` parameter value.
109

    
110
.. image:: images/astakos-signup.jpg
111
    :scale: 100%
112

    
113
Login Flow
114
----------
115

    
116
During loging procedure the user is authenticated by the respective identity provider.
117

    
118
If ASTAKOS_RECAPTCHA_ENABLED is set and the user fails several times (ASTAKOS_RATELIMIT_RETRIES_ALLOWED setting) to provide the correct credentials for a local account, is prompted to solve a captcha challenge.
119

    
120
Upon success, the system renews the token (if it has been expired), logins the user and sets the cookie, before redirecting the user to the ``next`` parameter value.
121

    
122
.. image:: images/astakos-login.jpg
123
    :scale: 100%
124

    
125
Approval Terms
126
--------------
127

    
128
The ``snf-manage addterms`` command serves to add new approval terms.
129

    
130
During the account registration, if there are approval terms, the user has to agree with them in order to proceed.
131

    
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

    
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

    
140
.. _authentication-label:
141

    
142
Astakos Users and Authentication
143
--------------------------------
144

    
145
Astakos incorporates django user authentication system and extends its User model.
146

    
147
Since username field of django User model has a limitation of 30 characters,
148
AstakosUser is **uniquely** identified by the ``email`` instead. Therefore,
149
``astakos.im.authentication_backends.EmailBackend`` is served to authenticate a
150
user using email if the first argument is actually an email, otherwise tries
151
the username.
152

    
153
A new AstakosUser instance is assigned with a uui as username and also with a
154
``auth_token`` used by the cloud services to authenticate the user.
155
``astakos.im.authentication_backends.TokenBackend`` is also specified in order
156
to authenticate the user using the email and the token fields.
157

    
158
Logged on users can perform a number of actions:
159

    
160
 * access and edit their profile via: ``/im/profile``.
161
 * change their password via: ``/im/password``
162
 * invite somebody else via: ``/im/invite``
163
 * send feedback for grnet services via: ``/im/send_feedback``
164
 * logout (and delete cookie) via: ``/im/logout``
165

    
166
User entries can also be modified/added via the ``snf-manage`` commands.
167

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

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

    
176
The login URI accepts the following parameters:
177

    
178
======================  =========================
179
Request Parameter Name  Value
180
======================  =========================
181
next                    The URI to redirect to when the process is finished
182
renew                   Force token renewal (no value parameter)
183
force                   Force logout current user (no value parameter)
184
======================  =========================
185

    
186
External systems inside the ASTAKOS_COOKIE_DOMAIN scope can acquire the user information by the
187
cookie identified by ASTAKOS_COOKIE_NAME setting (set during the login procedure).
188

    
189
Finally, backend systems having acquired a token can use the
190
:ref:`authenticate-api-label` api call from a private network or through HTTPS.
191