1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
|
WebKDC Installation Instructions
These are supplemental installation instructions for installing a WebKDC.
Each site running WebAuth only needs one WebKDC for the entire site, so
normally users do not need to follow these steps. They are here only for
site WebAuth administrators.
If you have installed the Debian or Ubuntu packages, please see
/usr/share/doc/libapache2-webkdc/README.Debian.gz and
/usr/share/doc/webauth-weblogin/README.Debian.gz instead of these
instructions. They are more complete and specific for people using those
packages.
It is important to always keep in mind that the security of the entire
WebAuth system depends on the security of the WebKDC. A compromise of the
WebKDC system would allow an attacker to steal usernames and passwords for
anyone using the login server and to be able to forge arbitrary
authentication credentials and use them to contact WebAuth servers. This
system should be locked down as tightly as possible and proactively
monitored for security.
We also recommend giving the WebKDC and WebLogin server its own separate
domain name. This will generally require giving it a separate IP address
unless you can use wildcard SSL/TLS certificates, but it's useful to
separate the cookies used by the WebLogin server from cookies used by
applications. This is particularly important if you use Active Directory
as your KDC and do ticket delegation. Active Directory Kerberos tickets
can be fairly large, and the combination of WebKDC cookies, WebAuth proxy
cookies, credential cookies, and id cookies can result in a Cookie header
that's longer than the HTTP protocol permits.
1. Follow the standard WebAuth installation instructions as given in the
INSTALL file at the top of the source tree, but also pass the flags
--enable-webkdc, --disable-mod_webauth, and --disable-mod_webauthldap
to ./configure. This will install only the WebKDC module, and it will
also install the Perl bindings (into the site_perl directory for the
first version of Perl found on your path).
2. You'll need to install the following Perl modules from CPAN:
CGI::Application
CGI::Application::Plugin::AutoRunmode
CGI::Application::Plugin::Forward
CGI::Application::Plugin::Redirect
CGI::Application::Plugin::TT
libwww (LWP)
Crypt::SSLeay -or- IO::Socket::SSL (for LWP https support)
MIME::Base64 (part of Perl itself since 5.7.3)
Template (Template Toolkit)
URI
XML::Parser
If you want support for replay detection and rate limiting, you will
also need:
Cache::Memcached
Digest::SHA (part of Perl itself since 5.9.3)
You'll probably also want to install and configure mod_fastcgi as
well, though it's not a requirement. If you decide to install it,
you'll need to configure it like so:
FastCGIConfig -initial-env LD_LIBRARY_PATH
LoadModule fastcgi_module modules/mod_fastcgi.so
<Directory "/usr/local/share/weblogin">
AllowOverride All
Options Indexes FollowSymlinks +ExecCGI
AddHandler fastcgi-script .fcgi
Order allow,deny
Allow from all
</Directory>
This assumes the WebLogin scripts and templates are installed into
/usr/local/share/weblogin, which is the default installation location.
You can put them anywhere; just adjust the path above and the paths in
Apache configuration options below accordingly.
3. Add Apache directives for the WebKDC. The basic set is:
LoadModule webkdc_module \
/usr/local/lib/apache2/modules/mod_webkdc.so
WebKdcServiceTokenLifetime 30d
WebKdcKeyring conf/webkdc/keyring
WebKdcKeytab conf/webkdc/keytab
WebKdcTokenAcl conf/webkdc/token.acl
If you are testing a beta release, please also add:
WebKdcDebug on
so that your server will generate more complete logs if anything goes
wrong. This may also be useful if this is the first time you've
installed a WebKdc. You'll also want to set LogLevel to debug:
LogLevel debug
4. Set up a script aliases to run the login, logout, and pwchange CGI
services by adding the following lines to your Apache configuration:
ScriptAlias /login "/usr/local/share/weblogin/login.fcgi"
ScriptAlias /logout "/usr/local/share/weblogin/logout.fcgi"
ScriptAlias /pwchange "/usr/local/share/weblogin/pwchange.fcgi"
Alias /images "/usr/local/share/weblogin/generic/images/"
Alias /help.html \
"/usr/local/share/weblogin/generic/templates/help.html"
You may want to add the first three only inside a VirtualHost block
that requires SSL to ensure that they are only accessible over SSL.
The pwchange service is optional, without it WebLogin will not be able
to correctly handle expired passwords and will instead just not allow
users with expired passwords to authenticate.
5. Set up a <VirtualHost> directive using SSL for the WebKDC service.
Inside that directive, set a handler for the URL /webkdc-service. In
other words, use a configuration block like:
<VirtualHost _default_:443>
SSLEngine on
...
<Location /webkdc-service>
SetHandler webkdc
</Location>
...
</VirtualHost>
6. Create the conf/webkdc directory.
cd <apache-root>
mkdir -p conf/webkdc
7. Install the WebKDC files used by the login server, the portion that
runs on the regular SSL port. cd to the root of the WebAuth source
tree and then run:
make install
This will install Perl modules into the site_perl directory of
whatever Perl was found by configure.
8. If you want to support changing expired passwords and you configured a
URL for pwchange.fcgi above, create /etc/webkdc/webkdc.conf and put a
line like:
$EXPIRING_PW_URL = "/pwchange";
in it, where the URL should be the URL you configured to point to the
pwchange.fcgi script. It shouldn't include the scheme or hostname
since browsers dislike POST to a URL that's fully-qualified for
security reasons.
Also, if the path and URL in <site-perl>/WebKDC/Config.pm are not
correct for your site (see docs/weblogin-config for the defaults), you
will also need to create an /etc/webkdc/webkdc.conf for that if you
haven't already and, in it, put lines like:
$KEYRING_PATH = "../conf/webkdc/keyring";
$URL = "https://localhost/webkdc-service/";
changing the values to what is appropriate for your site. If you
follow the default recommendations on where to place the keyring and
CGI scripts, you shouldn't have to change anything other than the
$EXPIRING_PW_URL setting. There are other settings you can change;
see doc/weblogin-config for all the details.
9. Install a keytab for the WebKDC. This keytab must be for the same
identity as is mentioned in the WebAuthWebKdcPrincipal configuration
option in the Apache configuration of individual WebAuth servers. The
keytab should for the identity service/webkdc, and should be installed
in <apache-root>/conf/webkdc/keytab or in whatever path the Apache
configuration option WebKdcKeyring references.
(Note that you can use some other identity if you prefer, as this is
part of the WebAuth module configuration. You'll just then have to
configure all of your systems using the WebAuth module to use whatever
other identity you chose.)
10. Create a file named token.acl in <apache-root>/conf/webkdc. This file
specifies which tokens various server identities are allowed to
create. There is an example file in conf/token.acl, so for an initial
configuration, do:
cp conf/token.acl <apache-root>/conf/webkdc/
uncomment the first line, and change the ACL pattern to match your
realm. This will allow any server with a webauth/* keytab to get an
id token (which identifies a user but conveys no other privileges).
This is a good place to start. See the mod_webkdc manual for more.
11. If you want to use replay caching of successful login attempts or rate
limiting of failed login attempts, set up a memcached server. If you
have a single WebLogin server, configure memcached to listen only to
localhost. If you have a pool of WebLogin servers, they will need to
share a memcached server. Note that memcached doesn't have much in
the way of protocol security, so normally it is protected using
firewalls or iptables to disallow connections from systems other than
the WebLogin servers.
Then, set the following variable in /etc/webkdc/webkdc.conf:
@MEMCACHED_SERVERS = ('127.0.0.1:11211');
This server setting is for a memcached only listening to localhost, on
the default port. Change the IP address and port as necessary for
your environment.
Nothing particularly critical or security-sensitive is stored in
memcached; the most an attacker can do is remove an account rate limit
or create a denial of service attack.
12. Configure replay rejection of successful login attempts if desired.
This requires setting up a memcached server (step 11).
Replay rejection prevents using the back button in a browser to replay
the authentication to WebLogin and is recommended as partial security
protection against attackers with access to browser history. To
enable it, set the following variable in /etc/webkdc/webkdc.conf:
$REPLAY_TIMEOUT = 300;
The value should be set to whatever the WebKdcTokenMaxTTL setting is
for your WebKDC, which by default is 300 seconds (five minutes).
13. Configure rate limiting of failed logins if desired. This requires
setting up a memcached server (step 11).
If configured, WebLogin will lock out an account after the configured
number of failed login attempts, rejecting all attempts to
authenticate (successful or unsuccessful) until the timeout interval
expires. To enable it, set the following variable in
/etc/webkdc/webkdc.conf:
$RATE_LIMIT_THRESHOLD = 5;
The rate limit setting allows five failed login attempts before
locking out a user for the default interval (five minutes). Adjust
this setting based on your local requirements. You may also want to
change $RATE_LIMIT_INTERVAL to something other than 300 (five minutes
in seconds). See docs/weblogin-config for more information.
14. Restart the Apache web server. You should now have a working WebKDC
and login server, which you can point a WebAuth server at. You will
need to install a regular WebAuth server following the instructions in
INSTALL to be able to test your WebKDC.
If you want to use let clients use SPNEGO to authenticate to the WebLogin
front-end with fallback to standard password authentication, see the
separate install-spengo documentation.
If you want to enable multifactor authentication, see the separate
install-multifactor documentation.
The WebLogin component of the WebKDC, which handles the login user
interface, is configured with /etc/webkdc/webkdc.conf by default.
However, the path of this configuration file can be overridden by setting
the WEBKDC_CONFIG environment variable to point to some other path. Since
one of the configuration settings is the path to the templates, this can
be used to provide multiple different WebLogin interfaces at different
URLs using the same code.
One convenient way to do that inside Apache is to use mod_env and the
SetEnv directive. So, for example, after using the above instructions to
set up a /login URL that uses your default local templates, you could add
an Apache configuration like:
ScriptAlias /login-special "/usr/local/share/weblogin/login.fcgi"
<Location "/login-special">
SetEnv WEBKDC_CONFIG /etc/webkdc/special.conf
</Location>
Then, users who go to the /login-special URL instead of /login will launch
a WebLogin instance that uses /etc/webkdc/special.conf as the
configuration instead. That configuration could then point to different
templates, different settings, etc.
Be aware that this won't work if you use FastCGI, since the FastCGI
process will load a single configuration and use it to process all
requests. If you want to do this in combination with FastCGI, you will
need to arrange for multiple FastCGI applications to be spawned with
different environments.
-----
Copyright 2003, 2004, 2006, 2009, 2010, 2011, 2012
The Board of Trustees of the Leland Stanford Junior University
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved. This file is offered as-is, without any
warranty.
|