Workshop 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.
This guide is specifically tailored for MAMS vmware used during the workshop. Some steps have been deleted or modified accordingly. For full instruction, refer to
ManualInstallIdP
All references to federation.mams.local are reflection to the federation.org.au domain. Federation.mams.local is specifically used throughout the workshop machines.
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.
- 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
- Tomcat is already installed on your system
- setup TOMCAT_HOME variable to point to it
Install the IdP
- The latest shibboleth idp package is available on your /usr/src/ folder. We're making a symlink from /usr/src to /root/software for convenience
- Untar it. 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:
- 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. Press enter (default) for all options asked during installation. 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:
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 certificate authorities.
- Generate a your key and certificate request using openssl:
-
cd /etc/certs
-
mv mycert.pem mycert.pem.old
-
mv mykey.pem mykey.pem.old
-
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 "wsXX.mams.local" where XX is your group number.
-
Common Name: wsXX.mams.local
- open up a browser and go to http://federation.mams.local/mams-ca/CA-mams-sign.html.
Login as username: workshop and passwd: w0rksh0p (this URL only valid for workshop, follow the public facing URL if you're doing installation at your institution)
- 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 BEGIN and END CERTIFICATE 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
- Download the level-1 CA certificate from http://federation.mams.local/level-1-ca.crt into /etc/certs directory
- Check that at this point you have at least these 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 & SSL virtual hosts
- 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.
- Apache 2.2 has been installed on your system, you need to make sure it is fully configured to use your new certificate as we will go through soon
- 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).
- Clean up the symlinks:
rm /etc/apache2/sites-enabled/003* /etc/apache2/sites-enabled/004*
ln -s /etc/apache2/sites-available/00* /etc/apache2/sites-enabled
- Edit the /etc/apache2/ports.conf file and make sure it has the following
- discover your machine IP address
- Edit 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 hostname and MY_IP with your vmware actual IP address:
<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
SSLCACertificateFile /etc/certs/ca-bundle.pem
CustomLog /var/log/apache2/ssl_request_log\
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
...
...
</VirtualHost>
- Edit 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 and MY_IP with your vmware actual IP address:
<VirtualHost MY_IP:8443>
SSLEngine on
ServerName MY_DNS:8443
UseCanonicalName On
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
SSLCACertificateFile /etc/certs/ca-bundle.pem
CustomLog /var/log/apache2/ssl_request_log_aa\
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
...
...
</VirtualHost>
- Restart Apache 2.
- From a browser 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
- mod_jk connector for Apache 2 has been installed on your system
- We need to expose IdP webapp to Apache so that we can conveniently instruct users to do the login (e.g. web browser will display https://xxxx rather than putting explicit port number such as https://xxx:8443 for instance). For this purpose, we need to configure mod_jk connector
- This guide assumes that we are protecting IdP using tomcat but exposes the IdP to apache so that Apache can serve the initial requests.
- Edit workers.properties file in /etc/apache2 directory make sure it has the following info:
workers.tomcat_home=/usr/local/tomcat
workers.java_home=/usr/lib/jvm/java-1.5.0-sun-1.5.0.07
ps=/
worker.list=apacheAuth tomcatAuth
# Definition for local worker using AJP 1.3
#
worker.apacheAuth.type=ajp13
worker.apacheAuth.host=localhost
worker.apacheAuth.port=8009
...
...
- Add the following directives to the above vhost files (for both port 443 and 8443) just before close tag of the enclosing VirtualHost? directive (i.e. still within VirtualHost? directive)
- change the ownership of the files so that tomcat gain full access on them
- Stop and restart Tomcat 5 and Apache 2 by executing the scripts:
-
/etc/init.d/tomcat5.5 stop
-
ps aux | grep tomcat
-
/etc/init.d/tomcat5.5 start
-
/etc/init.d/apache2 restart
- Test that the Tomcat connector is working by pointing your browser to
"https://MY_DNS/shibboleth-idp/login.jsp". You should see a page
where a standard login page is displayed. This only checks that mod_jk is doing its forwarding to tomcat.
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.mams.local:testfed"
providerId="urn:mace:federation.mams.local:testfed:MY_DNS">
<RelyingParty name="urn:mace:federation.mams.local:testfed"
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>
<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"/>
- Things to check on idp.xml:
- AAUrl using your correct hostname
- resolverConfig is using resolver.ldap.xml
- defaultRelyingParty is in the form of urn:mace:....
- providerId is urn:mace:...:wsXX.mams.local (i.e. your DNS)
- RelyingParty urn:mace:...:testfed
- signing credential name is correct using level-1
- both logging are set to DEBUG
- FileResolver id is the same as your signing credential name (your certificate)
- Your vmware already has cron job to ensure its time is always synch (vmware prone to out-of-synch timing), you may do things
differently at your home institution
- Manually download the federation metadata for the first time:
Configuring the Shibboleth IdP LDAP resolver:
- Download this 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 (i.e. localhost), binduser and password
For now we assume the following:
- Bind DN: uid=binduser,ou=demo,dc=mams,dc=org,dc=au
- Bind password: test
- LDAP host: localhost
- Base DN to search for users: ou=demo,dc=mams,dc=org,dc=au
<JNDIDirectoryDataConnector id="directory">
<Search filter="uid=%PRINCIPAL%">
<Controls searchScope="SUBTREE_SCOPE" returningObjects="false"/>
</Search>
<Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
<Property name="java.naming.provider.url" value="ldap://localhost:389/ou=demo,dc=mams,dc=org,dc=au"/>
<Property name="java.naming.security.principal" value="uid=binduser,ou=demo,dc=mams,dc=org,dc=au"/>
<Property name="java.naming.security.credentials" value="test"/>
</JNDIDirectoryDataConnector>
- Check the "provider.url" pointng to "localhost", principal is the binduser, credentials is the test
Configuring the Attribute Release Policy:
- Download this 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 or Tomcat Authentication:
- You are protecting the IdP using tomcat authentication on this guide. However, you can protect the IdP using apache authentication. We'll leave that for your exercise later.
- Follow the Guide for Tomcat Authentication.
- Restart Apache 2 and Tomcat 5.
-
/etc/init.d/tomcat5.5 stop
-
/etc/init.d/tomcat5.5 start
-
/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://federation.mams.local/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://federation.mams.local/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.mams.local:testfed:MY DNS
- Under the new organization, add an IdP with the following details:
- 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.mams.local/level-1/demo.jsp
- At the WAYF, select your new IdP in the drop down list.
Authenticate as a user in your system LDAP (try username staff with passwd test ) and you should successfully
see a MAMS Test Service Provider Page.
- If you have the error saying "Error 404: Servlet IdP is not available" then do these checks:
- visit https://MY_DNS/shibboleth-idp/AA --> you should see "standard" shibboleth error with shibboleth logo complaining about not passing parameters. if you don't see this, then see the solution below.
- visit https://MY_DNS/shibboleth-idp/login.jsp --> you should see a typical tomcat-auth login jsp page. if you don't see this, then your mod-jk/mod-proxy is not configured properly, go back and reconfigure.
- visit https://MY_DNS/shibboleth-idp/SSO --> you should be asked to login with popup dialog (apache-auth). if you don't see this, then your apache config on port 443 (003-ssl-conf) is not configured properly, redo its configuration section above.
- if you don't see the above expected behaviours particularly the https://MY_DNS/shibboleth-idp/AA step, then you need to:
- chown -R tomcat55:adm $TOMCAT_HOME/webapps
- chown -R tomcat55:adm $SHIB_HOME
- /etc/init.d/tomcat5.5 stop
- /etc/init.d/tomcat5.5 start
- if this still fail, try to check your idp.xml to see if you have misconfigured (or missed) something. Look at a guide for doing "resolvertest" on FAQ (link on left side)
to top