1 WebAuth Installation Instructions 2 3OVERVIEW 4 5 These installation instructions are for the typical WebAuth user who 6 wants to set up a web server with content protected by WebAuth and 7 take advantage of an existing site WebAuth infrastructure (including a 8 login server and WebKDC). For details on how to install the site 9 infrastructure, which is more complex and only has to be done once at 10 each site, see doc/install-webkdc. 11 12 If you have installed the Debian or Ubuntu packages, please see 13 /usr/share/doc/libapache2-webauth/README.Debian.gz, which is more 14 complete and specific for using those packages than these 15 instructions. 16 17PREREQUISITES 18 19 Make sure that you have all of the required packages installed. 20 WebAuth is implemented as Apache 2.x modules, and therefore requires 21 an installation of Apache 2.0.43 or later built with SSL and dynamic 22 modules. There are reports of problems with Apache 2.0.x as shipped 23 with Solaris 10 x86, so Apache 2.2 or later is recommended. It also 24 requires Kerberos, cURL, and OpenSSL 0.9.7 or later (for AES support). 25 See README for more version dependencies. 26 27 In order to build the LDAP module, Cyrus SASL 2.x and OpenLDAP are 28 also required. 29 30 Note that all of these packages should be installed on local disk. We 31 do not recommend using libraries installed on shared file systems such 32 as AFS, since the reliability of your web server will then be tied to 33 the availability of that remote file system. The required libraries 34 aren't large, particularly given the average size of modern disks. 35 36 If you build your own Apache 2.x server, you'll want to use a 37 configure invocation like: 38 39 ./configure --enable-so --enable-ssl --with-ssl=/usr/local 40 41 (changing the last if your OpenSSL is installed somewhere else). Any 42 pre-packaged Apache server should be built this way. 43 44 If you are building a Git clone of the WebAuth distribution (as 45 opposed to a packaged release, which already includes the generated 46 configure script), cd to the top of the source tree and run: 47 48 ./autogen 49 50 to generate the configure script. Autoconf 2.64 and Automake 1.11 or 51 later are required, Perl is required to generate the man pages, and 52 xml2rfc is required to build the protocol documentation. 53 54CONFIGURING THE BUILD 55 56 Run configure. The command will look something like: 57 58 ./configure --with-apxs=/usr/local/apache2/bin/apxs \ 59 --with-openssl=/usr/local --with-ldap=/usr/local 60 61 configure will detect various things about your system and will 62 generate the makefiles and include files required to build WebAuth. 63 64 Adjust the paths to match where you have installed those packages. 65 You can omit --with-openssl and --with-ldap if the packages are 66 installed in locations automatically searched by your compiler and 67 linker (which will be the case if you're using Linux and the packages 68 that come with your Linux distribution). 69 70 You can omit --with-apxs if the right version of apxs is in your path. 71 72 Normally, configure will use krb5-config to determine the flags to use 73 to compile with your Kerberos GSS-API libraries. If krb5-config isn't 74 found, it will look for the standard Kerberos libraries in locations 75 already searched by your compiler. If the krb5-config script first in 76 your path is not the one corresponding to the Kerberos libraries you 77 want to use or if your Kerberos libraries and includes aren't in a 78 location searched by default by your compiler, you need to specify 79 --with-krb5=PATH: 80 81 ./configure --with-krb5=/usr/local 82 83 You can also individually set the paths to the include directory and 84 the library directory with --with-krb5-include and --with-krb5-lib. 85 You may need to do this if Autoconf can't figure out whether to use 86 lib, lib32, or lib64 on your platform. If these flags are used, any 87 krb5-config script is ignored. 88 89 To specify a particular krb5-config script to use, either set the 90 PATH_KRB5_CONFIG environment variable or pass it to configure like: 91 92 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config 93 94 To not use krb5-config and force library probing even if there is a 95 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent 96 path: 97 98 ./configure PATH_KRB5_CONFIG=/nonexistent 99 100 Similarly, normally configure will use curl-config to determine the 101 flags to use to compile with cURL. If curl-config isn't found, it 102 will look for the standard cURL library in the locations already 103 searched by your compiler. If the curl-config script first in your 104 path is not the one corresponding to the cURL libraries you want to 105 use or if your cURL libraries and includes aren't in a location 106 searched by default by your compiler, you need to specify 107 --with-curl or --with-curl-libs and --with-curl-include as above. 108 Similarly, you can pass CURL_CONFIG to the configure script to change 109 which curl-config script is used. 110 111 You may optionally build Perl bindings for libwebauth by passing the 112 --enable-perl option to configure. If you do this, whatever version 113 of Perl is found first on your path will be used to build the Perl 114 bindings. You can override this check by setting the environment 115 variable PERL to the full path of the Perl binary that you want to 116 use. 117 118 Pass --enable-silent-rules to configure for a quieter build (similar 119 to the Linux kernel). 120 121 To change the compiler, set the environment variable CC before 122 running configure. Similarly, you can set CFLAGS to whatever 123 compiler flags you wish to build WebAuth with. See: 124 125 ./configure --help 126 127 for information about other available options. 128 129 WebAuth's library will by default be installed in /usr/local/lib, its 130 utility programs will be installed in /usr/local/bin, and its modules 131 will be installed in /usr/local/libexec/apache2/modules. To change 132 those locations, pass the --prefix option to configure with whatever 133 path you want to serve as the installation root. You can use 134 --libexecdir to set the parent directory of the module installation. 135 The modules will be installed in an apache2/modules subdirectory of 136 that directory. 137 138 The install location of the Perl modules will be derived from Perl's 139 configuration and is not affected by --prefix. 140 141COMPILING AND TESTING 142 143 Build WebAuth by running: 144 145 make 146 147 You can then also run: 148 149 make check 150 151 to have WebAuth build and run some internal consistency checks to make 152 sure that the library functions are working correctly. In order to do 153 more than limited tests of the low-level routines, you should first 154 create a keytab for testing use containing the key for a principal in 155 your local realm. See tests/config/README for instructions on what to 156 create and where to place the files. If you are building the Perl 157 bindings and modules, see perl/t/data/README for instructions about 158 further configuration required to test the WebAuth Perl bindings and 159 WebLogin code. 160 161 If a test case fails, please run the that individual test case with 162 verbose output using: 163 164 tests/runtests -o <name-of-test> 165 166 and send the WebAuth maintainers the output when reporting the 167 problem. 168 169INSTALLATION 170 171 Install WebAuth with: 172 173 make install 174 175 This will install the shared library, the Apache modules, and 176 optionally the the Perl bindings and WebLogin code as a Perl module. 177 At this point, the software is available but will not be used. 178 Without additional configuration changes to your server, WebAuth is 179 not active and will not protect any web pages. 180 181CONFIGURATION 182 183 Apache Directives 184 185 Add Apache directives for WebAuth to your httpd.conf or equivalent 186 file. The basic set of directives are: 187 188 LoadModule webauth_module \ 189 /usr/local/lib/apache2/modules/mod_webauth.so 190 191 WebAuthKeyringAutoUpdate on 192 WebAuthKeyringKeyLifetime 30d 193 194 WebAuthLoginURL "https://<your-webkdc>/login/" 195 WebAuthWebKdcURL "https://<your-webkdc>/webkdc-service/" 196 WebAuthWebKdcPrincipal service/webkdc 197 WebAuthKeyring conf/webauth/keyring 198 WebAuthKeytab conf/webauth/keytab 199 WebAuthServiceTokenCache conf/webauth/service_token.cache 200 201 WebAuthSSLRedirect on 202 203 In all instances above, replace <your-webkdc> with the hostname of the 204 WebKDC server at your site. conf/sample-webauth.conf contains a 205 heavily-commented version of these directives. 206 207 If you are testing a beta release, please also add: 208 209 WebAuthDebug on 210 LogLevel debug # change your existing setting to debug 211 212 so that your server will generate more complete logs if anything goes 213 wrong. This may also be useful if this is the first time you've 214 installed a WebAuth server. 215 216 Also, if you are using a self-signed certificate with your WebKDC, 217 you'll need to copy it to a local file (like conf/webauth/webkdc.cert) 218 and add the following directive: 219 220 WebAuthWebKdcSSLCertFile conf/webauth/webkdc.cert 221 222 so that the WebAuth Apache module can verify the WebKDC. 223 224 Keytab and Keyring 225 226 Make sure that the conf/webauth directory exists: 227 228 cd <apache-root> 229 mkdir -p conf/webauth 230 231 where <apache-root> is the root of your Apache 2.x installation. This 232 directory must be writable by the running web server (and by the child 233 servers, not just the main server), so if you have User and Group 234 directives in your httpd.conf, <apache-root>/conf/webauth should be 235 writable by that user and group. 236 237 You can put these files somewhere else if you wish. Just change 238 WebAuthKeyring and WebAuthKeytab in your Apache configuration. Only 239 the keyring directory and file need to be writable by the Apache 240 process. The keytab just needs to be readable. 241 242 Then, install a keytab in <apache-root>/conf/webauth/keytab (or 243 elsewhere if you chose to put it somewhere else). The recommended 244 principal name is webauth/<your-system> where <your-system> is the 245 fully qualified, all-lowercase name of your system. How to obtain a 246 keytab will depend on your local site and how your Kerberos KDC is set 247 up. 248 249 After installing the keytab, make sure that it is readable by the user 250 that the web server runs as. (It may have been created only readable 251 by root.) 252 253 SSL Certificate 254 255 Install an SSL certificate for your system, either a self-signed 256 certificate or one signed by whatever certificate authority you 257 normally use. All access to WebAuth-protected web pages must be 258 through SSL to preserve the security of the WebAuth authentication 259 tokens. 260 261 If you have not installed an SSL certificate before, there are 262 instructions available as part of the mod_ssl FAQ. See 263 <http://httpd.apache.org/docs/2.2/ssl/ssl_faq.html#realcert>. Debian 264 users can quickly install a self-signed certificate with the 265 apache2-ssl-certificate utility that comes with the Apache package. 266 267 If you are using the Debian or Ubuntu Apache packages, you will need 268 to explicitly enable the SSL Apache module with a2enmod ssl. You will 269 then also need to configure the location of your SSL certificate and 270 key file. For Debian and Ubuntu, the best location for the 271 certificate is /etc/ssl/certs, and for the key is /etc/ssl/private. 272 Example configuration: 273 274 SSLCertificateFile /etc/ssl/certs/<hostname>.pem 275 SSLCertificateKeyFile /etc/ssl/private/<hostname>.key 276 SSLCipherSuite HIGH:MEDIUM:!ADH:!SSLv2:@STRENGTH 277 SSLProtocol all -SSLv2 278 279 The last two configuration lines disable weak SSL ciphers. You can 280 use similar configuration directives for other operating systems, but 281 may need to change SSLCertificateFile and SSLCertificateKeyFile. 282 283 See /usr/share/doc/apache2.2-common/README.Debian.gz for more 284 information about configuring SSL on Debian and Ubuntu systems, 285 including how to generate and use self-signed certificates. 286 287 If your certificate came with intermediate CA certificates, you may 288 need to save them on your system (/etc/ssl/certs is recommended for 289 Debian and Ubuntu systems) and configure that file in Apache as well 290 with: 291 292 SSLCertificateChainFile /etc/ssl/certs/<chain-name>.crt 293 294 replacing <chain-name> with something documenting the intermediate CA 295 certificate chain stored in that file. 296 297 Basic Testing 298 299 Restart the server to pick up the configuration changes, and check 300 your error log for any errors indicating a problem with the WebAuth 301 installation. If you are using the default Apache 2.x setup, be sure 302 to start Apache with apachectl startssl to enable SSL. 303 304 At this point, WebAuth is available to your web server and will be 305 initialized when your server starts, but is not as yet being used to 306 protect any web pages. This can now be configured. For the most 307 basic use of WebAuth, just requiring a valid user login to view a 308 portion of the web pages served out by the server, add the lines: 309 310 AuthType WebAuth 311 require valid-user 312 313 to the <Directory> block for the portion of your web site that you 314 wish to protect. (To restrict access by privilege group, see the 315 instructions below on setting up the LDAP module.) 316 317 LDAP Configuration 318 319 If you want to have your WebAuth server do LDAP directory queries, 320 either to put directory information into environment variables or to 321 use LDAP-based privilege groups for access control, you need to 322 configure the mod_webauthldap module. The basic set of directives 323 are: 324 325 LoadModule webauthldap_module \ 326 /usr/local/lib/apache2/modules/mod_webauthldap.so 327 328 WebAuthLdapHost ldap.example.com 329 WebAuthLdapBase dc=example,dc=com 330 WebAuthLdapAuthorizationAttribute privilegegroup 331 332 WebAuthLdapKeytab conf/webauth/keytab 333 WebAuthLdapTktCache conf/webauth/krb5cc_ldap 334 335 The first three configuration settings will vary considerably given 336 the name and configuration of your local LDAP server. For more 337 information on what these settings do, see the mod_webauthldap manual. 338 Please note that the WebAuth LDAP module only supports Kerberos 339 GSS-API binds at this time. 340 341 Once you've added that configuration and restarted Apache, LDAP 342 lookups are available to your web server. This can now be configured. 343 To restrict access to a given set of pages by membership in a 344 privilege group, add the lines: 345 346 AuthType WebAuth 347 require privgroup example:staff 348 349 to the <Directory> or <Location> block for the portion of your web 350 site that you wish to protect. example:staff is whatever privilege 351 group you want to use. 352 353 To put various directory attributes related to the current 354 authenticated user into the environment, additionally add lines like: 355 356 WebAuthLdapAttribute displayName 357 WebAuthLdapAttribute mail 358 359 to the <Directory> or <Location> block. The attributes can be any 360 attributes your server has access to read, and the corresponding 361 values from your LDAP server will be put into environment variables of 362 the form WEBAUTH_LDAP_<attribute>, or in this case into the variables 363 WEBAUTH_LDAP_DISPLAYNAME and WEBAUTH_LDAP_MAIL. 364 365RUNNING THE MODULE TEST SUITE 366 367 You can now test WebAuth if you wish (and if this is the first time 368 that you've set up WebAuth, it's recommended). WebAuth comes with a 369 set of test pages that you can use to configure your installation with 370 various different configuration options. 371 372 To install this test suite, copy (recursively) the files in 373 tests/mod_webauth/conf into your Apache configuration directory and 374 the files in tests/mod_webauth/htdocs under your Apache document root. 375 376 Now, edit your httpd.conf file and add the line: 377 378 Include conf/webauth-tests.conf 379 380 and make sure that the basic WebAuth configuration directives are in 381 your httpd.conf file as described above, or uncomment them in the 382 webauth-tests.conf file. 383 384 After restarting Apache, you should now be able to go to the URL 385 https://<your-server>/tests/, where <your-server> is the name of your 386 web server, to see the test suite. Documentation on how to walk 387 through all of the tests can be found in doc/test-plan. 388 389CONCLUSION 390 391 Congratulations! You have a working WebAuth server. You can now add 392 AuthType WebAuth and require valid-user (or require lines for 393 particular users, or for groups containing user identities as returned 394 by WebAuth) to protect the content served by your web server, and make 395 use of the REMOTE_USER or WEBAUTH_USER environment variables in your 396 CGI scripts. You can also use require privgroup directives and 397 request directory attributes if you have configured the LDAP module as 398 well. 399 400LICENSE 401 402 Copyright 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2014 403 The Board of Trustees of the Leland Stanford Junior University 404 405 Copying and distribution of this file, with or without modification, 406 are permitted in any medium without royalty provided the copyright 407 notice and this notice are preserved. This file is offered as-is, 408 without any warranty. 409