-
Notifications
You must be signed in to change notification settings - Fork 9
/
INSTALL
271 lines (200 loc) · 10.6 KB
/
INSTALL
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
===============================================================
University of Cambridge Web Authentication System (UcamWebAuth)
Apache Authentication Agent (mod_ucam_webauth) Installation
===============================================================
1. Build requirements
2. Building and installing the module
2.1 Building and installing using APXS
2.2 Building and installing RPMs
2.3 Installing from .deb
2.4 Static Linking
3. Operating requirements
4. Initial configuration
Note that a pre-compiled binary version of the module is available for
use on Microsoft Windows. Windows users should see README.WIN32 and
then read sections 3 'Operating requirements' and 4 'Initial
configuration' below.
1. Build requirements
=====================
* Apache
The module is only of any use when used with a copy of Apache,
version 2.0, 2.1, 2.2, or 2.4 (it may or may not work with
later versions). Apache comes as part of most Unix/Linux
distributions, though it may be necessary to install an additional
package, perhaps called httpd-devel, apache-devel, or apache2-devel
for access to the tools needed to build the module.
It is expected that support for Apache versions 2.0, and 2.1
will be dropped in a forthcoming release; the Apache Software
Foundation encourages users to upgrade to version 2.2 or 2.4.
* OpenSSL
The module uses the OpenSSL library. Again, this comes as part of
most Unix/Linux distributions, and it may be necessary to install an
additional package, perhaps called openssl-devel or libssl-dev, for
access to the tools needed to build the module.
* C compiler
The module is written in C, so building the module requires a C
compiler. Most Unix and Linux distributions install a C compiler by
default. MacOS users should see INSTALL.Platforms for instructions
on installing a C compiler and related tools.
2. Building and installing the module
=====================================
2.1 Building and installing using APXS
--------------------------------------
Apache is normally built so that new modules can be built as 'shared
objects' and plugged-in to Apache without having to rebuild the whole
program. Apache provides a tool, called apxs, to manage this
process. Providing your copy of Apache supports this, and most do,
then it's the easiest way to build the module. If, however, you run a
RPM or .deb based linux distribution, then using the appropriate
package will be more straightforward (see sections 2.2 & 2.3 below for
details).
You can check if your copy of Apache supports this feature by running
it with the '-l' command line option - if mod_so.c is shown
as one of the modules loaded then shared object support is available.
To build the module and copy it into the correct Apache directory,
first unpack the distribution tar file and cd into the directory it
creates:
tar zxf mod_ucam_webauth-<ver>.tar.gz
cd mod_ucam_webauth-<ver>
then issue the following command as root:
apxs -c -i -lcrypto mod_ucam_webauth.c
If your copy of the OpenSSL library isn't in a standard place it may
be necessary to modify the '-lcrypto' option. apxs may not be on
root's default path and may be renamed (e.g. to apxs2) on some
platforms - see INSTALL.Platforms for further details. apxs and
related files are sometimes provided by a httpd-devel, apache-devel,
or apache2-devel package which will need to be installed.
2.2 Building and installing RPMs
--------------------------------
The module is distributed as a 'Source RPM', for Apache
2.0/2.1/2.2/2.4. On RPM-based Linux systems it is straightforward to
use this to build a binary RPM which can then be installed like any
other package. This is particularly useful if you need to install the
module on a number of similar systems. This approach will only work
with copies of Apache that include shared object support (see
above). This is almost always the case with RPM-based distributions.
To build an RPM, download the appropriate Source RPM, cd to the
directory containing it, and then as root issue the command
rpmbuild --rebuild mod_ucam_webauth2-<ver>.src.rpm
Near the end of the resulting output will be a line identifying the
binary RPM that was built, such as
Wrote: /usr/src/redhat/RPMS/i386/mod_ucam_webauth2-<ver>.i386.rpm
can be installed by issuing, e.g., the command
rpm -Uvh /usr/src/redhat/RPMS/i386/mod_ucam_webauth2-<ver>.i386.rpm
Linux distributions vary somewhat in how they package Apache-related
software so the source RPM is unlikely to install on every possible
system. With a little experience of modifying RPMs it should be easy
enough to install the source RPM and modify the '.spec' file to work
with a new system. If you find you need to do this, please inform
[email protected] so that any changes can be included in
future versions.
2.4 Installing from .deb
------------------------
Binary .debs are available for Debian and Ubuntu. The Debian .debs
should be suitable for releases from "wheezy" (the current stable
release) onwards, whilst the Ubuntu .debs should be suitable for
releases from "lucid" (10.04.4 LTS) onwards. They are available for
i386 (32-bit) and amd64 (64-bit) archiectures. Debian "jessie" and
Ubuntu "trusty" (14.04 LTS) come with Apache 2.4, which requires
different packaging; so versions built for these releases are now also
provided. The eight .debs have the following filenames:
libapache2-mod-ucam-webauth_<ver>_amd64.deb [Debian, 64-bit]
libapache2-mod-ucam-webauth_<ver>_i386.deb [Debian, 32-bit]
libapache2-mod-ucam-webauth_<ver>_apache24_amd64.deb [Apache2.4, 64-bit]
libapache2-mod-ucam-webauth_<ver>_apache24_i386.deb [Apache2.4, 32-bit]
libapache2-mod-ucam-webauth_<ver>ubuntu_amd64.deb [Ubuntu, 64-bit]
libapache2-mod-ucam-webauth_<ver>ubuntu_i386.deb [Ubuntu, 32-bit]
libapache2-mod-ucam-webauth_<ver>apache24ubuntu_amd64.deb [Apache2.4, 64-bit]
libapache2-mod-ucam-webauth_<ver>apache24ubuntu_i386.deb [Apache2.4, 32-bit]
Install the appropriate .deb using dpkg -i.
Alternatively, you can build a binary .deb yourself; to do so,
download libapache2-mod-ucam-webauth_<ver>.dsc and
libapache2-mod-ucam-webauth_<ver>.tar.gz, (or the apache24 versions)
unpack the source archive:
dpkg-source -x libapache-mod-ucam-webauth_<ver>.dsc
And build a binary .deb:
cd libapache2-mode-ucam-webauth-<ver>
dpkg-buildpackage -us -uc
You can then install the resulting (unsigned) .deb as above.
2.4 Static Linking
-------------------
Apache can be built with all its modules linked into the main program
- so-called 'static linking'. To add mod_ucam_webauth to such an
installation it is necessary to copy the module into the unpacked
Apache source tree and then to rebuild Apache.
Change into the Apache build directory and copy mod_ucam_webauth.c
from an unpacked tar distribution to modules/aaa. Run the configure
script with the options as specified below in addition to any other
options you wish to set.
For an Apache 2 installation:
./configure --prefix=<PREFIX> \
--with-module=aaa:ucam_webauth
Issue the commands to build and install Apache in the usual way:
make
make install
Use the command
httpd -l
to check that the module has been successfully incorporated into the
Apache server. It should be listed as mod_ucam_webauth.c.
3. Operating requirements
=========================
* RSA Public Keys
UcamWebAuth uses RSA public key cryptography to verify that
authentication responses are sent only by the trusted authentication
server. The module needs access to the relevant RSA public
keys. Within the University of Cambridge, the keys used by the Raven
service are available from https://raven.cam.ac.uk/project/keys/
By default the module expects to find keys in a directory called
conf/webauth_keys/ within the Apache server's 'ServerRoot'
directory. INSTALL.Platforms documents the default ServerRoot for
some systems. If all else fails, trying to use the module with no
keys installed will result in an error message in the server's error
log which includes the expected path to the keys. The key file
location can also be set using the AAKeyDir directive (see
README.Config).
The names of the key files should not be changed - be aware that
they have no filename suffix but that some browsers may add .txt or
similar when downloading them.
* Timekeeping
The protocol used to communicate between the module and the
authentication server requires that both have access to accurate
time values. UcamWebAuth servers use NTP (Network Time Protocol) to
set their clocks. Providing the server using the module has a clock
synchronised by NTP or something similar then the default values for
the time-related parameters in the module should be fine.
If the server clock can't be assumed to be accurate within a second
or so than the AAClockSkew directive (see README.Config) _must_ be
used to provide an estimate of the maximum possible error in the
server's clock. Messages in the web server error log containing the
text 'local clock incorrect?' are likely if this parameter is not
used on a server that needs it.
4. Initial configuration
========================
If the module has been built as a dynamic shared object then it must
first be loaded into Apache. Your distribution may have its own way of
managing modules (see INSTALL.Platforms) but a default Apache
installation would require a 'LoadModule' directive such as:
LoadModule ucam_webauth_module modules/mod_ucam_webauth.so
in the Apache configuration file, replacing
'modules/mod_ucam_webauth.so' if necessary with the path to the file
containing the module, relative to ServerRoot if it doesn't start
'/'. This is not necessary if the module has been statically linked
into the httpd program.
The minimum configuration required to restrict access to resources in
a particular directory to users with a UcamWebAuth login is, e.g.:
AACookieKey "some random string"
<Directory "/path/to/protected/directory">
AuthType Ucam-WebAuth
Require valid-user
</Directory>
The AACookieKey directive is required. It provides data used to sign
and verify the session cookie, providing detection of any
tampering. See README.Config for further important information about
this. See the Apache documentation for other ways to use the 'Require'
directive to restrict access to identified individuals.
In this example the protected resources is selected with a <Directory>
directive; resources specified by <Location> or <Files> directives can
also be protected. 'AuthType' must be set to 'Ucam-WebAuth'. A
'Require' directive must also appear before authentication will take
place.
See README.Config for more information about configuring the module.