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