Fixed error in Auth::authenticate causing phpCAS::client to be called twice.
[piwik-CASLogin.git] / README
1 == Introduction ==
2
3 This plugin allows users to login to piwik using a CAS central login service.
4
5
6 == User Provisioning Rationale ==
7
8 CASLogin currently authenticates users against the CAS service, but then
9 authorizes them to piwik according to the user configuration tables inside
10 piwik itself.
11
12 To make this work, first you need to make sure that the user that logs in
13 also exists in piwik user tables and has some rights to view or edit sites.
14
15 So a way to make this work in *new* piwik installations is:
16
17  * Make sure a superuser exists with login corresponding to
18    an actual CAS user.
19  * Enable the CASLogin plugin (see "Installation" below).
20  * Log in as the superuser. Go to Settings -> Users. Add a username (just
21    the actual username is needed, other data can be left empty). And for that
22    username, add some rights.
23
24 A further authorization and auto-provisioning mechanism can be written based
25 on specific SAML attributes or any other data. See "Further Customization,
26 Hacking" below.
27
28
29 == Installation ==
30
31  * Disable the "Login" plugin in administration panel.
32  * Enable the "CASLogin" plugin.
33  * In your main config/config.ini.php piwik configuration file, add a section that reads like this:
34
35 {{{
36 [caslogin]
37 protocol = SAML_VERSION_1_1
38 host = login.example.org
39 port = 443
40 }}}
41
42 Option "protocol" is one of CAS_VERSION_1_0, CAS_VERSION_2_0 or SAML_VERSION_1_1 .
43
44
45 == Additional Options ==
46
47 You can add a custom image on login page by setting it in [caslogin] section:
48
49 {{{
50 loginimage = 'url-of-image'
51 }}}
52
53
54 == Further Customization, Hacking ==
55
56 If you want to grab some additional attributes, e.g. SAML, from your login
57 server, then you can edit the file Auth.php. Search for "Additional
58 Attributes", that's where they can be added to the session and made available
59 to piwik.
60
61 If you want a user to be added automatically to the piwik users database, edit
62 Auth.php and search for "User Autocreate". This is the place where you can
63 enable adding to the database and probably add some default ACLs later,
64 depending on specific SAML attributes or anything else you use in your CAS
65 solution. The superuser can add rights by hand, or you can choose to add
66 them at this step using the piwik API.
67
68
69 == TODO ==
70
71  * Credit the authors of the plugins CASLogin was based on
72  * Remove some duplicate functions
73  * Allow more configurable provisioning
74  * Make default login page somewhat more elegant
75
76
77 == Author ==
78
79 Alexandros Vellis
80 National & Kapodistrian University of Athens
81 Network Operations Centre
82 avel at noc.uoa.gr
83 http://www.noc.uoa.gr
84 http://email.uoa.gr