Installing a Shibboleth Target can be broken down into three stages. The installation results in getting a service provider to use Shibboleth in order to identify users and authorise use.
Installing Shibboleth software has been convered in more detail in other documentation produced by the IAMSECT project[2]. The following steps will allow you to complete an installation from source.
The SWITCH install documentation[3] offers a succinct set of instructions for installing the pre-requisite software. There is little there which is debian-specific. The following software can be installed from the vendor or the software author:
gcc, g++, make etc. – to build the source packages
apache(-dev) : i.e. webserver + apxs (either 1 or 2)
libssl(-dev)
libcurl
libxml-security-c
mod_ssl
The following software must be obtained from http://wayf.internet2.edu/shibboleth/
log4cpp – via shib because the project is in a ‘limbo state’
xerces-c – latest official xerces-c release has a bug which breaks shib. This version doesn’t
opensaml
shibboleth
The software must be installed in the following order: first gcc, g++, make etc., then apache + apache-dev (axps), followed by libssl + libssl-dev (headers), and finally libcurl.
Debian:
# aptitude install c++-compiler make apache apache-dev libssl-dev libcurl-dev libapache-mod-ssl
Redhat/fedora:
# up2date g++ gcc make httpd httpd-devel openssl openssl-devel curl curl-devel mod_ssl
Next, prepare the directory where the other software goes
# mkdir -p /opt/shibboleth-1.2.1
# cd /opt
# ln -s shibboleth-1.2.1 shibboleth
# cd shibboleth
log4cpp
# wget http://wayf.internet2.edu/shibboleth/log4cpp-0.3.5rc1.tar.gz
# tar xvzf log4cpp-0.3.5rc1.tar.gz # cd log4cpp-0.3.5rc1
# ./configure --prefix=/opt/shibboleth --with-pthreads --disable-static --disable-doxygen
# make && make install
xerces-c
# wget http://wayf.internet2.edu/shibboleth/xerces-c-src_2_6_1.tar.gz
# tar xvzf xerces-c-src_2_6_1.tar.gz
# cd xerces-c-src_2_6_1
# export XERCESCROOT=`pwd`
# cd src/xercesc
# ./runConfigure -p linux -r pthread -P /opt/shibboleth
# make && make install
# cd ../../..
The -c and -x args, defining the C and C++ compilers, can be dropped if they are the default ones on the system anyway (and should be on any of the targets to set up)
libxml-security-c
# wget \
http://xml.apache.org/dist/security/c-library/old/xml-security-c-1.1.0.tar.gz
# tar xvzf xml-security-c-1.1.0.tar.gz
# cd xml-security-c-1.1.0/src
# ./configure --prefix=/opt/shibboleth --without-xalan
# make && make install
# cd ../..
The above relies on the variable $XERCESCROOT defined in the previous section, just in case you do things in a different order
opensaml
# wget http://wayf.internet2.edu/shibboleth/archive/opensaml-1.0.1.tar.gz
# tar xvzf opensaml-1.0.1.tar.gz # cd opensaml-1.0.1
# ./configure --prefix=/opt/shibboleth \
--with-curl=/opt/shibboleth \
--with-log4cpp=/opt/shibboleth
# make && make install
# cd ..
shibboleth
# wget http://wayf.internet2.edu/shibboleth/archive/shibboleth-1.2.1a.tar.gz
# tar xvzf shibboleth-1.2.1a.tar.gz
# cd shibboleth-1.2.1
# ./configure --prefix=/opt/shibboleth \
--enable-apache-20 \
--with-apxs2 \
--with-log4cpp=/opt/shibboleth-1.2.1
# make && make install
for apache 1.x, use --enable-apache
--with-apxs rather than --enable-apache-20 --with-apxs2.
Visit the URL of your protected resource. You should be sent off to your origin and asked to log in. On successful login, you should be directed back towards the target, and see the desired page. If the desired page prints out environment variables as suggested, you should see some that correspond to attributes that the origin is releasing.
In order to test the target software, you need a site setup to protect. A simple ‘hello world’ page would suffice but isn’t very interesting. You could use the following to provide a shibboleth-protected server status page:
<Location /server-status>
SetHandler server-status
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>
Another good choice would be a CGI or PHP script (or similar) which will print out the environment variables. The following PHP script for example
<?php phpinfo(); ?>
Then, the attributes that are provided to the application will be visible on the page.
After following this configuration list, test install again, as in the section called “Test install”.
ADD TEXT: what are we configuring? what are our expectations for the target?
root# cd /opt/shibboleth-1.2.1/var/log
root# chown root:apache shibboleth
root# chmod 775 shibboleth
Where ‘apache’ is the username the httpd runs under. `apache’ on redhat; `www-data’ on debian; /opt/shibboleth-1.2.1 is the root under which the shibboleth-specific software was installed.
Type the following in .profile:
source ~/.bashrc
Stick the following in .bashrc:
export PATH=/opt/shibboleth/bin:$PATH
The system init scripts need adjusting, so that:
apache is able to load the Shibboleth libraries on startup
apache is started after the shibd component of Shibboleth
This is achieved by modifying the /etc/init.d/apachescript (plus indicates
added lines):
...
start() }
echo -n $"Starting $prog: "
check13 || exit 1
+ export LD_LIBRARY_PATH=/opt/shibboleth/lib
LANG=$HTTPD_LANG daemon $httpd $OPTIONS
RETVAL=$?
echo
...
An example init script for starting and stopping the shibboleth daemon component can be found in the Appendix. see the section called “Sample shibd init script”.
Include configuration items relevant to shibboleth
ln -s /opt/shibboleth/etc/shibboleth/apache2.config \ /etc/httpd/conf.d/shibboleth.conf
If you find apache won’t start up and you get `permission denied’ errors, check the section called “Error Messages and Solutions”.
There should be a /etc/httpd/conf.d/ssl.conf file. This
defines SSL settings including certificate and private
key. Visiting https://yourserver/ should bring up the
redhat test page, after you’ve clicked past some
certificate warnings.
You are going to want to change these keys for something else, either real keys provided by a top-level Certificate Authority, keys provided by a federation you are operating within (e.g. SDSS Test Federation) or a self-signed or internally-issued set.
Once you’ve obtained your replacement key and
certificate, change the ssl.conf file to reference them and restart
apache. Re-visit the https url and look at the cert in
the browser. If necessary, once you’ve confirmed it's the
right one, add it to your browser’s list of trusted
certificates permanently. This will reduce the number of
pop-up windows that occur during testing.
WAYF URL
As suggested by the shibboleth.xml file, the default
wayfURL is the In
Queue federation’s service. Change to
https://your-handle-server/shibboleth/HS for
internal testing against your own origin.
-->
<Sessions lifetime="7200" timeout="3600"
checkAddress="true"
- wayfURL="https://wayf.internet2.edu/InQueue/WAYF"
+ wayfURL="https://lock.ncl.ac.uk/shibboleth/HS"
shireURL="/Shibboleth.shire"
shireSSL="false"/>
<!--
choice of providerId
The main application element’s providerId attribute must be changed to a URI chosen by the deployer to uniquely identify the service.
i.e. in our example, providerId becomes providerId="https://webdev2.ncl.ac.uk/shibboleth/target"
The providerId must match the the Name
attribute in the Destinationsite tag in the
federation’s sites.xml
(or the sites.xml that
the origin you are using has)
target certificates
The target, by default, uses shibd.key and shibd.crt supplied in the shibboleth source. We need to get hold of a new keypair which is more secure and trusted by the origin. You may get one from a federation provider, or a CA which is trusted by your federation, or you could use Self Signed Certificates. From http://shibboleth.internet2.edu/guides/deploy-guide-target.html:
The only target component that must have a private key and certificate is the shibd.
it is mandatory for the shibd to authenticate when contacting an AA
certificate is signed by a CA accepted by the origin site
The shibd is assigned a key and a certificate using shibboleth.xml’s File Resolver element
To make the shibd use your new keypair:
<Credentials
xmlns="urn:mace:shibboleth:credentials:1.0">
<FileResolver Id="defcreds">
<Key format="PEM">
- <Path>/opt/shibboleth-1.2.1/etc/shibboleth/shibd.key</Path>
+ <Path>/opt/shibboleth/self-signed/ssl.key</Path>
</Key>
<Certificate format="PEM">
- <Path>/opt/shibboleth-1.2.1/etc/shibboleth/shibd.crt</Path>
+ <Path>/opt/shibboleth/self-signed/ssl.crt</Path>
</Certificate>
</FileResolver>
We have omitted how to make the IdP trust these keys. In most cases it is not necessary as you will end up using the Federation (in this case SDSS-provided) keys. In this case also the SDSS CA was already trusted by our origin.
“Federation Provider and Trust Provider elements must be added or changed as needed to reflect the arrangements required. This information is often provided by federations to their members”[4]
Getting the service (Blackboard, Zope) to accept information from shibboleth and use it in some way: i.e. identify the user by their attributes, etc., is the final step in the set up. The amount of work involved in getting a particular service to work with Shibboleth is completely dependent on the service. This article goes on to decribe (in sections 3 and 4) how this process works for two VLEs, Blackboard and Zope.