2010-08-24 10:42:35 +0200
Table of Contents
This guide describes the installation of a Shibboleth Identity Provider (IdP) and its configuration for the SWITCHaai Federation. It covers installation with Tomcat 6.0 and Apache 2.2 on Debian 5.0 (lenny) using CAS [CAS] Single Sign-On. The ShibWiki provides information about other deployments.
The following typographic conventions are used in this guide:
file and directory names are formatted like this.
file contents
are formatted like this.
shell commandsand output
are formatted like this.
configuration items different from the standard IdP configurationare formatted like this.
specific values for an installationare formatted like this. They have to be adapted for each installation.
The Shibboleth Identity Provider (IdP) is a Java web application using SAML2. The IdP has endpoints for user authentication (SSO) and for back-channel attribute requests (Attribute Authority, AA). Communication with these endpoints is usually secured with TLS/SSL, for which X.509 server certificates are used.
The setup in this guide is as follows:
Sun Java 6
Apache 2 with Tomcat 6.0
Shibboleth 2
SSO endpoint on port 443, using an X.509 certificate from a well-known CA
Attribute Authority endpoint on port 8443, using a self-signed certificate
Central Authentication Service (CAS) server and client
The example values used in this guide are:
aai-logon.example.orgThe DNS name of the Home Organization (Identity Provider) server. Names like "aai-logon", "aai-login", "aai" or something similar are used.
ldap.example.orgThe name of the LDAP server where the user attributes are stored.
https://aai-logon.example.org/idp/shibbolethentityID of the IdP in the federation metadata
As indicated in the title, this guide applies to Debian 5.0 (lenny) and contains some references to Debian specific tools. However, the Shibboleth IdP can be installed on every system which allows to run the Sun Java virtual machine and a web application server like Tomcat or JBoss.
The following packages should be installed on the system prior to the installation:
OpenSSLRecommended Version 0.9.8, Debian Package: openssl. The OpenSSL tools will be used to handle server certificates.
NTPDebian package: ntp-server (or any other package which provides time-synchronization). Servers running Shibboleth should have their system time synchronized in order to avoid clock-skews.
Apache 2.2 with mod_ssl and mod_proxy_ajpDebian package: apache2. The modules mod_ssl and mod_proxy_ajp are part of the package.
cURLDebian package: curl (optional, as an alternative to wget)
gnupg (GNU Privacy Guard) and gpgvDebian packages: gnupg and gpgv (recommended, to verify the signature on the installed software)
MavenMaven will be used to build CAS server and client. Debian package: maven2.
As Java 1.5 is already being phased out by Sun [SunJava], we strongly recommend to install the current version Sun Java 6. The official Java 6 from Sun is available as a package in Debian 5.0 (lenny). However, to have the latest version, some prefer to install Java manually. This section shows the installation of the Debian package and how to install Sun Java 6 without a packaging system.
Make sure the non-free repository is included in the apt sources
(sources.list file or a file in directory
/etc/apt/sources.list.d/).
# /etc/apt/sources.list deb http://www.debian.org lenny main contrib non-free
If you install this package, the following dependent packages will also be
installed (among others):
sun-java6-bin, sun-java6-jre, sun-java6-demo.
Java will be installed in /usr/lib/jvm/java-6-sun. To avoid
conflicts with other Java virtual machines like kaffe or
gcj, deinstalling them is highly suggested.
You may also include the following lines in /etc/profile:
JAVA_HOME=/usr/lib/jvm/java-6-sun export JAVA_HOME
Check that the correct Java version is in the path:
java -versionjava version "1.6.0_21"[...]
Once Java is installed, the rest of this section can be skipped. Continue with section Tomcat Installation.
This section shows the steps to manually install Sun Java JDK 6.
Download Java SE Development Kit (JDK) 6 for Linux from http://java.sun.com
Install Java 6 in directory /opt while removing the
symlink to a previously installed version (if applicable).
cd /opt
chmod 750 jdk-6u21-linux-i586.bin
./jdk-6u21-linux-i586.bin
test -d /opt/java && rm /opt/java
ln -s /opt/jdk1.6.0_21 /opt/java
Use Debian update-alternatives to include the Java binaries into the system path.
export JAVA_HOME=/opt/java
/usr/sbin/update-alternatives --install /usr/bin/java \
java $JAVA_HOME/bin/java 200
/usr/sbin/update-alternatives --install /usr/bin/javac \
javac $JAVA_HOME/bin/javac 200
/usr/sbin/update-alternatives --install /usr/bin/jar \
jar $JAVA_HOME/bin/jar 200
/usr/sbin/update-alternatives --install /usr/bin/keytool \
keytool $JAVA_HOME/bin/keytool 200
You may also include the following lines at the end of
/etc/profile:
JAVA_HOME=/opt/java export JAVA_HOME
Apache Tomcat [ApacheTomcat] 6.0.17 or greater is the required version to use together with Shibboleth Identity Provider 2. As there is no Tomcat 6.0 package in Debian/stable, we give instructions to manually install Tomcat.
For further information about the setup of Tomcat (e.g. running Tomcat with jsvc), please refer to the Apache Tomcat website.
Download the latest Tomcat 6.0.x version from the Apache Tomcat website.
Unpack apache-tomcat-6.0.28.tar.gz in /opt.
cd /opt
tar -xzf apache-tomcat-6.0.28.tar.gz
Create symlinks to facilitate access to configuration and log directories of Tomcat:
ln -s /opt/apache-tomcat-6.0.28 /opt/tomcat
ln -s /opt/tomcat/conf /etc/tomcat
ln -s /opt/tomcat/logs /var/log/tomcat
Remove unnecessary files from /opt/tomcat/bin:
cd /opt/tomcat/bin
rm *.bat
Remove web applications you don't need from /opt/tomcat/webapps:
cd /opt/tomcat/webapps
rm -rf docs examples host-manager manager
Create a directory for endorsed libraries (/opt/tomcat/endorsed):
cd /opt/tomcat
mkdir /opt/tomcat/endorsed
Create a symlink to catalina.sh which is used to start tomcat.
ln -s /opt/tomcat/bin/catalina.sh /etc/init.d/tomcat
Configure JVM memory options. The values for memory usage depend on the physical memory of the
server. Set Xmx to 512MBytes minimum and
XX:MaxPermSize to half of the available memory or
512MBytes minimal.
In /opt/tomcat/bin/catalina.sh set the JAVA_OPTS variable:
#
# $Id: catalina.sh ... $
# -----------------------------------------------------------------------------
JAVA_OPTS="-Xmx512M -XX:MaxPermSize=512M"
# OS specific support. $var _must_ be set to either true or false.
Update the different rc.d to start automatically Tomcat with the default runlevels
update-rc.d tomcat defaults
This section describes the installation of the Shibboleth IdP [ShibbolethInternet2] together with a database for persistent identifiers.
If you update from a previous 2.x IdP version, please make a backup of your
configuration files, i.e. backup the directory /opt/shibboleth-idp/conf.
cd /opt
tar -cvzf shibboleth-idp_conf.tar.gz ./shibboleth-idp/conf
Get Shibboleth IdP 2.1.5 from the Shibboleth website.
cd /opt
curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.1.5/shibboleth-identityprovider-2.1.5-bin.zip
curl -O http://shibboleth.internet2.edu/downloads/shibboleth/idp/2.1.5/shibboleth-identityprovider-2.1.5-bin.zip.asc
Download the PGP Keys, import them and verify signature on the downloaded file. This step is needed to verify the integrity of the downloaded software (optional, but highly advised).
curl -O http://shibboleth.internet2.edu/downloads/KEYS
gpg --import KEYS
gpgv --keyring ~/.gnupg/pubring.gpg shibboleth-identityprovider-2.1.5-bin.zip.asc
gpgv: Signature made [...] using DSA key ID A1EAE3E8
gpgv: Good signature from [...]
rm KEYS
Extract the shibboleth-identityprovider-2.1.5-bin.zip and make the installer script install.sh executable. The archive will be
extracted into the directory shibboleth-identityprovider-2.1.5:
cd /opt
jar -xf shibboleth-identityprovider-2.1.5-bin.zip
cd /opt/shibboleth-identityprovider-2.1.5
chmod u+x install.sh
This and the subsequent step are done to modify the ant target selfSignedCert which will allow 3 years self-signed certificates.
cd /opt
curl -Ok https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.1/idp/ant-extensions-13Apr2008.jar
mv ant-extensions-13Apr2008.jar ./shibboleth-identityprovider-2.1.5/src/installer/lib/
Modify the ant task selfSignedCert in the file /opt/shibboleth-identityprovider-2.1.5/src/installer/resources/build.xml as follows:
<selfSignedCert hostname="${idp.hostname}" years="3"
privateKeyFile="${idp.home.path}/credentials/idp.key"
certificateFile="${idp.home.path}/credentials/idp.crt"
keystoreFile="${idp.home.path}/credentials/idp.jks"
keystorePassword="${idp.keystore.pass}"
uriSubjectAltNames="${idp.entity.id}" />
Endorse XML/Xerces libraries from the Shibboleth IdP package in
$CATALINA_HOME/endorsed (with
$CATALINA_HOME=/opt/tomcat in case of a manually installed
Tomcat).
cd /opt/shibboleth-identityprovider-2.1.5
cp ./endorsed/*.jar /opt/tomcat/endorsed/
Run the ant task to install the Shibboleth IdP software.
chmod 755 install.sh ./install.shBuildfile: 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]/opt/shibboleth-idpWhat is the fully qualified hostname of the Shibboleth Identity Prov ider server? [default: idp.example.org]A keystore is about to be generated for you. Please enter a password that will be used to protect it.aai-logon.example.orgUpdating property file: /opt/shibboleth-identityprovider-2.1.5/src/i nstaller/resources/install.properties Created dir: /opt/shibboleth-idp Created dir: /opt/shibboleth-idp/bin [...] BUILD SUCCESSFUL Total time: 25 secondschangeit
Set symbolic links for your convenience. Link /etc/shibboleth to the shibboleth-idp
configuration directory and /var/log/shibboleth to the shibboleth-idp log directory:
ln -s /opt/shibboleth-idp/conf /etc/shibboleth
ln -s /opt/shibboleth-idp/logs /var/log/shibboleth
Set the IDP_HOME environment variable:
export IDP_HOME=/opt/shibboleth-idp
You may also include the following line into your /etc/profile file:
IDP_HOME=/opt/shibboleth-idp export IDP_HOME
Create the directory for the context descriptor, if not already there:
cd /opt/tomcat
mkdir -p conf/Catalina/localhost
Create a context descriptor for the IdP web application in
/opt/tomcat/conf/Catalina/localhost/idp.xml:
<Context
docBase="/opt/shibboleth-idp/war/idp.war"
privileged="true"
antiResourceLocking="false"
antiJARLocking="false"
unpackWAR="false"
swallowOutput="true" />
This section shows how to install and configure a MySQL [MySQL] database for persistent identifiers locally on the IdP server. A remote MySQL server may also be used, as long as it meets the availability requirements of the IdP server.
Install the Debian 5.0 (lenny) package for MySQL server version 5.0:
apt-get install mysql-server-5.0With the defaults, the mysql daemon only listens to localhost on IPv4.
Set password for the root user in MySQL:
/usr/bin/mysqladmin -u root password 'secret-password'
Create database:
mysql -u root -pmysql>SET NAMES 'utf8'; SET CHARACTER SET utf8; CHARSET utf8; CREATE DATABASE IF NOT EXISTS shibboleth CHARACTER SET=utf8; USE shibboleth;
Create table shibpid for the persistent id:
CREATE TABLE IF NOT EXISTS shibpid (
localEntity TEXT NOT NULL,
peerEntity TEXT NOT NULL,
principalName VARCHAR(255) NOT NULL default '',
localId VARCHAR(255) NOT NULL,
persistentId VARCHAR(36) NOT NULL,
peerProvidedId VARCHAR(255) default NULL,
creationDate timestamp NOT NULL default CURRENT_TIMESTAMP
on update CURRENT_TIMESTAMP,
deactivationDate timestamp NULL default NULL,
KEY persistentId (persistentId),
KEY persistentId_2 (persistentId, deactivationDate),
KEY localEntity (localEntity(16), peerEntity(16),localId),
KEY localEntity_2 (localEntity(16), peerEntity(16),
localId, deactivationDate)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;
Show information about the table that has been created in the step before.
DESCRIBE shibpid;
+------------------+--------------+------+-----+-------------------+-------+
| Field | Type | Null | Key | Default | Extra |
+------------------+--------------+------+-----+-------------------+-------+
| localEntity | text | NO | MUL | | |
| peerEntity | text | NO | | | |
| principalName | varchar(255) | NO | | | |
| localId | varchar(255) | NO | | | |
| persistentId | varchar(36) | NO | MUL | | |
| peerProvidedId | varchar(255) | YES | | NULL | |
| creationDate | timestamp | NO | | CURRENT_TIMESTAMP | |
| deactivationDate | timestamp | YES | | NULL | |
+------------------+--------------+------+-----+-------------------+-------+
8 rows in set (0.00 sec)
Create a user shibboleth with password demo
and restrict permissions to database shibboleth:
USE mysql;
INSERT INTO user (Host,User,Password,Select_priv,
Insert_priv,Update_priv,Delete_priv,Create_tmp_table_priv,
Lock_tables_priv,Execute_priv) VALUES
('localhost','shibboleth',PASSWORD('demo'),
'Y','Y','Y','Y','Y','Y','Y');
FLUSH PRIVILEGES;
GRANT ALL ON shibboleth.* TO 'shibboleth'@'localhost'
IDENTIFIED BY 'demo';
FLUSH PRIVILEGES;
QUIT
Check if the user shibboleth has been created
with password demo:
mysql -u shibboleth -pEnter passworddemoWelcome to the MySQL monitor. Commands end with ; or \g. [...]
Download the MySQL jdbc connector from dev.mysql.com. Extract it in /opt:
cd /opt
tar -xvzf mysql-connector-java-5.1.13.tar.gz
Copy the .jar file with the connector classes to the IdP's library directory:
cp mysql-connector-java-5.1.13/mysql-connector-java-5.1.13-bin.jar \
/opt/shibboleth-identityprovider-2.1.5/lib/
On the IdP system, X.509 certificates are installed for different purposes:
secure the traffic on the login page
secure the communication with the Shibboleth Service Providers
For the IdP login page, a certificate from an official CA (of which the root is in the browser) is needed. This will make sure the users can verify they are submitting their credentials to a server they trust and they don't get pop-ups. The procedure to get such a certificate is described in the following.
For the communication with the Shibboleth Service Providers, the IdP installer generates a self-signed certificate (idp.crt, idp.key) which has to be included in the AAI metadata.
In the following the needed steps to get a server certificate are described. For a full documentation how to get SWITCHpki certificates, see the SWITCHpki web pages. SWITCHpki allows the use of Subject Alternative Names in certificates. The desired Subject AltNames can be submitted with the certificate request.
OpenSSL is available on many platforms (for Windows binaries) and can be used to generate a key pair and a CSR. The most convenient way, in our opinion, is to write a short OpenSSL configuration file which you feed to the openssl req command afterwards (but feel free to use an alternative procedure if you prefer).
Create a text file named myserver.cnf (where myserver is supposed to denote the name/FQDN of your server) with the following content:
# OpenSSL configuration file for creating a CSR for a server certificate # Adapt at least the FQDN and ORGNAME lines, and then run # openssl req -new -config myserver.cnf -keyout myserver.key -out myserver.csr # on the command line. # the fully qualified server (or service) name FQDN =# the name of your organization # (see also https://www.switch.ch/pki/participants.html) ORGNAME =foo.example.org# subjectAltName entries: to add DNS aliases to the CSR, delete # the '#' character in the ALTNAMES line, and change the subsequent # 'DNS:' entries accordingly. Please note: all DNS names must # resolve to the same IP address as the FQDN. ALTNAMES = DNS:$FQDN # , DNS:bar.example.org , DNS:www.foo.example.org # --- no modifications required below --- [ req ] default_bits = 2048 prompt = no encrypt_key = no default_md = sha1 distinguished_name = dn req_extensions = req_ext [ dn ] C = CH O = $ORGNAME CN = $FQDN [ req_ext ] subjectAltName = $ALTNAMESExample University
The CN attribute is the only attribute which must always be specified in a CSR for a SWITCHpki QuoVadis certificate. All other attributes are optional (as far as the CSR is concerned), but some of them will automatically be added to the issued certificate, if needed: C (countryName), ST (stateOrProvinceName), L (localityName) and O (organizationName). If desired, an OU (organizationalUnit) attribute can be included in the request.
The CN attribute must be set to the fully qualified domain name of your server - i.e. www.example.com, www.subdomain.example.com or similar. The req_ext section can be used to specify subjectAltName entries if you prefer specifying them this way (otherwise, simply use the text field on the enrollment form). For backward compatibility, the old multi-CN format used by SCS/GlobalSign continues to be supported, but is considered deprecated.
Then, after having saved the myserver.cnf file, create the key pair and the CSR with the following command(s):
umask 0377
openssl req -new -config myserver.cnf -keyout myserver.key \
-out myserver.csr
This will create a 2048-bit RSA key pair, store the private key in the file myserver.key and write the CSR to the file myserver.csr. The private key is stored with no passphrase, that's why the umask command is used to tighten file permissions first (on a non-UNIX system, use a directory with restrictive file ACLs or equivalent).
The CSR can then be submitted through the SWITCHpki QuoVadis certificate request form.
To examine your CSR, use the following command (prints subject, public key and requested extensions, if present):
openssl req -in myserver.csr -noout -text \
-nameopt sep_multiline
User authentication can be done on many ways if Apache and Tomcat are used. Firstly, the Shibboleth IdP has built-in authentication handlers. Then, Apache and Tomcat offer user authentication and Single Sign-On systems exist for both of these web servers. Even if Apache is put in front of Tomcat, user authentication can be handled by Tomcat i.e. by the CAS SSO. If authentication has to be done by Apache, there is the Pubcookie SSO and Apache modules (mod_ldap, mod_auth_pam) for various backends.
To build CAS server 3, maven 2 is required. This sections shows how to install maven 2.
Install the maven package.
apt-get install maven2Users behind a firewall, forced to use an http proxy, see the proxy guide for maven.
Get CAS server 3.4 from the CAS website.
cd /opt
curl -O http://www.ja-sig.org/downloads/cas/cas-server-3.4.2.1-release.zip
Uncompress CAS server in /opt.
cd /opt
jar -xf cas-server-3.4.2.1-release.zip
Make the Virginia Tech LDAP Login Module classes available to CAS:
cd /opt/cas-server-3.4.2.1
mkdir -p cas-server-webapp/src/main/webapp/WEB-INF/lib
cp /opt/shibboleth-idp/lib/vt-ldap-2.8.5.jar \
./cas-server-webapp/src/main/webapp/WEB-INF/lib/
Enable the JAAS authentication handler for the cas web application by editing
cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml.
Within the AuthenticationManager's "authenticationHandlers" property,
place the following configuration (replace the SimpleTestUsernamePassword handler):
<bean class="org.jasig.cas.authentication.handler.support.JaasAuthenticationHandler" />
Adapt the server name in cas-server-webapp/src/main/webapp/WEB-INF/cas.properties:
cas.securityContext.serviceProperties.service=cas.securityContext.casProcessingFilterEntryPoint.loginUrl=https://aai-logon.example.org:443/cas/services/j_acegi_cas_security_checkcas.securityContext.ticketValidator.casServerUrlPrefix=https://aai-logon.example.org:443/cas/logincas.themeResolver.defaultThemeName=default cas.viewResolver.basename=default_views host.name=cas #database.hibernate.dialect=org.hibernate.dialect.OracleDialect #database.hibernate.dialect=org.hibernate.dialect.MySQLDialect database.hibernate.dialect=org.hibernate.dialect.HSQLDialecthttps://aai-logon.example.org:443/cas
Configure the logfile location in cas-server-webapp/src/main/webapp/WEB-INF/classes/log4j.xml:
<!-- ... -->
<appender name="cas" class="org.apache.log4j.RollingFileAppender">
<param name="File" value="/opt/shibboleth-idp/logs/cas.log"/opt/shibboleth-idp/logs/perfStats.log"
Build the CAS server web application:
cd cas-server-webapp mvn package
Create the context descriptor file $CATALINA_HOME/conf/Catalina/localhost/cas.xml:
<Context
docBase="/opt/cas-server-3.4.2.1/cas-server-webapp/target/cas.war"
privileged="true"
antiResourceLocking="false"
antiJARLocking="false"
unpackWAR="false" />
Configure JAAS in $IDP_HOME/conf/login.config with
[VTLdap]:
CAS {
// Example LDAP authentication
// See: https://spaces.internet2.edu/display/SHIB2/IdPAuthUserPass
edu.vt.middleware.ldap.jaas.LdapLoginModule required
host="ldap.example.org"
port="389"
ssl="false"
tls="false"
base="ou=people,dc=example,dc=org"
subtreeSearch="true"
userField="uid"
serviceUser="cn=administrator,dc=example,dc=org"
serviceCredential="password";
// Example Kerberos authentication, requires Sun's JVM
// See: https://spaces.internet2.edu/display/SHIB2/IdPAuthUserPass
/*
com.sun.security.auth.module.Krb5LoginModule required
keyTab="/path/to/idp/keytab/file";
*/
};
Have the JVM use the JAAS configuration above. Place the following line in
/etc/java-6-sun/security/java.security:
# # Default login configuration file # login.config.url.1=file:/opt/shibboleth-idp/conf/login.config
Get the JA-SIG CAS Java Client from the CAS website.
cd /opt
curl -O http://www.ja-sig.org/downloads/cas-clients/cas-client-3.1.3-release.zip
Uncompress cas-client in /opt.
cd /opt
jar -xf cas-client-3.1.3.zip
Build cas client:
cd cas-client-3.1.3/cas-client-core
mvn package
Make the cas client classes available to the Shibboleth IdP web application:
cp cas-client-core/target/cas-client-core-3.1.3.jar \
/opt/shibboleth-identityprovider-2.1.5/lib/
In /opt/tomcat/conf/server.xml, configure the AJP 1.3 Connector
on port 8009:
<!-- Define an AJP 1.3 Connector on port 8009 -->
<Connector port="8009" address="127.0.0.1"
enableLookups="false" redirectPort="443"
protocol="AJP/1.3"
tomcatAuthentication="false" />
Other connectors are not needed when Apache is run in front of Tomcat, so they
should be commented out (i.e. the Connector for port 8080).
Apache will be configured with the modules mod_ssl for SSL support and
mod_proxy_ajp to redirect requests to Tomcat.
The Apache configuration usually takes place in files in the directory
/etc/apache2/sites-available/.
Copy the aai-logon.example.org.key/etc/ssl/private/ and aai-logon.example.org.crt/etc/ssl/certs/.
cp aai-logon.example.org.key /etc/ssl/private/
cp aai-logon.example.org.crt /etc/ssl/certs/
If a SWITCHpki QuoVadis certificate is going to be used, get the QuoVadis Global SSL ICA certificate (for SSLCertificateChainFile) qvsslica.crt.pem and move it into the directory /etc/ssl/certs/.
curl -Ok https://www.switch.ch/pki/quovadis/qvsslica.crt.pem
mv qvsslica.crt.pem /etc/ssl/certs/
To improve your server's security, consider adding the ServerTokens directive in /etc/apache2/apache2.conf.
ServerTokens Prod
Configure the virtual host on aai-logon.example.org/etc/apache2/sites-available or adapt an existing one.
For example, use /etc/apache2/sites-availabe/aai-logon.
Make sure to set the SSLCertificateChainFile to a file which chains to the root of the CA which issued the certificate.
<IfModule mod_ssl.c> <VirtualHost _default_:443> ServerNameaai-logon.example.org:443SSLEngine On SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:!SSLv2:+EXP SSLProtocol all -SSLv2 SSLCertificateFile /etc/ssl/certs/aai-logon.example.org.crtSSLCertificateKeyFile /etc/ssl/private/aai-logon.example.org.keySSLCertificateChainFile /etc/ssl/certs/qvsslica.crt.pemSSLOptions +StdEnvVars SetEnvIf User-Agent ".*MSIE.*" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 <IfModule mod_proxy_ajp.c> ProxyRequests Off <Proxy ajp://localhost:8009> Allow from all </Proxy> ProxyPass /idp ajp://localhost:8009/idp retry=5 # uncomment the following line if you use CAS # ProxyPass /cas ajp://localhost:8009/cas retry=5 </IfModule> </VirtualHost> </IfModule>
Configure the virtual host for port 8443. Make a new configuration
file in /etc/apache2/sites-available or adapt an existing one.
For example, use /etc/apache2/sites-availabe/aai-aa.
<IfModule mod_ssl.c>
<VirtualHost _default_:8443>
ServerName aai-logon.example.org:8443
SSLEngine On
SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:!SSLv2:+EXP
SSLProtocol all -SSLv2
SSLCertificateFile /opt/shibboleth-idp/credentials/idp.crt
SSLCertificateKeyFile /opt/shibboleth-idp/credentials/idp.key
SSLVerifyClient optional_no_ca
SSLVerifyDepth 10
SSLOptions -StdEnvVars +ExportCertData
SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
<IfModule mod_proxy_ajp.c>
ProxyRequests Off
<Proxy ajp://localhost:8009>
Allow from all
</Proxy>
ProxyPass /idp ajp://localhost:8009/idp retry=5
</IfModule>
</VirtualHost>
</IfModule>
Enable both virtual hosts (aai-logon and aai-aa):
a2ensite aai-logon aai-aa
Enabling site aai-logon.
Enabling site aai-aa.
Run '/etc/init.d/apache2 reload' to activate new configuration!
Enable the ssl module.
a2enmod ssl
Module ssl installed; run /etc/init.d/apache2 force-reload to enable.
Enable the ajp proxy module, the module mod_proxy will also be
enabled.
a2enmod proxy_ajp
Enabling proxy as a dependency
Module proxy installed; run /etc/init.d/apache2 force-reload to enable.
Module proxy_ajp installed; run /etc/init.d/apache2 force-reload to enable.
Make sure the server listens on port 443 (and 8443 for AA connections)
with the Listen directive in /etc/apache2/ports.conf.
Listen 443 Listen 8443
Restart the apache httpd server:
apache2ctl -tSyntax OKapache2ctl -k restart
The credentials which the Shibboleth IdP uses are in the
/opt/shibboleth-idp/credentials/ directory.
The installer generates a self-signed certificate which
will be used within the SWITCHaai federation.
The certificate is also included in the IdP's metadata
in the file /opt/shibboleth-idp/metadata/idp-metadata.xml.
Whenever the IdP's credentials are changed, this file has to be changed
as well.
Remember to set appropriate ownership and permissions, notably
for the file idp.key.
cd /opt/shibboleth-idp/credentials
chown root idp.key
chgrp root idp.{key,crt}
chmod 440 idp.key
chmod 644 idp.crt
Download the SWITCHaai metadata trust anchor.
cd /tmp
curl -O http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem
Compare the certificate fingerprint with the fingerprint of the SWITCHaai Root CA certificate shown on https://www.switch.ch/pki/aai/:
openssl x509 -in SWITCHaaiRootCA.crt.pem \
-fingerprint -sha1 -noout
SHA1 Fingerprint=3C:E2:5A:E0:9D:B4:BB:2B:FD:33:3C:22:80:39:F7:FC:4A:F9:2C:E9
If the fingerprint is correct, copy the certificate to IdP's credentials
directory.
cp SWITCHaaiRootCA.crt.pem /opt/shibboleth-idp/credentials/
chmod 444 /opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem
The SWITCHaai specific relying-party.xml file can be downloaded
as a template for your installation. Backup the file generated by the installer first.
cd /opt/shibboleth-idp/conf/
mv relying-party.xml relying-party.xml.orig
curl -Ok https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.1/idp/relying-party.xml
In the configuration file relying-party.xml,
configure the Relying Party elements, the Metadata Provider to use the SWITCHaai
federation metadata and the trusted root certificate as shown below.
Please make sure the StaticPKIXSignature Metadata TrustEngine
is used.
The entityID (https://aai-logon.example.org/idp/shibboleth)
of the IdP may be adapted also, if a different value than the default should
be used.
For the AAI test federation, configure http://metadata.aai.switch.ch/metadata.aaitest.xml as metadataURL and /opt/shibboleth-idp/metadata/metadata.aaitest.xml
as backingFile.
<!--
...
-->
<!-- ========================================== -->
<!-- Relying Party Configurations -->
<!-- ========================================== -->
<AnonymousRelyingParty provider="https://aai-logon.example.org/idp/shibboleth"https://aai-logon.example.org/idp/shibboleth"defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport">
<ProfileConfiguration xsi:type="saml:ShibbolethSSOProfile" />
<ProfileConfiguration xsi:type="saml:SAML1AttributeQueryProfile" />
<ProfileConfiguration xsi:type="saml:SAML1ArtifactResolutionProfile" />
<ProfileConfiguration xsi:type="saml:SAML2SSOProfile" />
<ProfileConfiguration xsi:type="saml:SAML2AttributeQueryProfile" />
<ProfileConfiguration xsi:type="saml:SAML2ArtifactResolutionProfile" />
</DefaultRelyingParty>
<!-- See https://www.switch.ch/aai/SAML1/Attribute-Push for more information -->
<RelyingParty id="https://www.switch.ch/aai/SAML1/Attribute-Push"
provider="https://aai-logon.example.org/idp/shibboleth"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
defaultSigningCredentialRef="IdPCredential">
<ProfileConfiguration xsi:type="saml:ShibbolethSSOProfile"
includeAttributeStatement="true" />
<ProfileConfiguration xsi:type="saml:SAML2SSOProfile" />
</RelyingParty>
<!-- See https://www.switch.ch/aai/SAML2/Attribute-Pull for more information -->
<RelyingParty id="https://www.switch.ch/aai/SAML2/Attribute-Pull"
provider="https://aai-logon.example.org/idp/shibboleth"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
defaultSigningCredentialRef="IdPCredential">
<ProfileConfiguration xsi:type="saml:SAML2SSOProfile"
includeAttributeStatement="false" />
<ProfileConfiguration xsi:type="saml:SAML2AttributeQueryProfile" />
<ProfileConfiguration xsi:type="saml:SAML2ArtifactResolutionProfile" />
</RelyingParty>
<!-- ========================================== -->
<!-- Metadata Configuration -->
<!-- ========================================== -->
<!-- MetadataProvider the combining other MetadataProviders -->
<MetadataProvider id="ShibbolethMetadata" xsi:type="ChainingMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata">
<!-- Load the IdP's own metadata. This is necessary for artifact support. -->
<MetadataProvider id="IdPMD" xsi:type="ResourceBackedMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata" >
<MetadataResource xsi:type="resource:FilesystemResource" file="/opt/shibboleth-idp/metadata/idp-metadata.xml" />
</MetadataProvider>
<!-- SWITCHaai production federation metadata provider. -->
<!-- Reads metadata from a URL and store a backup copy on the file system. -->
<!-- These attributes are set specifically for SWITCHaai -->
<!-- Validates the signature of the metadata and filters out all by SP entities in order to save memory -->
<!-- maintainExpiredMetadata: use expired metadata (boolean) -->
<!-- cacheDuration: max time until next metadata refresh (seconds) -->
<MetadataProvider id="URLMD" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
metadataURL="http://metadata.aai.switch.ch/metadata.switchaai.xml"
backingFile="/opt/shibboleth-idp/metadata/metadata.switchaai.xml"
maintainExpiredMetadata="false"
cacheDuration="3600">
<MetadataFilter xsi:type="ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
<MetadataFilter xsi:type="RequiredValidUntil" xmlns="urn:mace:shibboleth:2.0:metadata"
maxValidityInterval="604800" />
<MetadataFilter xsi:type="SignatureValidation"
xmlns="urn:mace:shibboleth:2.0:metadata"
trustEngineRef="shibboleth.MetadataTrustEngine"
requireSignedMetadata="true" />
</MetadataFilter>
</MetadataProvider>
</MetadataProvider>
<!-- ========================================== -->
<!-- Security Configurations -->
<!-- ========================================== -->
<security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
<security:PrivateKey>/opt/shibboleth-idp/credentials/idp.key</security:PrivateKey>
<security:Certificate>/opt/shibboleth-idp/credentials/idp.crt</security:Certificate>
</security:Credential>
<!-- Trust engine used to evaluate the signature on loaded metadata. -->
<security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticPKIXSignature">
<security:ValidationInfo
id="SWITCHaaiFederationCredentials"
xsi:type="security:PKIXFilesystem"
verifyDepth="3">
<security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate>
</security:ValidationInfo>
</security:TrustEngine>
<!-- DO NOT EDIT BELOW THIS POINT -->
<!--
...
-->
3268 instead of 389.
Adapt the attribute resolver to use your attribute source. The example shows a configuration with an LDAP server to resolve the attributes from. Download the SWITCHaai specific configuration file attribute-resolver.xml and adapt it.
cd /opt/shibboleth-idp/conf/
curl -Ok https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.1/idp/attribute-resolver.xml
Make sure to have replaced the salt of the storedID Connector with a random string. The random string may be generated with the following command:
openssl rand -base64 36 2>/dev/nullThe salt is a string of random data; must be at least 16 characters, 48 characters is recommended. Be sure to write down this salt value somewhere safe so that the persistentIDs are not lost if you delete your configuration file!
<!--
...
-->
<!-- ========================================== -->
<!-- Attribute Definitions -->
<!-- ========================================== -->
<!--
...
-->
<!-- ========================================== -->
<!-- Data Connectors -->
<!-- ========================================== -->
<!-- Example Static Connector -->
<!--
<resolver:DataConnector id="staticAttributes" xsi:type="Static" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
<Attribute id="eduPersonAffiliation">
<Value>member</Value>
</Attribute>
<Attribute id="eduPersonEntitlement">
<Value>urn:mace:dir:entitlement:common-lib-terms</Value>
</Attribute>
<Attribute id="swissEduPersonHomeOrganization">
<Value>aai-logon.example.org</Value>
</Attribute>
<Attribute id="swissEduPersonHomeOrganizationType">
<Value>others</Value>
</Attribute>
</resolver:DataConnector>
-->
<!-- Example Relational Database Connector -->
<!--
<resolver:DataConnector id="mySIS" xsi:type="RelationalDatabase" xmlns="urn:mace:shibboleth:2.0:resolver:dc">
<ApplicationManagedConnection jdbcDriver="oracle.jdbc.driver.OracleDriver"
jdbcURL="jdbc:oracle:thin:@db.example.org:1521:SomeDB" jdbcUserName="myid" jdbcPassword="mypassword" />
<QueryTemplate>
<![CDATA[
SELECT * FROM student WHERE gzbtpid = $requestContext.principalName
]]>
</QueryTemplate>
<Column columnName="gzbtpid" attributeID="uid" />
<Column columnName="fqlft" attributeID="gpa" type="Float" />
</resolver:DataConnector>
-->
<!-- Example LDAP Connector -->
<resolver:DataConnector id="myLDAP"
xsi:type="LDAPDirectory"
xmlns="urn:mace:shibboleth:2.0:resolver:dc"
ldapURL="ldap://ldap.example.orgou=people,dc=example,dc=orgcn=admin,dc=example,dc=orgsecret-passwordyour random string hereshibbolethdemo<resolver:PrincipalConnector xsi:type="pc:StoredId" xmlns:pc="urn:mace:shibboleth:2.0:resolver:pc" id="saml2Persistent"
nameIDFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
storedIdDataConnectorRef="myStoredId" />
</AttributeResolver>
This sample Attribute Filter Policy file attribute-filter.xml
allows the release of attributes to two Service Providers within the SWITCHaai
Federation, the Resource Registry and the Attribute Viewer. Before registering
the IdP in the Resource Registry, download the attribute-filter.xml
file.
cd /opt/shibboleth-idp/conf/
curl -Ok https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.1/idp/attribute-filter.xml
After the IdP has been registered in the Resource Registry, the configuration
for the attribute-filter.xml file will have to be changed.
The file attribute-filter.xml to be kept up to date in order to
allow the release of attributes for e.g. new Service Providers or new
attributes to be released to Service Providers.
Enable the RemoteUser login handler of the Shibboleth IdP in
the configuration file handler.xml
(remove the comments around the <LoginHandler> element):
<!--
...
-->
<!-- Login Handlers -->
<LoginHandler xsi:type="RemoteUser">
<AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthenticationMethod>
</LoginHandler>
<!-- Username/password login handler -->
<!--
<LoginHandler xsi:type="UsernamePassword"
jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config">
<AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</AuthenticationMethod>
</LoginHandler>
-->
<!--
...
-->
Configure the CAS client filter for the Shiboleth IdP web application
in /opt/shibboleth-identityprovider-2.1.5/src/main/webapp/WEB-INF/web.xml:
<!--
...
-->
<!-- Spring 2.0 listener used to load up the configuration -->
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<!-- CAS Filter Configuration -->
<context-param>
<param-name>serverName</param-name>
<param-value>https://aai-logon.example.orghttps://aai-logon.example.org/cas/loginhttps://aai-logon.example.org/cas
Redeploy the Shibboleth IdP web application, responding no. Tomcat will reload the web application provided that the context descriptor
points to the file /opt/shibboleth-idp/war/idp.war (see the IdP deployment section Shibboleth IdP Installation for that).
cd /opt/shibboleth-identityprovider-2.1.5/ ./install.sh installBuildfile: build.xml install: Is this a new installation? Answering yes will overwrite your current configuration. [yes|no]noWhere should the Shibboleth Identity Provider software be installed? [default: /opt/shibboleth-idp]/opt/shibboleth-idp(further output omitted)
Edit the /opt/shibboleth-identityprovider-2.1.5/src/main/webapp/WEB-INF/web.xml:
...
<!-- 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#
The IPv4 net 130.59.0.0/16 as well as the IPv6 net 2001:620::/48
have been registered for SWITCH.
Customize the login and error pages of the IdP. These are JSP pages that
lie in src/main/webapp/ of the Shibboleth IdP distribution.
The following files are customizable:
Login page of the Shibboleth Username/Password authentication handler.
Error page for container managed authentication. (Does not apply for this guide.)
Standard error page.
Custom 404 page for unconfigured locations in the IdP webapp.
For SWITCHaai specific design templates, refer to SWITCHaai design web pages.
Redeploy the Shibboleth IdP web application, responding no. Tomcat will reload the web application provided that the context descriptor
points to the file /opt/shibboleth-idp/war/idp.war (see the section Shibboleth IdP Installation).
cd /opt/shibboleth-identityprovider-2.1.5/ ./install.shBuildfile: 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)
The IdP's main log file is idp-process.log. Errors and warnings can be found there.
To set the log level for debugging, edit the /etc/shibboleth/logging.xml
configuration file. In the <logger> element the attribute level can be set to DEBUG.
For production use, set the log level to WARN or lower.
To enable logging for the LDAP connection, insert the following lines in
logging.xml:
<!-- Logs LDAP related messages -->
<logger name="edu.vt.middleware.ldap">
<level value="WARN"/>
</logger>
If the Shibboleth web application does not start up at all, there may be some
piece of information in the Tomcat logs in /var/log/tomcat/catalina.out.
First, make sure Apache and Tomcat are running.
apache2ctl status
Apache Server Status for localhost
(further output omitted)
If Tomcat has not been started, start it:
/etc/init.d/tomcat start
Using CATALINA_BASE: /opt/tomcat
Using CATALINA_HOME: /opt/tomcat
Using CATALINA_TMPDIR: /opt/tomcat/temp
Using JRE_HOME: /usr/lib/jvm/java-6-sun
Using CLASSPATH: /opt/tomcat/bin/bootstrap.jar
Check the Tomcat log in /var/log/tomcat/catalina.out for errors.
To test if the IdP web application is up, check the Status URL of the IdP with the web browser:
https://aai-logon.example.org/idp/status.
The IdP should send a plain text page with configuration information about your IdP with
three sections: Operating Environment Information, Identity Provider Information and
Relying Party Configurations.
If there's no such page, check the log files for errors (see section Shibboleth IdP Log Files).
You may also have to check the IdP Status URL configuration (see Section 11.1.5, “IdP Status URL configuration”).
SWITCH runs Service Providers as test counterparts for Identity Providers.
On the AAI Viewer SP (SWITCHaai federation),
the attributes sent to that resource are shown on a web page. Before testing,
make sure the attribute resolver (attribute-resolver.xml) is
configured properly and the attribute filter (attribute-filter.xml)
allows attributes to be released to the respective resource. If no
attributes are shown on the Service Provider, check your log files for errors
(see section Shibboleth IdP Log Files).
The SWITCHaai Resource Registry collects configuration information about Service Providers and Identity Providers which participate in the federations "SWITCHaai", and "AAI Test".
You are now ready to register your Identity Provider in the
AAI Resource Registry.
Doing this allows to download a customized attribute-filter.xml
file for the IdP.
The attribute-filter.xml file can be configured to be downloaded
from a URL as follows.
The correct download URL has to be obtained from the Resource Registry.
A configuration example in service.xml is shown below.
Instead of example.org put in your IdP's hostname or domain name.
<Service id="shibboleth.AttributeFilterEngine"
xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine"
configurationResourcePollingFrequency="3600000"
configurationResourcePollingRetryAttempts="128">
<ConfigurationResource xsi:type="resource:FileBackedHttpResource"
url="https://rr.aai.switch.ch/switchaai/example.org/opt/shibboleth-idp/conf/attribute-filter.xml"/>
</Service>
For the AAI test federation, configure https://rr.aai.switch.ch/aaitest/example.org/attribute-filter.xml as url (replace example.org with an appropriate value).
Restart Tomcat to enable the new settings.
This concludes the Shibboleth IdP installation.
Make sure you keep the software on your IdP system up to date! Here are some hints that may help you to do so:
Sign up to the aai-operations mailing list.
Regularly check for security updates of your operating system. Debians security page lists the latest updates.
Security updates of the Shibboleth software is announced on their security advisories page.
Authentication and Authorization Infrastructure
System initiated web-service connection to the IdP
Certification authority
Certificate revocation list
Certificate signing request
User initiated browser connection to the IdP
Identity Provider
Public key infrastructure
Security Assertion Markup Language
[AttrSpec] AAI Attribute Specification. SWITCH. 9.2007. http://www.switch.ch/aai/attributes .
[AAIRR] AAI Resource Registry. https://rr.aai.switch.ch .
[ApacheTomcat] Apache Tomcat. http://tomcat.apache.org .
[Debian] Debian. http://www.debian.org .
[EmbdCerts] Requirements for SAML2 Metadata embedded certificates. SWITCH. 9.2008. http://www.switch.ch/aai/support/embeddedcerts-requirements.html .
[IdPADConfigIssues] Microsoft Active Directory Configuration Issues. https://spaces.internet2.edu/display/SHIB2/IdPADConfigIssues .
[JAAS] Java Authentication and Authorization Service (JAAS) Reference Guide. http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASRefGuide.html .
[MySQL] MySQL. http://dev.mysql.com .
[ShibbolethInternet2] Shibboleth Website. http://shibboleth.internet2.edu .
[ShibWiki] Shibboleth Wiki. https://spaces.internet2.edu/display/SHIB2/ .
[SunJava] Sun Java. http://java.sun.com .
[uapprove] SWITCH AAI uApprove. http://www.switch.ch/aai/uapprove/ .
[VTLdap] Virginia Tech LDAP Module. http://code.google.com/p/vt-middleware/wiki/vtldapJAAS .
[CAS] CAS server and client. http://www.ja-sig.org/products/cas/ .
[CAS-UM] CAS user manual. http://www.ja-sig.org/wiki/display/CASUM/ .
[Maven] Maven. http://maven.apache.org .