README
1Login Authentication plugin for SquirrelMail
2============================================
3Ver 3.0, 2012/05/29
4
5
6Copyright (c) 2004-2012 Paul Lesniewski <paul@squirrelmail.org>
7Copyright (c) 2001 Tyler Akins
8
9
10
11Description
12===========
13
14This plugin tells SquirrelMail how to understand when users
15have been externally authenticated, in which case the SquirrelMail
16login page is unnecessary. Common uses of this plugin are for
17environments that employ HTTP authentication or have implemented
18single sign-on systems. Remember that SquirrelMail still needs
19to authenticate against your IMAP server, so SquirrelMail still
20needs to know what credentials to use and how to get them. Assuming
21you've coordinated your IMAP authentication with your external
22web authentication, this plugin helps with those tasks.
23
24The default behavior of this plugin assumes HTTP authentication
25where the web server makes the username and password available to
26PHP. In this kind of environment, all you need to do is ensure
27that the user credentials in your HTTP authentication system match
28those that your IMAP server uses.
29
30This plugin also supplies modules to handle SAML single sign-on
31authenticated users in a couple different ways and allows you to
32easily create custom modules for any other system. See the
33configuration file for more details.
34
35By default, if a user is not externally authenticated, the user
36is allowed to log in using the standard SquirrelMail login page,
37but this plugin can be configured to disallow this, instead
38referring the user to your external login page.
39
40
41
42Donations
43=========
44
45If you or your company make regular use of this software,
46please consider supporting Open Source development by
47donating to the authors or inquire about hiring them to
48consult on other projects. Donation/wish list links for
49the author(s) are as follows:
50
51Paul Lesniewski: https://squirrelmail.org/donate_paul_lesniewski.php
52
53
54
55License
56=======
57
58This plugin is released under the GNU General Public
59License (see the file COPYING for details).
60
61
62
63Requirements
64============
65
66 * SquirrelMail version 1.4.0 or above, or version 1.4.23
67 or above when using the "trusted_saml" SAML module
68
69 * Compatibility plugin version 2.0.7 or above, unless
70 using SquirrelMail version 1.4.10+ or 1.5.2+
71
72 * PHP Zlib support (compile with --with-zlib) only if
73 you are using the compression feature with the
74 "authenticated_saml" module
75 See: http://php.net/manual/en/zlib.installation.php
76
77
78
79Troubleshooting
80===============
81
82 * Unless users authenticating externally have set the
83 "Options-->Display Preferences-->Use Javascript" option to
84 "Always", JavaScript functionalities will not be enabled
85 because the "Autodetect" setting uses an autodetection scheme
86 in the SquirrelMail login page, which is skipped by this
87 plugin. If you so choose, you can force all users to "Always"
88 by using one of the methods described here:
89
90 http://www.squirrelmail.org/docs/admin/admin-5.html#ss5.6
91
92 * If changes to the configuration file don't seem to be having
93 any effect, ensure that there are not two Login Authentication
94 configuration files, one in the login_auth directory and
95 one in the main SquirrelMail config directory (named
96 "config_login_auth.php"). The one in the main SquirrelMail
97 config directory will always override the one in the
98 login_auth directory.
99
100 * Note that this plugin is not compatible with some plugins
101 that run on the login screen, such as the Multilogin plugin
102
103 * When using the "trusted_saml" module, did you set SquirrelMail's
104 IMAP authentication mechanism to "plain"? You can do that in
105 the main SquirrelMail configuration file or use the configuration
106 tool to do so: config/conf.pl ==> 2. Server Settings ==>
107 A. Update IMAP Settings ==> 6. Authentication type
108
109 * When using the "trusted_saml" module, did you set
110 $trusted_saml_username and $trusted_saml_username in the
111 configuration file? This plugin should only be used AFTER
112 you have confirmed that you have a working single sign-on
113 authentication system in place. You can find a few tips for
114 doing so using a Shibboleth-based system in the
115 contrib/README.Shibboleth file, but if you have more detailed
116 questions, you need to search for the answers in locations
117 specific to Shibboleth, which does NOT include the plugin
118 authors or the SquirrelMail mailing lists.
119
120 * When using HTTP authentication, did you correctly configure
121 HTTP-based authentication on your web server? This plugin
122 should only be used AFTER you have confirmed that you have a
123 working HTTP authentication system in place. You can find a
124 few tips for doing so in the contrib/README.HTTP_authentication
125 file, but if you have more detailed questions, you need to
126 search for the answers in locations specific to your web
127 server software, which does NOT include the plugin authors
128 or the SquirrelMail mailing lists.
129
130 * For the "authenticated_saml" module, you should first ensure
131 that you have a working single sign-on authentication system
132 in place. You can find a few tips for doing so using a
133 crudesaml/mod_auth_mellon-based system in the contrib/README.crudesaml
134 file, but if you have more detailed questions, you need to
135 search for the answers in locations specific to crudesaml or
136 mod_auth_mellon, which does NOT include the plugin authors or
137 the SquirrelMail mailing lists.
138
139
140
141Help Requests
142=============
143
144Before looking for help elsewhere, please try to help yourself:
145
146 * Read the Troubleshooting section herein.
147
148 * Look to see if others have already asked about the same issue.
149 There are tips and links for the best places to do this in
150 the SquirrelMail mailing list posting guidelines:
151 http://squirrelmail.org/wiki/MailingListPostingGuidelines
152 You should also try Google or some other search engine.
153
154 * If you cannot find any information about your issue, please
155 first mail your help request to the squirrelmail-plugins
156 mailing list. Information about it can be found here:
157 http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
158 You MUST read the mailing list posting guidelines (see above)
159 and include as much information about your issue (and your
160 system) as possible. Including configtest output, any debug
161 output, the plugin configuration settings you've made and
162 anything else you can think of to make it easier to diagnose
163 your problem will get you the most useful responses. Inquiries
164 that do not comply with the posting guidelines are liable to
165 be ignored.
166
167 * If you don't get any replies on the mailing list, you are
168 welcome to send a help request to the authors' personal
169 address(es), but please be patient with the mailing list.
170
171
172
173TODO
174====
175
176 * Ideas?
177
178
179
180Change Log
181==========
182
183 3.0 2012/05/29 Paul Lesniewski <paul@squirrelmail.org>
184 * Added the ability to use this plugin for other external
185 login systems (aside from just HTTP authentication), such
186 as some single sign-on systems.
187 * Thanks to Emmanuel Dreyfus for help with the "authenticated_saml"
188 module and Victoriano Giralt for help with the "trusted_saml" module
189 * Added compatibility with the Login Manager plugin
190 * Added configuration file that allows administrators to
191 fine-tune the behavior of this plugin, particularly if
192 using a custom single sign-on system. Those using HTTP
193 authentication do not need to create a configuration file
194 of their own - the default behavior will suffice in these
195 cases.
196
197 2.1 2008/06/18 Paul Lesniewski <paul@squirrelmail.org>
198 * Log out of IMAP connection made during login page hook
199 * Update plugin documentation and some minor code updates
200 to bring into conformance with newest plugin specifications
201 * Added custom signout page that reflects the true nature
202 of disposing HTTP authentication credentials
203
204 2.0 2004/10/06 Paul Lesniewski <paul@squirrelmail.org>
205 * Rewrote the whole plugin so that it works as a normal
206 plugin (as opposed to a bit of a hack)
207 * If username/password pairs don't match, SquirrelMail's login
208 page is correctly shown again
209 * Conformance with SquirrelMail plugin requirements and
210 other cleanup
211
212 1.1 2001/05/02 Tyler Akins
213 * Removed serious security issue -- the password was being
214 logged in the web server logs.
215
216 1.0 2001/05/01 Tyler Akins
217 * Initial release
218
219