Installing the Apache authentication module under MacOS X: Difference between revisions

From RavenWiki
Jump to navigationJump to search
mNo edit summary
m (Reverted edits by jmw11 (talk) to last revision by jw35)
Tag: Rollback
 
(62 intermediate revisions by 4 users not shown)
Line 1: Line 1:
'''IMPORTANT 1''': see section [[#Mac OS X Server | 'Mac OS X Server']] (below) if installing on Mac OS X Tiger Server version 10.4.6 or later 10.4.x version.
'''WARNING:''' Apple removed the OpenSSL library from MacOS 10.11 (El Capitan) onward. Since the Apache authentication module depends on OpenSSL for some of its function this means that the '''module can't easily be used with the supplied copy of Apache from 10.11 onward'''.


'''IMPORTANT 2''': If upgrading to Leopard/SnowLeopard also note that Leopard installs Apache 2.2.6 whilst Tiger comes with Apache 1.something so your Apache configuration and custom modules will need modification/recompiling.
Options for anyone needing or currently using Raven authentication with Apache on MacOS include:
* Moving to Apache on a Linux platform
* Using Raven's Shibboleth service -- UIS have no experience of using this but the Shibboleth Consortium [https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMacInstall appear to support running the Shibboleth SP under MacOS], and both [https://www.macports.org/ Macports] and [https://brew.sh/ Homebrew] include shibboleth-sp packages that may be usable with the MacOS version of Apache
* Install a separate copy of Apache and its dependencies either by hand or using [https://www.macports.org/ Macports] or [https://brew.sh/ Homebrew], and build a copy of the Apache Ucam WebAuth module against that using [http://raven.cam.ac.uk/project/apache/INSTALL the generic build instructions]


----
All of these options will be fiddly, and none will be GUI-based. Sorry.


1. Log in as administrator (aka admin) and install the Xcode tools if you haven't already got them installed on your system. This will give you all the stuff you need for writing code on your Mac.
==Ucam WebAuth==


You can pick the Xcode tools up from http://developer.apple.com/tools/download/ or install it from your distribution CD.
Ucam WebAuth v2.0 supports v3 of the protocol. This allows distinction between current users and all users. For more information please see this page https://wiki.cam.ac.uk/raven/Current_and_non-Current_users. It is recommended that mod_ucam_webauth v2.x is used for all new installs.  


To install Xcode tools from the CD/DVD:
==Installing & configuring Raven for 10.6 and later==
* Insert the CD labelled "Mac OS X Xcode Tools" or the install DVD for Leopard and double-click on the XcodeTools.mpkg icon.  For Leopard you need to double-click on "Optional Installs", then "Xcode Tools" to get to the XcodeTools.mpkg icon.
* Enter your administrator password.
* Follow the instructions in the installer.


To install the Xcode tools from the the package (i.e.. XcodeTools1.5_CD.dmg) that you downloaded from the developer.apple.com site:
For those users running 10.6 and later there is a prebuilt installer package to deploy the Raven module without the need for compilation. Users of previous versions of OS X should look at [[Legacy Raven info for 10.4 etc]]
* Double-click on the XcodeTools1.5_CD.dmg.
* Enter your administrator password.
* Follow the instructions in the installer.


2. Download a copy of mod_ucam_webauth from https://raven.cam.ac.uk/project/apache/files/ (and if necessary double click on mod_ucam_webauth-1.4.2.tar). (By default this will be downloaded into a folder called mod_ucam_webauth-1.4.2 on your desktop or if using Leopard all downloaded items will go into your Downloads folder.)
===Installing mod_ucam_webauth===
* Start the Terminal application.
* Type the command "cd Desktop/mod_ucam_webauth-1.4.2" (or "cd Downloads/mod_ucam_webauth-1.4.2" on Leopard/SnowLeopard).
* To build ucam_webauth on Tiger and SnowLeopard type the command "make".


You should see something along the following lines:
Choose the correct the installer package for your version of OS X. The module will be installed into /usr/libexec/apache/
 
*[http://raven.cam.ac.uk/project/apache/files/MacOS/mod_ucam_webauth_2.0.2_10.6-10.9.dmg 10.6 (Snow Leopard) to 10.9 (Mavericks)]
admin$ make
*[http://raven.cam.ac.uk/project/apache/files/MacOS/mod_ucam_webauth_2.0.2_10.10.dmg 10.10 (Yosemite)]
/usr/sbin/apxs -c -lcrypto \
Download the necessary RSA public keys from https://raven.cam.ac.uk/project/keys/ and place them in into /etc/apache2/webauth_keys/. The easiest way to do this is to simply execute the following commands in Terminal:
mod_ucam_webauth.c
  <tt>sudo mkdir /etc/apache2/webauth_keys
gcc -DDARWIN -DUSE_HSREGEX -DUSE_EXPAT -I../lib/expat-lite -g -Os -pipe -DHARD_SERVER_LIMIT=2048
-DEAPI -DSHARED_MODULE -I/usr/include/httpd -c mod_ucam_webauth.c
cc -bundle -undefined suppress -flat_namespace -Wl,-bind_at_load -o mod_ucam_webauth.so
mod_ucam_webauth.o -lcrypo
 
* On Leopard you unfortunately cannot use APXS as it does not appear to understand about fat modules and just running "make" will result in a non-functional mod_ucam_webauth module.  Thusly you need to type (best to cut and paste!) the following horror into your Terminal:
 
/usr/share/apr-1/build-1/libtool --silent --mode=compile gcc    -DDARWIN -DSIGPROCMASK_SETS_THREAD_MASK -no-cpp-precomp  -I/usr/include/apache2  -I/usr/include/apr-1  -I/usr/include/apr-1 -arch ppc -arch ppc64 -arch i386 -arch x86_64  -c -o mod_ucam_webauth.lo mod_ucam_webauth.c
 
/usr/share/apr-1/build-1/libtool --silent --mode=link gcc -o mod_ucam_webauth.la  -lcrypto -rpath /usr/libexec/apache2 -module -avoid-version -arch ppc -arch ppc64 -arch i386 -arch x86_64 mod_ucam_webauth.lo
 
If the above two commands result in errors for you, what you need to do is to run "make clean" then run "make SUFFIX=la". This should work without errors and produce some output that will contain two lines similar to the above two commands. What you need to do is to then run "make clean" again and then copy and paste the first command then the second command as was displayed when you ran "make SUFFIX=la" BUT you have to add the options "-arch ppc -arch ppc64 -arch i386 -arch x86_64" to each of the commands to cause the module to be built 4-way-fat as is needed for Leopard's Apache installation.
 
* Then copy the module into the /usr/libexec/httpd/ directory by typing "sudo make install" on Tiger or "sudo make SUFFIX=la install" on Leopard and SnowLeopard.
 
You should see something along the following lines:
 
sudo make install
Password:
/usr/sbin/apxs -c -lcrypto \
mod_ucam_webauth.c
gcc -DDARWIN -DUSE_HSREGEX -DUSE_EXPAT -I../lib/expat-lite -g -Os -pipe -DHARD_SERVER_LIMIT=2048
-DEAPI -DSHARED_MODULE -I/usr/include/httpd -c mod_ucam_webauth.c
cc -bundle -undefined suppress -flat_namespace -Wl,-bind_at_load -o mod_ucam_webauth.so
mod_ucam_webauth.o -lcrypto
/usr/sbin/apxs -i mod_ucam_webauth.so
cp mod_ucam_webauth.so /usr/libexec/httpd/mod_ucam_webauth.so
chmod 755 /usr/libexec/httpd/mod_ucam_webauth.so
 
3. Download the necessary RSA public keys from https://raven.cam.ac.uk/project/keys/ and place them in /usr/conf/webauth_keys/ on Tiger or /etc/apache2/webauth_keys/ on Leopard. For Leopard the easiest way to do this is to simply execute the following commands on the Terminal:
 
  sudo mkdir /etc/apache2/webauth_keys
  cd /etc/apache2/webauth_keys
  cd /etc/apache2/webauth_keys
  sudo curl -O https://raven.cam.ac.uk/project/keys/pubkey2
  sudo curl -O https://raven.cam.ac.uk/project/keys/pubkey2</tt>


The Apache module only needs the "PEM formated PKCS#1 RSA public key" which is stored in a file named pubkey''<n>'' (currently pubkey2). The names of the key files should not be changed - beware that they have no filename suffix but that some browsers may add .txt or similar when downloading them.
===Editing Apache Configuration===


4. For Tiger, add the following to /etc/httpd/httpd.conf, after the line that reads "ClearModuleList":
It is recommended that you do not edit the primary httpd.conf file but configure apache through VirtualHost files. They are found in the following locations:


LoadModule ucam_webauth_module libexec/httpd/mod_ucam_webauth.so
<tt>/etc/apache2/sites/</tt> - all client version of OS X and 10.7 Server
AddModule mod_ucam_webauth.c


AACookieKey "some random string"
<tt>/Library/Server/Web/Config/apache2/sites/</tt> - 10.8 Server and later
<Directory "path to protected directory">
  AuthType Ucam-WebAuth
  Require valid-user
</Directory>


For Leopard and SnowLeopard, add the following to /etc/apache2/httpd.conf, after the last line beginning with "LoadModule":
It is highly recommended that you do not use Server Admin or Server to manage the web service post Raven configuration. These tools have a nasty habit of destroying configuration the GUI tools do not understand.


LoadModule ucam_webauth_module libexec/apache2/mod_ucam_webauth.so
For a basic configuration add the following to the apache config file:


<tt>LoadModule ucam_webauth_module libexec/apache2/mod_ucam_webauth.so
  AAKeyDir "/etc/apache2/webauth_keys"
  AAKeyDir "/etc/apache2/webauth_keys"
  AACookieKey "some random string"
  AACookieKey "some random string"
  <Directory "path to protected directory">
  <Directory "/path/to/protected/web/directory">
   AuthType Ucam-WebAuth
   AuthType Ucam-WebAuth
   Require valid-user
   Require valid-user
  </Directory>
  </Directory></tt>


This is the minimum configuration required to restrict access to resources in a particular directory to users with a Ucam-WebAuth login. See https://raven.cam.ac.uk/project/apache/README.Config for further customisation options.
====10.5, 10.6 & 10.7 specific edits====


==Mac OS X Tiger Server==
Add the following to the VirtualHosts file:


Note the below applies to Mac OS X Tiger Server.  Mac OS X Leopard and SnowLeopard work fine without doing the below and in fact doing the below will break Raven.
<tt>LoadModule authz_user_module libexec/apache2/mod_authz_user.so</tt>


By default Apache on Mac OS X Server uses Apple's own authentication module, mod_auth_apple, in place of the standard Apache module, mod_auth. In Mac OS X Server version 10.4.6 (and probably in future versions of Mac OS X Server 10.4)  mod_auth_apple won't inter-work with mod_ucam_webauth.
====10.8 or later specific edits====


To work around this, disable use of mod_auth_Apple and re-enable mod_auth (which Apple continue to supply). To do so, edit /etc/httpd/httdp.conf and replace
Add the following to the VirtualHosts file:


  LoadModule apple_auth_module    libexec/httpd/mod_auth_apple.so
<tt>LoadModule authz_user_module libexec/apache2/mod_authz_user.so


with
LoadModule authz_groupfile_module libexec/apache2/mod_authz_groupfile.so</tt>


  LoadModule auth_module            libexec/httpd/mod_auth.so
====Testing====


and
Start/restart the web server and test. Check /var/log/apache2/error.log if you are having problems.


  AddModule mod_auth_apple.c
This is the minimum configuration required to restrict access to resources in a particular directory to users with a Ucam-WebAuth login. See https://raven.cam.ac.uk/project/apache/README.Config for further customisation options.
 
with
 
  AddModule mod_auth.c
 
It may also be possible to make this change using the Apache management GUI - see Apple documentation for details.  


===Notes for Leopard and SnowLeopard Server===
====Building from Source====


(Tested with 10.5.6 and 10.6)
Should you wish to build the module from source then do the following:
#Download and install Xcode AND the command line tools (<tt>sudo xcode-select --install</tt> is easiest) or install gcc & support files from another source
#Download mod_ucam_webauth from https://raven.cam.ac.uk/project/apache/files/MacOS/ and expand the tar archive
#cd into mod_ucam_webauth and type <tt>sudo apxs -c -i -lcrypto mod_ucam_webauth.c</tt>. This will build and install the Raven authentication module for the currently booted OS X system architecture.
#Install the RSA keys and edit apache as described above.


When using 10.5 and 10.6 server ''do not'' disable the mod_auth_apple module as above. auth_module does not exist in 10.5 and 10.6 server and Raven will fail without mod_auth_apple enabled with a 'No groups file error' in the apache error log.
If Xcode 4 or later users get the error "<tt>env: /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain/usr/bin/cc: No such file or directory</tt>" then paste in the following command as one line:


===Background to the problem===
<tt>sudo ln -s /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain</tt>


The standard Apache mod_auth supports authentication using user names and
Replace OSX10.8.xctoolchain with OSX10.9.xctoolchain etc as appropriate.
passwords stored in files maintained by the htpassword utility. Apple's
mod_auth_apple appears to extend this to allow users to authenticate either
via credentials stored in htpassword files or via the system's login user
name/password database.


While mod_ucam_webauth replaces the password validation functions of
Apple forgot to include a symlink causing apxs to fail to find the compiler.
mod_auth and mod_auth_apple, it still relies on other functions that they
provide. Even though mod_auth_apple largely replicates mod_auth's
functionality it unfortunately does so in a way that is incompatible with
mod_ucam_webauth's needs.


As far as we know the only thing you loose by replacing mod_auth_apple with
[[Legacy Raven info for 10.4 etc]]
mod_auth is the integration with the system's login user name/password
database. Obviously that's a problem if you need it, or if you are running
any web applications that rely on it. Otherwise this loss probably doesn't matter.

Latest revision as of 13:57, 13 December 2019

WARNING: Apple removed the OpenSSL library from MacOS 10.11 (El Capitan) onward. Since the Apache authentication module depends on OpenSSL for some of its function this means that the module can't easily be used with the supplied copy of Apache from 10.11 onward.

Options for anyone needing or currently using Raven authentication with Apache on MacOS include:

All of these options will be fiddly, and none will be GUI-based. Sorry.

Ucam WebAuth

Ucam WebAuth v2.0 supports v3 of the protocol. This allows distinction between current users and all users. For more information please see this page https://wiki.cam.ac.uk/raven/Current_and_non-Current_users. It is recommended that mod_ucam_webauth v2.x is used for all new installs.

Installing & configuring Raven for 10.6 and later

For those users running 10.6 and later there is a prebuilt installer package to deploy the Raven module without the need for compilation. Users of previous versions of OS X should look at Legacy Raven info for 10.4 etc

Installing mod_ucam_webauth

Choose the correct the installer package for your version of OS X. The module will be installed into /usr/libexec/apache/

Download the necessary RSA public keys from https://raven.cam.ac.uk/project/keys/ and place them in into /etc/apache2/webauth_keys/. The easiest way to do this is to simply execute the following commands in Terminal: 

sudo mkdir /etc/apache2/webauth_keys
cd /etc/apache2/webauth_keys
sudo curl -O https://raven.cam.ac.uk/project/keys/pubkey2

Editing Apache Configuration

It is recommended that you do not edit the primary httpd.conf file but configure apache through VirtualHost files. They are found in the following locations:

/etc/apache2/sites/ - all client version of OS X and 10.7 Server

/Library/Server/Web/Config/apache2/sites/ - 10.8 Server and later

It is highly recommended that you do not use Server Admin or Server to manage the web service post Raven configuration. These tools have a nasty habit of destroying configuration the GUI tools do not understand.

For a basic configuration add the following to the apache config file: 

LoadModule ucam_webauth_module libexec/apache2/mod_ucam_webauth.so
AAKeyDir "/etc/apache2/webauth_keys"
AACookieKey "some random string"
<Directory "/path/to/protected/web/directory">
  AuthType Ucam-WebAuth
  Require valid-user
</Directory>

10.5, 10.6 & 10.7 specific edits

Add the following to the VirtualHosts file:

LoadModule authz_user_module libexec/apache2/mod_authz_user.so

10.8 or later specific edits

Add the following to the VirtualHosts file:

LoadModule authz_user_module libexec/apache2/mod_authz_user.so

LoadModule authz_groupfile_module libexec/apache2/mod_authz_groupfile.so

Testing

Start/restart the web server and test. Check /var/log/apache2/error.log if you are having problems.

This is the minimum configuration required to restrict access to resources in a particular directory to users with a Ucam-WebAuth login. See https://raven.cam.ac.uk/project/apache/README.Config for further customisation options.

Building from Source

Should you wish to build the module from source then do the following:

  1. Download and install Xcode AND the command line tools (sudo xcode-select --install is easiest) or install gcc & support files from another source
  2. Download mod_ucam_webauth from https://raven.cam.ac.uk/project/apache/files/MacOS/ and expand the tar archive
  3. cd into mod_ucam_webauth and type sudo apxs -c -i -lcrypto mod_ucam_webauth.c. This will build and install the Raven authentication module for the currently booted OS X system architecture.
  4. Install the RSA keys and edit apache as described above.

If Xcode 4 or later users get the error "env: /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain/usr/bin/cc: No such file or directory" then paste in the following command as one line:

sudo ln -s /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain /Applications/Xcode.app/Contents/Developer/Toolchains/OSX10.8.xctoolchain

Replace OSX10.8.xctoolchain with OSX10.9.xctoolchain etc as appropriate.

Apple forgot to include a symlink causing apxs to fail to find the compiler.

Legacy Raven info for 10.4 etc

Retrieved from "https://wiki.cam.ac.uk/wiki/raven/index.php?title=Installing_the_Apache_authentication_module_under_MacOS_X&oldid=2894"