These instructions are for IdPs versions 2.0/2.1/2.2/2.3 in the SWITCHaai federation that have been installed using the deployment guides on our website.
Please also take the time to upgrade the OS, Java and Apache Tomcat. The Shibboleth IdP 2.4 runs well on Tomcat 6.
We assume that this is the version you use and that you have installed it from the debian package tomcat6.
Earlier guides unpacked the Shibboleth IdP sources to /opt. This guide assumes that all Shibboleth IdP sources are unpacked to /usr/local/src.
To clean up, move the previous version of the IdP into /usr/local/src instead of keeping it in /opt.
mv /opt/shibboleth-identityprovider-* /usr/local/src
If you have upgraded your Debian operating system to the current stable version Debian 7.0 "wheezy",
we recommend that you install the Java package default-jre-headless
. This will install
OpenJDK. Java will be available in /usr/lib/jvm/default-java.
apt-get install default-jre-headless
Krb5LoginModule
in login.config
), please note
that Kerberos will return a principal name of the format userid@CAMPUS.EDU
(i.e. includes the realm). Make sure
that the attribute resolver is configured accordingly. (Older versions of the IdP and/or Kerberos module might
have returned the username that the user entered into the login form.) See the section "Kerberos Login Module Specification"
at https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPass
for details.cd /opt/shibboleth-idp tar -cvzf ../shibboleth-idp_config.tar.gz ./conf ./metadata ./credentials chmod 600 ../shibboleth-idp_config.tar.gz
Download the latest Shibboleth Identity Provider.
The following steps assume that the latest Shibboleth Identity Provider
has been downloaded and extracted in the directory /usr/local/src/shibboleth-identityprovider-2.4.4
:
cd /usr/local/src
curl -O https://shibboleth.net/downloads/identity-provider/2.4.4/shibboleth-identityprovider-2.4.4-bin.zip
cd /usr/local/src unzip shibboleth-identityprovider-2.4.4-bin.zip cd shibboleth-identityprovider-2.4.4 chmod u+x install.sh
WEB-INF/web.xml
) in the IdP source directory. Copy the files from the old source directory
to the new one. The IdP version currently running on your system may be different from the example (2.3.8) below.
The customized pages are located in src/main/webapp/
.
cd /usr/local/src/shibboleth-identityprovider-2.3.8 cp -pr src/main/webapp/* \ /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/
src/main/webapp/WEB-INF/web.xml
:cd /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/WEB-INF
web.xml
and check whether the servlet for displaying IdP status is configured:
...
<!-- Servlet for displaying IdP status. -->
<servlet>
<servlet-name>Status</servlet-name>
<servlet-class>edu.internet2.middleware.shibboleth.idp.StatusServlet</servlet-class>
<!-- Space separated list of CIDR blocks allowed to access the status page -->
<init-param>
<param-name>AllowedIPs</param-name>
<param-value>127.0.0.1/32 ::1/128 130.59.0.0/16 2001:620::/48 #your IP range#</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
...
Update the file src/main/webapp/WEB-INF/idpui.tld
by downloading it from our website.
cd /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/WEB-INF
curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/idpui.tld
Note: Usually, no manual changes have been made to this file. So it's safe to just replace the existing file.
mysql-connector-java-version-bin.jar
) to/usr/local/src/shibboleth-identityprovider-2.4.4/lib/
.cd /usr/local/src/shibboleth-identityprovider-2.3.8 cp lib/mysql-connector-java-5.1.x-bin.jar \ /usr/local/src/shibboleth-identityprovider-2.4.4/lib/
lib
directory:
cp /opt/cas-client-X.Y.Z/cas-client-core/target/cas-client-core-X.Y.Z.jar \ /usr/local/src/shibboleth-identityprovider-2.4.4/lib/
endorsed
subdirectory (must no longer be used with IdP 2.4.4 or later, for security reasons):
rm -r /usr/share/tomcat6/endorsed
The file relying-party.xml
has changed at various places since previous versions of the IdP.
We highly recommend to download the SWITCHaai specific relying-party.xml file as a template from our website
and apply the required adaptations as described in our deployment guide.
WARNING: The following instructions install a new version of the file relying-party.xml
and replace the old file. In case you have made specific manual changes to the existing file,
please carefully compare the old and the new file. If you have enabled interfederation support
in the old file, you can still use the new file and just re-enable interfederation support
by removing the comments around the corresponding MetadataProvider
and TrustEngine
elements. If in doubt, try to keep the existing file or ask the SWITCHaai Team for support.
relying-party.xml
:
cd /opt/shibboleth-idp/conf/ cp relying-party.xml relying-party.xml.old curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/relying-party.xml
Update all of the following configuration files by downloading them from our website:
handler.xml
internal.xml
service.xml
WARNING: The following instructions install new versions of the these files and replace the old files. In case you have made specific manual changes to the existing files, please carefully compare the old and the new files. If in doubt, try to keep the existing files or ask the SWITCHaai Team for support.
cd /opt/shibboleth-idp/conf/ cp handler.xml handler.xml.old cp internal.xml internal.xml.old cp service.xml service.xml.old curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/handler.xml curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/internal.xml curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/service.xml
Note: In the file service.xml
, you need to adapt the URL to downlad the
attribute-filter.xml
file. This is described in the next step.
service.xml
, update the URL to download the
attribute-filter.xml
file. The correct download URL has to be obtained from
the SWITCH Resource Registry.
(Login to the Resource Registry,
go to "Home Organizations", and locate your Home Organisation. The link to the download
location of attribute-filter.xml
is labelled as "Attribute Filter".)service.xml
, look for the element
<srv:Service id="shibboleth.AttributeFilterEngine" ...>
and change the value of the url
attribute to the URL found in the
Resource Registry.
<srv:Service id="shibboleth.AttributeFilterEngine"
xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine"
configurationResourcePollingFrequency="PT1H"
configurationResourcePollingRetryAttempts="128">
<srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
url="https://rr.aai.switch.ch/switchaai/example.org/attribute-filter.xml"
file="/opt/shibboleth-idp/conf/attribute-filter.xml"/>
</srv:Service>
This step also enables your Identity Provider to add the value member
to the attribute eduPersonAffiliation
for users who have one of the
values student
, staff
or faculty
set.
The value member
is required by some international Federation Partners.
At least, you should make sure that
member
is supported by the attribute eduPersonAffiliation
,eduPersonScopedAffiliation
.Without this, your users might not be able to access the services of some publishers.
Follow the guide International Attribute Support for SWITCHaai Identity Providers to add these attributes.
Note: You won't need to restart your Identity Provider at this step as described in the guide above, since this will be done later in this guide.
cd /usr/local/src/shibboleth-identityprovider-2.3.8 cp lib/jstl-1.2.jar \ lib/spring-jdbc-2.5.6.SEC03.jar \ lib/spring-tx-2.5.6.SEC03.jar \ lib/uApprove-2.5.0.jar \ /usr/local/src/shibboleth-identityprovider-2.4.4/lib/
attribute-resolver.xml
configuration
(element <dc:FilterTemplate> in the LDAP DataConnector).
You might need to adapt the filter according to the descriptions in the Shibboleth Wiki IdP2.2 upgrade instructions (Changes in Principal Name Returned from Authentication).
(Since IdP version 2.2, the IdP sets the variable $requestContext.principalName
to the user's login ID
(the thing they type in the username field of the login page) instead of the value returned by the authentication engine.)
Update the logging configuration in the file logging.xml
. We recommend to limit the archivation of log files to a maximum of 6 months.
We provide an adapted configuration file logging.xml you can download and use. This configuration file limits the archivation of log files to a maximum of 6 months and adapts some settings that are not optimal in the default configuration.
WARNING: The following instructions install a new version of the file logging.xml
and replace the old file. In case you have made specific manual changes to the existing file,
please carefully compare the old and the new file. If in doubt, try to keep the existing
file or ask the SWITCHaai Team for support.
Our specific logging.xml
file can be downloaded as follows:
cd /opt/shibboleth-idp/conf/ cp logging.xml logging.xml.old curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/logging.xml
(If you upgrade from IdP version 2.0/2.1, and want to keep your existing logging configuration, please apply the changes in the Shibboleth Wiki IdP2.2 upgrade instructions (Logging Configuration).)
cd /usr/local/src/shibboleth-identityprovider-2.4.4
If you use Debian 7.0 "wheezy" and have the package default-jre-headless
installed:
JAVA_HOME=/usr/lib/jvm/default-java ./install.sh
Else (if JAVA_HOME
is set in /etc/profile
):
./install.sh
Buildfile: src/installer/resources/build.xml
install:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Be sure you have read the installation/upgrade instructions on the
Shibboleth website before proceeding.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
Where should the Shibboleth Identity Provider software be installed?
[/opt/shibboleth-idp]
The directory '/opt/shibboleth-idp' already exists. Would you like to
overwrite this Shibboleth configuration? (yes, [no])
no
(further output omitted)
Set appropriate ownership and permissions for the files in
/opt/shibboleth-idp/
.
cd /opt/shibboleth-idp chown -R tomcat6 logs metadata chgrp -R tomcat6 conf credentials logs metadata war lib chown tomcat6 conf/attribute-filter.xml chmod 664 conf/attribute-filter.xml chmod 755 lib war chmod 755 conf credentials chmod 640 conf/logging.xml chmod 640 conf/attribute-resolver.xml chmod 644 conf/attribute-filter.xml chmod 755 logs metadata cd credentials chown root idp.key chgrp tomcat6 idp.{key,crt} chmod 440 idp.key chmod 644 idp.crt rm -f idp.jks
Check the autoDeploy
parameter in /etc/tomcat6/server.xml
. If its value is true, change it to false.
/etc/init.d/tomcat6 restart
Finally, test whether your IdP still works as before.
Access the AAI Viewer, choose your home organization, login and then verify whether all attributes are available.
In case you have enabled support for interfederation, you should also verify whether all attributes required for interfederation are released.
Access the Interfederation Test page and authenticate with AAI.
More information about this test can be found in the guide Enabling Interfederation Support for a Shibboleth Identity Provider (IdP) in SWITCHaai.
If problems occur during the upgrade, or something doesn't work as expected, please contact the SWITCHaai Team by email: aai@switch.ch.
General support website: http://www.switch.ch/aai/support/