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