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 The superuser login value in piwik itself should also correspond to a proper
  16 user in CAS.
  17
  18 So a way to make this work in *new* piwik installations is:
  19
  20  * In main piwik configuration, set the "login" in [superuser] section to
  21    correspond to an actual CAS user.
  22  * Enable the CASLogin plugin (see "Installation" below).
  23  * Log in as the superuser. Go to Settings -> Users. Add a username (just
  24    the actual username is needed, other data can be left empty). And for that
  25    username, add some rights.
  26
  27 A further authorization and auto-provisioning mechanism can be written based
  28 on specific SAML attributes or any other data. See "Further Customization,
  29 Hacking" below.
  30
  31
  32 == Installation ==
  33
  34  * Disable the "Login" plugin in administration panel.
  35  * Enable the "CASLogin" plugin.
  36  * In your main config/config.ini.php piwik configuration file, add a section that reads like this:
  37
  38 {{{
  39 [caslogin]
  40 protocol = SAML_VERSION_1_1
  41 host = login.example.org
  42 port = 443
  43 }}}
  44
  45 Option "protocol" is one of CAS_VERSION_1_0, CAS_VERSION_2_0 or SAML_VERSION_1_1 .
  46
  47
  48 == Additional Options ==
  49
  50 By default, only the user defined in piwik configuration (config/config.ini.php) in
  51 the [superuser] section is regarded as a superuser / root administrator.
  52
  53 However, with the CAS Login scheme, you might need to add additional accounts as
  54 superusers, each one of them logging in as normal with their own password.
  55
  56 If you'd like to do that, add these accounts in section [caslogin] as follows:
  57
  58 {{{
  59 additionalsuperusers[] = uid1
  60 additionalsuperusers[] = uid2
  61 }}}
  62
  63
  64 == Further Customization, Hacking ==
  65
  66 If you want to grab some additional attributes, e.g. SAML, from your login
  67 server, then you can edit the file Auth.php. Search for "Additional
  68 Attributes", that's where they can be added to the session and made available
  69 to piwik.
  70
  71 If you want a user to be added automatically to the piwik users database, edit
  72 Auth.php and search for "User Autocreate". This is the place where you can
  73 enable adding to the database and probably add some default ACLs later,
  74 depending on specific SAML attributes or anything else you use in your CAS
  75 solution. The superuser can add rights by hand, or you can choose to add
  76 them at this step using the piwik API.
  77
  78
  79 == TODO ==
  80
  81  * Credit the authors of the plugins CASLogin was based on
  82  * Remove some duplicate functions
  83  * Allow more configurable provisioning
  84  * Make default login page somewhat more elegant
  85
  86
  87 == Author ==
  88
  89 Alexandros Vellis
  90 National & Kapodistrian University of Athens
  91 Network Operations Centre
  92 avel at noc.uoa.gr
  93 http://www.noc.uoa.gr
  94 http://email.uoa.gr