Rollout Workshop Configuration 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.
Both domains of "federation.mams.local" and "federation.org.au" are resolved to the same machine during the workshop, however, your Shibboleth setup should always refer to "federation.mams.local" whenever possible.
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 (on client test machine)
- 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.
Some software are already installed for the workshop machines to save time, however you will go through their configurations. They are:
- Tomcat 5.5, located at /usr/local/tomcat (referred as $TOMCAT_HOME)
- Shibboleth IdP Software, located at /usr/local/shibboleth-idp
- Shibboleth IdP Webapp, located at /usr/local/tomcat/webapps/shibboleth-idp
- Shibboleth IdP requires that a specific version of the Xerces library be used. For that reason, the following files resolver.jar, xalan.jar, xercesImpl.jar and xml-apis.jar are copied into $TOMCAT_HOME/common/endorsed folder
- Your vmware already has a valid SSL Certificate located at /etc/certs
- Apache 2 is already configured with SSL signed by Testbed CA (with Common Name: wsXX.mams.local)
- For Level 2 and Level 3 of the Testbed Federation we only accept certificates signed by commercial certificate authorities.
- 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). Refer to /etc/apache2/sites-enabled files
- mod_jk connector for Apache 2 has been installed on your system (this allows Apache to serve pages and forward to Tomcat)
- This guide assumes that we are protecting IdP using apache. You can protect IdP using tomcat authentication. We'll leave that for your exercise later.
View of Apache Config (003-ssl-vhost.conf)
<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>
View of Apache Config (004-ssl-vhost.conf)
<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>
Test Apache
Check if your vmware has proper configuration of Apache by visiting http and https URL: "http://MY_DNS", "https://MY_DNS" and "https://MY_DNS:8443". Replace MY_DNS with your vmware name (e.g. wsXX.mams.local)
Tomcat and mod_jk Connector Configuration
- Check /etc/apache2/workers.properties to see the list of workers handling redirection
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 tomcat
# Definition for local worker using AJP 1.3
#
worker.shibboleth.type=ajp13
worker.shibboleth.host=localhost
worker.shibboleth.port=8009
...
...
- Mounting Shibboleth IdP Webapp, check /etc/apache2/sites-enabled/003 and 004 (for both port 443 and 8443)
- change the ownership of the files so that tomcat gain full access on them
- Go to $TOMCAT_HOME/conf and check the server.xml file. It should have tomcatAuthentication is false:
<Connector port="8009" address="127.0.0.1"
request.tomcatAuthentication="false" tomcatAuthentication="false"
enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />
- 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.org.au (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:
- Apache mod_auth_ldap has been installed in your system and their appropriate symlinks have been created in /etc/apache2/mods-available and 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.
- In the first SSL virtual host file, /etc/apache2/sites-available/003-ssl-vhost.conf, just before the enclosing
</VirtualHost>, make sure the following exists:
<Location /shibboleth-idp/SSO>
AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative OFF
AuthName "Shibboleth IdP Authentication"
AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
AuthLDAPBindPassword "test"
AuthLDAPURL "ldap://localhost:389/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)"
require valid-user
</Location>
- 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.federation.mams.local/shibboleth/target
- 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