[api] update default distribution list:
[opensuse:build-service.git] / docs / ichain.txt
1 Authentication on the openSUSE Build Service
2 ============================================
3
4 The authentication used on the build system has the following
5 basic requirements:
6
7 * The authentication has to happen on the frontend since we need
8   client independance. That means that a valid authentication check
9   can only be done on the frontend. Clients only transfer credentials
10   to the frontend.
11
12 * On the fronend, ActiveRBac for Ruby on Rails 
13   ( https://activerbac.turingstudio.com/trac ) is used because we
14   want to benefit especially from the permission system that ActiveRBac
15   comes with. Every change to the openSUSE build service authentication
16   system should not change the ActiveRBAC code. Moreover our changes
17   should integrate into the ActiveRBAC concepts.
18
19 * Additionally we want to integrate the iChain support with the ActiveRBAC  
20   user management. iChain is a Novell identity management solution 
21   and if we support users can do everything with one login on the
22   Novell and openSUSE websites.
23
24 * Since there are many registered users on the Novell websites we 
25   do not want to give access to the openSUSE build service by default
26   to anybody. Especially in the beginning we want to be able to
27   control who has access to the BS. Thus there needs to be a process
28   where people ask for enabling their iChain account and the BS admin
29   team activates the user.
30
31 * iChain works like a proxy transparent in front of a web application.
32   All it does is adding a header value to the http header. In our case
33   (iChain is much more powerfull than this) we only have the username 
34   in the header. Note that as a result of the administrational setup 
35   this header value can be considered as 100% true and secure. That 
36   means if the header contains the user name 'freitag' it is absolutely
37   secure to consider that the user freitag is logged in. The huge benefit
38   from that is that the app (the BS) does not have to bother with sensitive
39   information like passwords for example.
40
41 * We want to control in the clients what pages or functions are accessible
42   without authentication (ie. the start page) and which need an authenticated
43   user. That should not need configuration in the iChain system.
44
45 How does that work in the BS?
46 =============================
47
48 Every controller on the webclient calls the extract_user method in
49 the application controller. This method tries to extract credentials
50 from the request depending on the kind of authentication that is 
51 running. 
52
53 To switch on ichain authentication the parameter ICHAIN_HOST in the 
54 config file on both webclient and frontend need to be set to the IP
55 address of the ichain host (Note: The IP is not yet used, so setting
56 to non-nil is sufficient).
57
58 If iChain is running and the user accesses a page that should be 
59 authenticated but is not yet, the webapp redirects to a special page.
60 The iChain system is configured in the way that accessing this special
61 page requires authentication and thus iChain displays the Novell
62 standard login page. The user provides the credentials and after the
63 login was successfull, the user is redirected to his initial requested
64 page.
65
66
67 If iChain is active the user is taken from the header value X-username
68 (HTTP_X_USERNAME) that iChain transparently adds to the HTTP header.
69 The username is added as a header value to all communication to the
70 frontend as well. 
71
72 To check if a user is valid, the webclient does a lookup on the user 
73 name on the frontend. 
74 That can result in the following states:
75
76 * the user was found and has the ActiveRBAC state 2: The user is valid
77   and allowed to login in. 
78
79 * the user is not found. That means that the access to the BS was not
80   yet granted. The user is forwarded to a page that lets him ask for
81   BS access. 
82
83 * the user was found but is in state 5: The user has already asked for
84   BS access but the BS admin team has not approved. The user sees a 
85   message that asks him to wait.
86
87 In case the user is not yet in the frontend user database, the client
88 sends a XML document of the following form to the frontend controller
89 person action register:
90
91        <unregisteredperson>
92            <login>freitag</login>
93            <realname>Klaas Freitag</realname>
94            <email>freitag@suse.de</email>
95            <state>5</state>
96            <password>opensuse</password>
97            <note>This is why I like to work with the BS</note>
98         </unregisteredperson>
99
100 This controller adds the new user to the BS database and sets the
101 state to be unconfirmned. Now a BS admin has to switch the users
102 state to confirmned. As long as that has not happened the user can
103 not log in correctly. 
104