WebAuth Weblogin Server for Debian
----------------------------------
This package contains the central Weblogin server for a WebAuth
installation. Only one server (or one pool of load-balanced servers) at a
given site need to run this package. libapache2-mod-webkdc should also be
installed on the same server as this package is running on.
This package comes with a very generic set of page templates, suitable for
getting started. You will probably want to customize those templates for
your local site, and you should definitely customize the help.html web
page to contain contact information for your local help desk. The generic
templates are installed in /usr/share/webauth/generic; you can just copy
that whole directory with cp -r to another directory and make whatever
changes you want. Then, change the paths in the two Alias lines below to
point to your directory instead of the generic directory and change the
TEMPLATE_PATH in /etc/webkdc/webkdc.conf to point to the new path.
(You could then, if you wished, make a Debian package of your local
templates to make them easier to maintain.)
See:
for more information about WebAuth, including copies of the module manuals
and places to contact to get help with the installation.
Installing the Weblogin Server
------------------------------
The Weblogin server is implemented as Perl CGI scripts. In order to
finish the installation, you need to add Apache configuration directives
to send the login and logout URLs to these CGI scripts and to allow the
images and help page they use to be found.
Add the following configuration to a virtual host in:
/etc/apache2/sites-available/weblogin
or wherever you put local Apache configuration:
AllowOverride None
Options +ExecCGI
SSLRequireSSL
Order allow,deny
Allow from all
ScriptAlias /login "/usr/share/weblogin/login.fcgi"
ScriptAlias /logout "/usr/share/weblogin/logout.fcgi"
ScriptAlias /pwchange "/usr/share/weblogin/pwchange.fcgi"
Alias /help.html "/usr/share/weblogin/generic/templates/help.html"
Alias /images/ "/usr/share/weblogin/generic/images/"
(If you put this in sites-available, you then need to enable the site with
a2ensite.)
The ScriptAlias and Alias directives can, of course, be changed if you
want the Weblogin server to live at a different URL (although note that
the default templates expect /help.html and /images to work and may need
to be modified otherwise). The pwchange configuration is optional, but
without it WebLogin will not be able to correctly handle expired passwords
and will instead just not allow users with expired passwords to
authenticate.
Add the URL for the pwchange script, if you configured one, to
/etc/webkdc/webkdc.conf. If you used the recommended URL configured
above, the line to add is:
$EXPIRING_PW_URL = '/pwchange';
If you used a different URL, change the value of the setting. The host
and scheme of the URL should be omitted and should be the same as the
login URL, since otherwise browsers will reject the cross-site POST for
security reasons.
If you used something other than /webkdc-service as the URL to the WebKDC,
you will need to modify the $URL setting in /etc/webkdc/webkdc.conf to
point to the appropriate URL on localhost that the WebKDC is listening to.
Because the Weblogin server accepts Kerberos passwords from end-users, it
must only be available over SSL. The SSLRequireSSL above makes sure that
users only use SSL to contact the server, but you may also want to put the
above in a virtual host specifically for SSL and set up a separate non-SSL
virtual host that redirects all accesses to the SSL URL.
Now, reload Apache's configuration file with apache2ctl graceful. After
you've tested and everything is working, you will probably want to
customize the templates as described above.
Site Documentation
------------------
After you have configured both this server and the WebKDC, following the
instructions in /usr/share/doc/libapache2-mod-webkdc/README.Debian, you
should document the way WebAuth is configured at your site for other users
who are installing the WebAuth modules on individual web servers. I
recommend putting up a web page that contains the following information:
* The configuration needed for libapache2-mod-webauth (or any other
installation of WebAuth, regardless of platform, at your site). Users
who are installing WebAuth servers need to know the URL to the WebKDC
service, the URL to the Weblogin server, and the Kerberos principal
used by the WebKDC, choices that you had to make while installing.
I recommend using:
WebAuthLoginURL https://weblogin.example.com/login
WebAuthWebKdcURL https://weblogin.example.com/webkdc-service
WebAuthWebKdcPrincipal service/webkdc@example.com
where example.com is your domain. But as long as you configure this
package and libapache2-mod-webkdc consistently, you can use whatever
URLs and Kerberos principals you want.
* The naming convention for WebAuth Kerberos principals for individual
web servers. This needs to match the configuration that you put into
token.acl when configuring the WebKDC.
* How to download or otherwise obtain a Kerberos keytab at your site,
when someone is installing a new server. This will depend on how your
Kerberos realm is maintained.
You will also want to modify the templates for the Weblogin server as
mentioned above to include images, pointers, and help appropriate to your
local site.
Using SPNEGO
------------
The Weblogin scripts optionally support attempting to authenticate with
SPNEGO first before prompting the user with a username and password. If
the user is authenticated to Kerberos and their ticket caches are properly
accessible to the browser, this should work with Firefox on all platforms
and Safari on the Mac, at least. It may also work with IE depending on
your KDC setup.
To use SPNEGO in Debian, install the libapache2-mod-auth-kerb module (it
will do the SPNEGO protocol work) and then follow the instructions in
/usr/share/doc/webauth-weblogin/install-spnego.gz. The path to the
login.fcgi script will be different in the example ScriptAlias
configuration, but otherwise those instructions should work verbatim with
Debian.
Using FastCGI
-------------
The Weblogin scripts are written so that they can use FastCGI, but don't
require it.
If you want to use these scripts with FastCGI, you will need to install
the Apache modules for FastCGI. libapache2-mod-fcgid comes with Debian,
and libapache2-mod-fastcgi is available in the non-free Debian archive
(which is not part of Debian, but which is provided on the same servers
for the convenience of Debian users).
Once you have configured Apache to support FastCGI, add, to the
block in the installation instructions above, the line:
AddHandler fastcgi-script .fcgi
After you restart Apache with apache2ctl graceful, the Weblogin scripts
should run under FastCGI.
-- Russ Allbery , Sun, 13 Nov 2016 10:24:21 -0800