Manual Installation of Shibboleth Identity Provider

Below are step-by-step instructions on setting up an IdP on a Debian Linux system, and joining Level-1 of the MAMS Testbed Federation. It is aimed at system administrators who are familiar with the operations of setting up and configuring Apache 2 with SSL, Tomcat, and LDAP.

Prerequisites

• A Debian Linux system: while the instructions below are specific to the Debian system, it should be quite simple for most administrators to modify it slightly for use on other Linux distributions such as SUSE or RedHat^?.
• Make sure a browser exists in the system, if not, install Mozilla Firefox
• Java 1.5.x with JAVA_HOME environment set up to point to this location
• Web browser such as Mozilla Firefox
• Apache 2 with SSL
• Bind, search, authenticate as a user and retrieve their attributes from your institution's LDAP.
• Ntp tools to synchronize time with a remote time server (eg. ntpdate)
• wget (or something similar to download files from a webserver on a command line).
• Machine with a public IP address and a public DNS name associated with that IP. For the rest of this guide, we will use MY_DNS to represent the DNS name of the IdP machine that we are setting up.
• Firewall open for the following ports on the IdP machines:
  • TCP destination ports (ie. ports on the IdP machine) 80, 443, 8443.
  • UDP source port (ie. port on the remote host) 123.

Install Tomcat 5

• Download Tomcat 5
  • Tomcat 5.5.17: apache-tomcat-5.5.17.tar.gz
• Unpack the above package into /usr/local and setup the variable TOMCAT_HOME to point to the top level of tomcat.

  • $tar xzvf apache-tomcat-5.5.17.tar.gz

  • $mv apache-tomcat-5.5.17 /usr/local/.

  • ln -s /usr/local/apache-tomcat-5.5.17 /usr/local/tomcat

  • $export TOMCAT_HOME=/usr/local/tomcat

Install the IdP

• Download the latest IdP package, shibboleth-idp-1.3c.tar.gz
  • Shibboleth IdP: shibboleth-idp-1.3.3.tar.gz
• Untar it into a temporary working directory. We will refer to this directory as the environment SHIB_INSTALL.
• Shibboleth IdP requires that a specific version of the Xerces library be used. For that reason, we need to copy the following files, resolver.jar, xalan.jar, xercesImpl.jar and xml-apis.jar into the $TOMCAT_HOME/common/endorsed folder; replacing and removing the existing ones that came with the Tomcat 5 distribution if necessary:

  • $rm ${TOMCAT_HOME}/common/endorsed/*

  • $cp $SHIB_INSTALL/endorsed/*.jar ${TOMCAT_HOME}/common/endorsed

• Run the ant script inside the $SHIB_INSTALL folder. This will take you through a series of questions such as where is the Tomcat 5 location and where to install Shibboleth IdP. We assume that you specify that Shibboleth IDP is to be placed into “/usr/local/shibboleth-idp" and environment SHIB_HOME points to this directory:

  • $./ant

  • ....

  • $export SHIB_HOME=/usr/local/shibboleth-idp

Obtain SSL Certificate and the CA certificate

• To configure Apache 2 with SSL and also later for the IdP, you need to first obtain a certificate. For Level-1 of the Testbed Federation, we accept certificates signed by commercial certificate authorities and by our own MAMS Testbed Federation Level-1 Certificate Authority. If you already have a commercial certificate, you can skip this section. For Level 2 and Level 3 of the Testbed Federation we only accept certificates signed by commercial certicificate authorities.
• Generate a your key and certificate request using openssl:

  • mkdir /etc/certs && cd /etc/certs

  • openssl req -newkey rsa:1024 -nodes -keyout newkey.pem -out newreq.pem

  • mv newkey.pem mykey.pem

  • cat newreq.pem

  • Make sure that when you answer the question above when it comes to setting the Common Name, you enter the machine's Fully Qualified Domain Name such as "myhost.edu.au"
  • Make sure that your tomcat user (or whatever user that you use for IdP) has access to these certificate files
• On the IdP machine, open up a browser and go to this URL http://www.federation.org.au/CA/CA-sign.html
• Open the file newreq.pem with a text editor and copy the section between:

   -----BEGIN CERTIFICATE REQUEST-----

   ...... 

   -----END CERTIFICATE REQUEST----- 

• Make sure you also include the above lines when copying.
• Paste the information into the form on the browser and hit Submit. Copy the resultant certificate into a file and call it mycert.pem.
• Note that if you do not run the browser from the same machine as your IdP, you will not be able to obtain a certificate
• Download the level-1 CA certificate from this URL: http://www.federation.org.au/level-1-ca.crt into /etc/certs directory
• Check that at this point you have the three files:
  • Your IdP x509 certificate: mycert.pem
  • Your IdP key: mykey.pem
  • Level-1 CA x509 certificate: level-1-ca.crt

Configure Apache 2 with SSL

• Note: the instructions here are specific for Debian system. However if you want to use this for other Linux distributions, simply make sure that the Apache 2 directives below gets included by the httpd.conf file of your Apache 2 on your system.
• Create a file (if there is none already there) in /etc/apache2/mods-available directory called ssl.load with the line:

  • LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so

• Create the ssl configuration file, ssl.conf, in the same directory, /etc/apache2/mods-available, with the following content:

<IfModule mod_ssl.c>
   SSLRandomSeed startup builtin
   SSLRandomSeed connect builtin
   #SSLRandomSeed startup file:/dev/random  512
   #SSLRandomSeed startup file:/dev/urandom 512
   #SSLRandomSeed connect file:/dev/random  512
   #SSLRandomSeed connect file:/dev/urandom 512

   AddType application/x-x509-ca-cert .crt
   AddType application/x-pkcs7-crl    .crl

   SSLPassPhraseDialog  builtin

   SSLSessionCache         dbm:/var/run/apache2/ssl_scache
   SSLSessionCacheTimeout  300
   
   SSLMutex  file:/var/run/apache2/ssl_mutex
   SSLCipherSuite  ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

   SetEnvIf User-Agent ".*MSIE.*" \
               nokeepalive ssl-unclean-shutdown \
               downgrade-1.0 force-response-1.0
</IfModule>

• Enable ssl module by creating the following symbolic links:

  • $ln -s /etc/apache2/mods-available/ssl.load /etc/apache2/mods-enabled/.

  • $ln -s /etc/apache2/mods-available/ssl.conf /etc/apache2/mods-enabled/.

Create two SSL virtual hosts

• Due to a bug with Apache 2, it is necessary to run some IdP services on different ports/virtual hosts. The first vhost is used to handle the IdP's Single Sign On service (SSO) while the second is used to handle the IdP's Attribute Authority (AA).
• Edit the /etc/apache2/ports.conf file and make sure it has the following

  • Listen 443 

    Listen 8443

• Create the first SSL virtual host file, 003-ssl-vhost.conf, in the directory /etc/apache2/sites-available, with the following content, making sure to substitute MY_DNS with your actual fully qualified hostname:

<VirtualHost MY_IP:443>
    SSLEngine on
    ServerName MY_DNS:443
    UseCanonicalName on
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
    SSLOptions +StdEnvVars +ExportCertData
    SSLCertificateFile /etc/certs/mycert.pem
    SSLCertificateKeyFile /etc/certs/mykey.pem
    CustomLog /var/log/apache2/ssl_request_log\
         "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

    DocumentRoot /var/www/
    <Directory />
       Options FollowSymLinks
       AllowOverride None
    </Directory>
    <Directory /var/www/>
       Options Indexes FollowSymLinks MultiViews
       AllowOverride None
       Order allow,deny
       allow from all
       # This directive allows us to have apache2's default start page
       # in /apache2-default/, but still have / go to the right place
       RedirectMatch ^/$ /apache2-default/
    </Directory>

</VirtualHost>

• Create the second ssl vhost file, 004-ssl-vhost.conf, also in the same directory /etc/apache2/sites-available, with the following contents, making sure to substitute MY_DNS with your actual hostname:

<VirtualHost MY_IP:8443>
    SSLEngine on
    ServerName MY_DNS:8443
    UseCanonicalName  on
    SSLVerifyDepth  10
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP
    SSLVerifyClient optional_no_ca
    SSLOptions +StdEnvVars +ExportCertData
    SSLCertificateFile /etc/certs/mycert.pem
    SSLCertificateKeyFile /etc/certs/mykey.pem
    CustomLog /var/log/apache2/ssl_request_log_aa\
         "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

    DocumentRoot /var/www/
    <Directory />
       Options FollowSymLinks
       AllowOverride None
    </Directory>
    <Directory /var/www/>
       Options Indexes FollowSymLinks MultiViews
       AllowOverride None
       Order allow,deny
       allow from all
       # This directive allows us to have apache2's default start page
       # in /apache2-default/, but still have / go to the right place
       RedirectMatch ^/$ /apache2-default/
    </Directory>
</VirtualHost>

• Enable the virtual hosts by making the following symbolic links:

  • $ln -s /etc/apache2/sites-available/003-ssl-vhost.conf /etc/apache2/sites-enabled/.

  • $ln -s /etc/apache2/sites-available/004-ssl-vhost.conf /etc/apache2/sites-enabled/.

• Restart Apache 2.

  • $/etc/init.d/apache2 restart

• From a browser (preferably on a different machine), verify that you can get to the IdP machine via https protocol on port 443 and 8443, ie. use the followingg URL "https://MY_DNS" and "https://MY_DNS:8443"

Configuring Tomcat mod_jk Connector

• This section below uses Apache to protect IdP. Alternatively, you can use [Federation.ProtectIdPTomcatAuthentication][using Tomcat Authentication]] to protect IdP.
• Also, this section assume you're using mod_jk on apache. Newer apache/httpd can use mod_proxy.
• Install the mod_jk connector for Apache 2

  • $apt-get install libapache2-mod-jk

• Create a file called, jk.conf, in the directory /etc/apache2/mods-available, with the following content:

<IfModule !mod_jk.c>
  LoadModule jk_module mod_jk.so
</IfModule>

JkWorkersFile "/etc/apache2/workers.properties"
JkLogFile "/var/log/apache2/mod_jk.log"

JkLogLevel debug

• There should already be a jk.load file in /etc/apache2/mods-available.
• Make the symbolic links to enable the mod_jk module in Apache 2:

  • $ln -s /etc/apache2/mods-available/jk.load /etc/apache2/mods-enabled/.

  • $ln -s /etc/apache2/mods-available/jk.conf /etc/apache2/mods-enabled/.

• Create a new workers.properties file in /etc/apache2 directory with the following:

      workers.tomcat_home=/usr/local/tomcat
      workers.java_home=/usr/lib/jvm/java-1.5.0-sun-1.5.0.07
      ps=/
      worker.list=shibboleth

      # Definition for local worker using AJP 1.3
      #
      worker.shibboleth.type=ajp13
      worker.shibboleth.host=localhost
      worker.shibboleth.port=8009

• Add the following directives to the above vhost files (for both port 443 and 8443) just before the enclosing VirtualHost^? directive

  • JkMount /shibboleth-idp/* shibboleth

• Start up Tomcat 5:

  • $$TOMCAT_HOME/bin/startup.sh

• Go to $TOMCAT_HOME/conf and edit the server.xml file. Make sure that the following block is added or uncommented:

        <Connector port="8009" address="127.0.0.1" request.tomcatAuthentication="false"
            enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

• Make sure that any Coyote Connector defined for port 8009 is commented out
• Stop and restart Tomcat 5 and Apache 2 by executing the scripts:

  • $$TOMCAT_HOME/bin/shutdown.sh

  • $$TOMCAT_HOME/bin/startup.sh

  • $/etc/init.d/apache 2 restart

• Test that the Tomcat connector is working by pointing your browser to "https://MY_DNS/servlets-examples/index.html". You should see a page where you can try out all the example servlets that came with Tomcat 5.

Configuring Shibboleth IdP

• In the changes below, we assume that you installed Shibboleth IdP into /usr/local/shibboleth-idp, ie your SHIB_HOME. If not, you will need to make the changes to point to your correct location. You will also need to replace MY_DNS with the actual value of your IdP DNS name.
• Make a backup of your /usr/local/shibboleth-idp/etc/idp.xml to /usr/local/shibboleth-idp/etc/idp.xml.orig
• Search and edit /usr/local/shibboleth-idp/etc/idp.xml with the following changes. *Be very careful of blocks which are commented out and closing xml brackets*.

      <IdPConfig
         xmlns="urn:mace:shibboleth:idp:config:1.0"
         xmlns:cred="urn:mace:shibboleth:credentials:1.0"
         xmlns:name="urn:mace:shibboleth:namemapper:1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="urn:mace:shibboleth:idp:config:1.0 shibboleth-idpconfig-1.0.xsd"
         AAUrl="https://MY_DNS:8443/shibboleth-idp/AA"
         resolverConfig="file:/usr/local/shibboleth-idp/etc/resolver.ldap.xml"
         defaultRelyingParty="urn:mace:federation.org.au:testfed:level-1"
         providerId="urn:mace:federation.org.au:testfed:MY_DNS">


     
      <RelyingParty name="urn:mace:federation.org.au:testfed:level-1"
         signingCredential="testfed_level_1_cred">
         <NameID nameMapping="shm"/> 
      </RelyingParty>

      
      <Logging>
         <ErrorLog level="DEBUG"
            location="file:/usr/local/shibboleth-idp/logs/shib-error.log" />
         <TransactionLog level="DEBUG" 
            location="file:/usr/local/shibboleth-idp/logs/shib-access.log" />
      </Logging>

      <NameMapping
         xmlns="urn:mace:shibboleth:namemapper:1.0"
         id="shm"
         format="urn:mace:shibboleth:1.0:nameIdentifier"
         type="SharedMemoryShibHandle"
         handleTTL="1800"/>


      <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
         <FileResolver Id="testfed_level_1_cred">
            <Key>
               <Path>file:/etc/certs/mykey.pem</Path>
            </Key>
            <Certificate>
               <Path>file:/etc/certs/mycert.pem</Path>
             </Certificate>
         </FileResolver>
      </Credentials>


      <MetadataProvider
         type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadata"
         uri="file:/usr/local/shibboleth-idp/etc/level-1-metadata.xml"/>
   

• Ensure that cron service is enabled on your system.
• Install ntpdate time synchronization tool:

  • $apt-get install ntpdate

• Under the /etc/cron.hourly directory, create a new script, called ntpdate.sh, with the following content:

      #!/bin/sh
      /usr/sbin/ntpdate 128.250.37.2 129.127.28.4

• Note the above script uses the ntpdate command to update your system clock every hour so that your machine's clock is kept up to date.
• Make sure the script is executable, and then manually execute it for the first time.
• Manually download the federation metadata for the first time:

  • $wget https://www.federation.org.au/level-1/level-1-metadata.xml -O /usr/local/shibboleth-idp/etc/level-1-metadata.xml

Configuring the Shibboleth IdP LDAP resolver:

• Download the attached resolver.ldap.xml and replace the existing one in /usr/local/shibboleth-idp/etc/resolver.ldap.xml

• Edit the directory connector part down the bottom of the file to put in your correct LDAP host, binduser and password

Configuring the Attribute Release Policy:

• Download the attached arp.site.xml and replace the existing one in /usr/local/shibboleth-idp/etc/arps. This is a default site-wide Attribute Release Policy configuration file that prevents the release of any attribute. For examples of how to edit this file and release attribute see this guide ARP.

Configure Shibboleth IdP with Apache 2 LDAP Authentication:

• Install the Apache 2 mod_auth_ldap package:

*

$apt-get install libapache-mod-ldap libapache-auth-ldap
      

• Creating the file in /etc/apache2/mods-available directory called auth_ldap.load with the two lines below:

  • LoadModule ldap_module /usr/lib/apache2/modules/mod_ldap.so

  • LoadModule auth_ldap_module /usr/lib/apache2/modules/mod_auth_ldap.so

• Enable the Apache 2 auth_ldap module by creating the symbolic link:

  • $ln -s /etc/apache2/mods-available/auth_ldap.load /etc/apache2/mods-enabled/.

• We make the same assumptions about the LDAP as before, when configuring the LDAP resolver for Shibboleth IdP Attribute Authority. You need to change the details below to match your particular LDAP. For now we assume the following:
  • Bind DN: uid=binduser,ou=demo,dc=mams,dc=org,dc=au
  • Bind password: test
  • LDAP host: idp-ldap.mams.org.au
  • Base DN to search for users: ou=demo,dc=mams,dc=org,dc=au

• In the first SSL virtual host file, /etc/apache2/sites-available/003-ssl-vhost.conf, just before the enclosing , add the following:

     <Location /shibboleth-idp/SSO>
        AuthType Basic
        AuthName "Shibboleth IdP Authentication"
        AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
        AuthLDAPBindPassword "test"
        AuthLDAPURL "ldap://idp-ldap.mams.org.au:389/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)"
        require valid-user
     </Location>

• Restart Apache 2 and Tomcat 5.

  • $/usr/local/tomcat5/bin/shutdown.sh

  • $/usr/local/tomcat5/bin/startup.sh

  • $/etc/init.d/apache2 restart

Join the Level 1 Testbed Federation

• If you haven't register with the Testbed Federation, you will need to go to http://www.federation.org.au/FedManager/jsp/registerUser.jsp and register using your email address. A password will then be emailed to you.
• Log in to your Federation Management page, http://www.federation.org.au/FedManager/jsp/admin-main.jsp. You should change the password emailed to you by updating your details.
• Add a new Organization. It is important that your Organization Entity Id detail is of the form urn:mace:federation.org.au:testfed:MY DNS
• Under the new organization, add an IdP with the following details:
  • Certificate CN: the hostname of your IdP machine, ie. MY_DNS
  • SSO URL: https://MY_DNS/shibboleth-idp/SSO
  • Attribute Authority Service URL: https://MY_DNS:8443/shibboleth-idp/AA
  • Artifact Resolution Service URL: https://MY_DNS:8443/shibboleth-idp/Artifact
  • Federation Level: 1
• Configure your system to regularly download the latest Federation metadata by following this guide here
• Note it can be many hours before other SPs in the Testbed Federation retrieve the latest metadata that contains your IdP information.
• Open up a browser from any machine and point it to a test Service Provider, https://demo.federation.org.au/shibboleth/target
• At the WAYF, select your new IdP in the drop down list. Authenticate as a user in your system LDAP and you should successfully see a MAMS Test Service Provider Page.

---

to top