2014-12-02 15:38:48 +0100
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 7.0 (wheezy) using authentication handlers provided by the Shibboleth IdP. The ShibWiki provides information about other deployments.
The following typographic conventions are used in this guide:
file
and directory
names
file contents
shell commands
and output
configuration items different from the standard IdP configuration (as available from https://shibboleth.net/downloads/identity-provider)
specific values for an installation
These values 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:
OpenJDK 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
The example values used in this guide are:
aai-logon.example.org
The DNS name of the Home Organization (Identity Provider) server. Names like "aai-logon", "aai-login", "aai" or something similar are used.
ldap.example.org
The name of the LDAP server where the user attributes are stored.
https://aai-logon.example.org/idp/shibboleth
entityID of the IdP in the federation metadata
As indicated in the title, this guide applies to Debian 7.0 (wheezy) and contains some references to Debian specific tools. However, the Shibboleth IdP can be installed on every system which allows to run the 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:
OpenSSL
Recommended Version 1.0.0 or later, Debian Package: openssl. The OpenSSL tools will be used to handle server certificates.
NTP
Debian package: ntp (or any other package which provides time-synchronization). Servers running Shibboleth should have their system time synchronized in order to avoid clock-skews. (Note: On installations on virtual machines, the host system usually cares about synchronizing the guest's time, so running time-synchronization software on the guest might not be needed, or could even lead to problems.)
Apache 2.2 with mod_ssl and mod_proxy_ajp
Debian package: apache2. The modules mod_ssl and mod_proxy_ajp are part of the package.
cURL
Debian package: curl (optional, as an alternative to wget)
For installations on Debian, we recommend to install OpenJDK, which is available as package in Debian's main repository.
Apache Tomcat 6 is the recommended version to run the Shibboleth Identity Provider version 2. This section documents the installation with the Tomcat 6 Debian package.
For further information about Tomcat, please refer to the Apache Tomcat website.
apt-get install tomcat6
Configure JVM memory options for the needs of the IdP web application.
The values for memory usage depend on the physical memory of the
server. Set Xmx
(maximum amount of heap space available
to the JVM) to at least 512MBytes and
XX:MaxPermSize
to 128MBytes. See also
the Shibboleth Wiki
for more information. In /etc/default/tomcat6
set the
JAVA_OPTS
variable:
JAVA_OPTS="-Djava.awt.headless=true -Xmx512M -XX:MaxPermSize=128M -Dcom.sun.security.enableCRLDP=true"
If possible, you should configure a larger value than 512MBytes for the maximum amount of heap space, e.g. 1024MBytes
(-Xmx1024M
). If your IdP supports Interfederation, we recommend to configure at least 1024MBytes,
as 512MBytes might be too short for the current Interfederation metadata. Depending on the number of Service Providers contained in the metadata,
memory needs may rise in the future. If supporting Interfederation, the following values are recommended for the JAVA_OPTS
variable:
JAVA_OPTS="-Djava.awt.headless=true -Xmx1024M -XX:MaxPermSize=128M -Dcom.sun.security.enableCRLDP=true"
In the file /etc/tomcat6/server.xml, the default value of the parameter "autoDeploy" is equal to true. This means that Tomcat checks periodically for new or updated web applications. If an updated web application or context XML descriptors is found, a redeploy is triggered. This is not the preferred behavior, therefore set this to false.
<Host name="localhost" appBase="webapps"
unpackWARs="true" autoDeploy="false"
xmlValidation="false" xmlNamespaceAware="false">
This section describes the installation of the Shibboleth IdP [ShibbolethWWW] together with a database for persistent identifiers.
Get Shibboleth IdP 2.4.4 from the Shibboleth website.
cd /usr/local/src
curl -O https://shibboleth.net/downloads/identity-provider/2.4.4/shibboleth-identityprovider-2.4.4-bin.zip
Extract the shibboleth-identityprovider-2.4.4-bin.zip
and ensure the installer script install.sh
is executable. The archive will be
extracted into the directory shibboleth-identityprovider-2.4.4
:
Please install unzip in case you don't have it.
apt-get install unzip
cd /usr/local/src
unzip shibboleth-identityprovider-2.4.4-bin.zip
cd shibboleth-identityprovider-2.4.4
chmod u+x install.sh
If you use MySQL as a backend for the persistent identifiers, download the MySQL JDBC connector from https://dev.mysql.com/downloads/connector/j/.
We recommend using the newest version. We have successfully tested with mysql-connector-java-5.1.32.
Extract it in /usr/local/src/
:
cd /usr/local/src
unzip mysql-connector-java-5.1.32.zip mysql-connector-java-5.1.32/mysql-connector-java-5.1.32-bin.jar
Move the .jar
file with the connector classes to the IdP's library directory:
mv mysql-connector-java-5.1.32/mysql-connector-java-5.1.32-bin.jar \
/usr/local/src/shibboleth-identityprovider-2.4.4/lib/
Run the ant task to install the Shibboleth IdP software.
Make sure you set the environment variable (IdPCertLifeTime
)
for the IdP self-signed certificate to 3 (years).
cd /usr/local/src/shibboleth-identityprovider-2.4.4/ env IdPCertLifetime=3 JAVA_HOME=/usr/lib/jvm/default-java ./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]/opt/shibboleth-idp
What 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.org
Updating property file: /usr/local/src/shibboleth-identityprovider-2.4.4/src/i nstaller/resources/install.properties Created dir: /opt/shibboleth-idp Created dir: /opt/shibboleth-idp/bin [...] BUILD SUCCESSFUL Total time: 25 seconds
changeit
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 a context descriptor for the IdP web application in
/etc/tomcat6/Catalina/localhost/idp.xml
:
<Context docBase="/opt/shibboleth-idp/war/idp.war" privileged="true" antiResourceLocking="false" antiJARLocking="false" unpackWAR="false" swallowOutput="true" cookies="false" />
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 7.0 (wheezy) package for MySQL server:
apt-get install mysql-server
With 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 -p
mysql>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 | NULL | |
| peerEntity | text | NO | | NULL | |
| principalName | varchar(255) | NO | | | |
| localId | varchar(255) | NO | | NULL | |
| persistentId | varchar(36) | NO | MUL | NULL | |
| peerProvidedId | varchar(255) | YES | | NULL | |
| creationDate | timestamp | NO | | CURRENT_TIMESTAMP | on update CURRENT_TIMESTAMP |
| deactivationDate | timestamp | YES | | NULL | |
+------------------+--------------+------+-----+-------------------+-----------------------------+
8 rows in set (0.00 sec)
Create a user shibboleth
with a password
and restrict permissions to database shibboleth
(please replace the example password demo
in the following commands by a reasonable password chosen by you):
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 the correct password (enter the password you have chosen above):
mysql -u shibboleth -p
Enter passwordWelcome to the MySQL monitor. Commands end with ; or \g. [...]
demo
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.
SWITCHpki customers can get their certificates as described on the SWITCHpki web pages.
Institutions who can not get SWITCHpki certificates may refer to their certificate provider.
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.
This section shows how to configure authentication for the Shibboleth IdP authentication handler with a [JAAS] module.
Configure JAAS in $IDP_HOME/conf/login.config
with
[VTLdap] if you use ldaps:
ShibUserPassAuth { // Example LDAP authentication edu.vt.middleware.ldap.jaas.LdapLoginModule required ldapUrl="" baseDn="
ldaps://ldap.example.org
" bindDn="
ou=people,dc=example,dc=org
" bindCredential="
cn=idp-user,dc=example,dc=org
"; };
password for idp-user
Configure JAAS in $IDP_HOME/conf/login.config
with
[VTLdap] if you use startTLS:
ShibUserPassAuth { // Example LDAP authentication edu.vt.middleware.ldap.jaas.LdapLoginModule required ldapUrl="" tls="
ldap://ldap.example.org
" baseDn="
true
" bindDn="
ou=people,dc=example,dc=org
" bindCredential="
cn=idp-user,dc=example,dc=org
"; };
password_for_idp-user
3268
instead of 389
.
Configure JAAS in $IDP_HOME/conf/login.config
with
[VTLdap] for using localhost:
ShibUserPassAuth { // Example LDAP authentication edu.vt.middleware.ldap.jaas.LdapLoginModule required ldapUrl="" bindDn="
ldap://localhost/ou=people,dc=example,dc=org
" bindCredential="
cn=idp-user,dc=example,dc=org
"; };
password_for_idp-user
In /etc/tomcat6/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
to the directory aai-logon.example.org.key
/etc/ssl/private/
and
to the directory 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, please refer to the SWITCHpki website for more information.
To improve your server's security, consider adding the ServerTokens
directive in /etc/apache2/conf.d/security
.
ServerTokens Prod
Configure the virtual host on
for ports 443 and 8443. Create a new
configuration file in aai-logon.example.org
/etc/apache2/sites-available
or adapt an existing one.
For example, use /etc/apache2/sites-available/aai-logon
.
Make sure to set the SSLCertificateChainFile
to a file which chains to the root of the CA which issued the certificate.
ServerName aai-logon.example.org <VirtualHost _default_:443> ServerNameaai-logon.example.org:443
ServerAdminadmin@example.org
DocumentRoot /var/www SSLEngine On SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5 SSLProtocol all -SSLv2 SSLCertificateFile /etc/ssl/certs/aai-logon.example.org.crt
SSLCertificateKeyFile /etc/ssl/private/aai-logon.example.org.key
SSLCertificateChainFile /etc/ssl/certs/qvsslica.crt.pem
<Proxy ajp://localhost:8009> Allow from all </Proxy> ProxyPass /idp ajp://localhost:8009/idp retry=5 BrowserMatch "MSIE [2-6]" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 # MSIE 7 and newer should be able to use keepalive BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown </VirtualHost> <VirtualHost _default_:8443> ServerNameaai-logon.example.org:8443
ServerAdminadmin@example.org
DocumentRoot /var/www SSLEngine On SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5 SSLProtocol all -SSLv2 SSLCertificateFile /opt/shibboleth-idp/credentials/idp.crt SSLCertificateKeyFile /opt/shibboleth-idp/credentials/idp.key SSLVerifyClient optional_no_ca SSLVerifyDepth 10 <Proxy ajp://localhost:8009> Allow from all </Proxy> ProxyPass /idp ajp://localhost:8009/idp retry=5 BrowserMatch "MSIE [2-6]" \ nokeepalive ssl-unclean-shutdown \ downgrade-1.0 force-response-1.0 # MSIE 7 and newer should be able to use keepalive BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown </VirtualHost>
Enable the virtual hosts:
a2ensite aai-logon
Enabling site aai-logon.
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 -t
Syntax 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
. Set the group ownership to tomcat6
if Tomcat runs with the tomcat6
in group tomcat6
.
The Java keystore idp.jks
is not required and should be removed
(it contains a private key).
cd /opt/shibboleth-idp/credentials
chown root idp.key
chgrp tomcat6 idp.{key,crt}
chmod 440 idp.key
chmod 644 idp.crt
rm idp.jks
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 -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/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 has to be adapted to your IdP's entityID.
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 --> <!-- ========================================== --> <rp:AnonymousRelyingParty provider="defaultSigningCredentialRef="IdPCredential" /> <rp:DefaultRelyingParty provider="
https://aai-logon.example.org/idp/shibboleth"
defaultSigningCredentialRef="IdPCredential"
https://aai-logon.example.org/idp/shibboleth"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"
><rp:ProfileConfiguration xsi:type="saml:ShibbolethSSOProfile" /> <rp:ProfileConfiguration xsi:type="saml:SAML1AttributeQueryProfile" /> <rp:ProfileConfiguration xsi:type="saml:SAML1ArtifactResolutionProfile" /> <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" /> <rp:ProfileConfiguration xsi:type="saml:SAML2AttributeQueryProfile" signResponses="always" /> <rp:ProfileConfiguration xsi:type="saml:SAML2ArtifactResolutionProfile" />
</rp:DefaultRelyingParty><!-- See https://www.switch.ch/aai/SAML1/Attribute-Push for more information --> <rp:RelyingParty id="https://www.switch.ch/aai/SAML1/Attribute-Push" provider="
<!-- ========================================== --> <!-- Metadata Configuration --> <!-- ========================================== --> <!-- MetadataProvider the combining other MetadataProviders --> <metadata:MetadataProvider id="ShibbolethMetadata" xsi:type="metadata:ChainingMetadataProvider"> <!-- Load the IdP's own metadata. This is necessary for artifact support. --> <metadata:MetadataProvider id="IdPMD" xsi:type="metadata:FilesystemMetadataProvider" metadataFile="/opt/shibboleth-idp/metadata/idp-metadata.xml" maxRefreshDelay="P1D" />https://aai-logon.example.org/idp/shibboleth"
defaultAuthenticationMethod="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" defaultSigningCredentialRef="IdPCredential"> <rp:ProfileConfiguration xsi:type="saml:ShibbolethSSOProfile" includeAttributeStatement="true" /> <rp:ProfileConfiguration xsi:type="saml:SAML2SSOProfile" /> </rp:RelyingParty><!-- SWITCHaai production federation metadata provider. --> <!-- Reads metadata from a URL and stores a backup copy on the file system. --> <!-- Validates the signature of the metadata --> <metadata:MetadataProvider id="URLMD" xsi:type="metadata:FileBackedHTTPMetadataProvider" metadataURL="
http://metadata.aai.switch.ch/metadata.switchaai.xml
" backingFile="/opt/shibboleth-idp/metadata/metadata.switchaai.xml
" requireValidMetadata="true" maxRefreshDelay="PT1H"> <metadata:MetadataFilter xsi:type="metadata:ChainingFilter" > <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil" maxValidityInterval="P7D" /> <metadata:MetadataFilter xsi:type="metadata:SignatureValidation" trustEngineRef="shibboleth.MetadataTrustEngine" requireSignedMetadata="true" /> </metadata:MetadataFilter> </metadata:MetadataProvider><!-- SWITCHaai interfederation metadata provider. --> <!-- Reads interfederation metadata from a URL and stores a backup copy on the file system. --> <!-- Validates the signature of the metadata --> <!-- Enable this MetadataProvider for interfederation support --> <!-- <metadata:MetadataProvider id="InterfederationURLMD" xsi:type="metadata:FileBackedHTTPMetadataProvider" metadataURL="http://metadata.aai.switch.ch/entities/interfederation+sp" backingFile="/opt/shibboleth-idp/metadata/metadata.interfederation-sps.xml" requireValidMetadata="true" maxRefreshDelay="PT1H"> <metadata:MetadataFilter xsi:type="metadata:ChainingFilter"> <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil" maxValidityInterval="P7D"/> <metadata:MetadataFilter xsi:type="metadata:SignatureValidation" trustEngineRef="shibboleth.InterfederationMetadataTrustEngine" requireSignedMetadata="true"/> </metadata:MetadataFilter> </metadata:MetadataProvider> -->
</metadata: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:TrustedName>SWITCHaai Metadata Signer</security:TrustedName> <security:ValidationInfo id="SWITCHaaiFederationCredentials" xsi:type="security:PKIXFilesystem" verifyDepth="2"> <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate> </security:ValidationInfo> <security:ValidationOptions xsi:type="security:CertPathValidationOptionsType" forceRevocationEnabled="true" policyMappingInhibit="true" anyPolicyInhibit="true"> <security:PolicyOID>2.16.756.1.2.6.7</security:PolicyOID> </security:ValidationOptions> </security:TrustEngine>
<!-- Trust engine used to evaluate the signature on loaded interfederation metadata. --> <!-- Enable this TrustEngine for interfederation support --> <!-- <security:TrustEngine id="shibboleth.InterfederationMetadataTrustEngine" xsi:type="security:StaticPKIXSignature"> <security:TrustedName>SWITCHaai Interfederation Metadata Signer</security:TrustedName> <security:ValidationInfo id="SWITCHaaiFederationCredentials" xsi:type="security:PKIXFilesystem" verifyDepth="2"> <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate> </security:ValidationInfo> <security:ValidationOptions xsi:type="security:CertPathValidationOptionsType" forceRevocationEnabled="true" policyMappingInhibit="true" anyPolicyInhibit="true"> <security:PolicyOID>2.16.756.1.2.6.8</security:PolicyOID> </security:ValidationOptions> </security:TrustEngine> -->
<!-- DO NOT EDIT BELOW THIS POINT --> <!-- ... -->
2013-08-16 10:43:38,780 - ERROR [org.opensaml.xml.security.x509.CertPathPKIXTrustEvaluator:151] - - PKIX path construction failed for untrusted credential: [subjectName='CN=SWITCHaai Metadata Signer,O=SWITCH,C=CH']: unable to find valid certification path to requested target 2013-08-16 10:43:38,780 - ERROR [org.opensaml.saml2.metadata.provider.SignatureValidationFilter:326] - - Signature trust establishment failed for metadata entry urn:mace:switch.ch:SWITCHaai 2013-08-16 10:43:38,785 - ERROR [org.opensaml.saml2.metadata.provider.AbstractReloadingMetadataProvider:393] - - Error filtering metadata from http://metadata.aai.switch.ch/metadata.switchaai.xmlWe recommend to switch to OpenJDK 1.6 or 1.7 instead. OpenJDK is well-supported on most Linux systems, especially on Debian and RedHat. Please note that Oracle doesn't provide security updates for their JDK 1.6 anymore, so your system might be insecure.
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 -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/attribute-resolver.xml
Make sure to have replaced the salt
of the storedID Connector
with a random string. The random string can be generated with the following command:
openssl rand -base64 36 2>/dev/null
The 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!
In the storedID Connector
, set the MySQL user's password you have set in the section Section 6.2, “MySQL Server Installation and Configuration” instead of the
example password demo
.
<!-- ... --> <!-- ========================================== --> <!-- Attribute Definitions --> <!-- ========================================== --> <!-- ... --> <!-- ========================================== --> <!-- Data Connectors --> <!-- ========================================== --> <!-- Example Static Connector --> <resolver:DataConnector id="staticAttributes" xsi:type="dc:Static"> <dc:Attribute id="swissEduPersonHomeOrganization"> <dc:Value>example.org</dc:Value> </dc:Attribute> <dc:Attribute id="swissEduPersonHomeOrganizationType"> <dc:Value>university</dc:Value> </dc:Attribute> <dc:Attribute id="schacHomeOrganization"> <dc:Value>example.org</dc:Value> </dc:Attribute> <dc:Attribute id="schacHomeOrganizationType"> <dc:Value>urn:schac:homeOrganizationType:int:university</dc:Value> <dc:Value>urn:schac:homeOrganizationType:ch:university</dc:Value> </dc:Attribute> </resolver:DataConnector> <!-- Example Relational Database Connector --> <!-- <resolver:DataConnector id="mySIS" xsi:type="dc:RelationalDatabase"> <dc:ApplicationManagedConnection jdbcDriver="oracle.jdbc.driver.OracleDriver" jdbcURL="jdbc:oracle:thin:@db.example.org:1521:SomeDB" jdbcUserName="myid" jdbcPassword="mypassword" /> <dc:QueryTemplate> <![CDATA[ SELECT * FROM student WHERE gzbtpid = '$requestContext.principalName' ]]> </dc:QueryTemplate> <dc:Column columnName="gzbtpid" attributeID="uid" /> <dc:Column columnName="fqlft" attributeID="gpa" type="Float" /> </resolver:DataConnector> --> <!-- Example LDAP Connector --> <!-- See documentation for further options: https://wiki.shibboleth.net/confluence/display/SHIB2/ResolverLDAPDataConnector --> <resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" ldapURL="" useStartTLS="true" baseDN="
ldap://ldap.example.org
" principal="
ou=people,dc=example,dc=org
" principalCredential="
cn=admin,dc=example,dc=org
"> <dc:FilterTemplate> <![CDATA[ (uid=$requestContext.principalName) ]]> </dc:FilterTemplate> <!-- ResultCache available for IdP versions 2.2 and higher --> <!-- <dc:ResultCache elementTimeToLive="PT10M" maximumCachedElements="1000"/> --> </resolver:DataConnector> <!-- StoredID (persistentID) Connector --> <resolver:DataConnector id="myStoredId" xsi:type="dc:StoredId" generatedAttributeID="persistentID" sourceAttributeID="swissEduPersonUniqueID" salt="
secret-password
"> <resolver:Dependency ref="swissEduPersonUniqueID" /> <dc:ApplicationManagedConnection jdbcDriver="com.mysql.jdbc.Driver" jdbcURL="jdbc:mysql://localhost:3306/shibboleth?autoReconnect=true" jdbcUserName="
put-in-random-string-here
" jdbcPassword="
shibboleth
" /> </resolver:DataConnector> <!-- ========================================== --> <!-- Principal Connectors --> <!-- ========================================== --> <resolver:PrincipalConnector xsi:type="pc:Transient" id="shibTransient" nameIDFormat="urn:mace:shibboleth:1.0:nameIdentifier" /> <resolver:PrincipalConnector xsi:type="pc:Transient" id="saml1Unspec" nameIDFormat="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" /> <resolver:PrincipalConnector xsi:type="pc:Transient" id="saml2Transient" nameIDFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" />
demo
<resolver:PrincipalConnector xsi:type="pc:StoredId" id="saml2Persistent" nameIDFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" storedIdDataConnectorRef="myStoredId" />
</resolver: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 -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/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
has 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 UsernamePassword
login handler of the Shibboleth IdP in
the configuration file handler.xml
(remove the comments around the <LoginHandler> element):
<!--
...
-->
<!-- Login Handlers -->
<!--
<ph:LoginHandler xsi:type="ph:RemoteUser">
<ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod>
</ph:LoginHandler>
-->
<!-- Username/password login handler -->
<ph:LoginHandler xsi:type="ph:UsernamePassword"
jaasConfigurationLocation="file:///opt/shibboleth-idp/conf/login.config">
<ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</ph:AuthenticationMethod>
<ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</ph:AuthenticationMethod>
</ph:LoginHandler>
<!--
...
-->
Edit the /usr/local/src/shibboleth-identityprovider-2.4.4/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#
</param-value>
</init-param>
<load-on-startup>2</load-on-startup>
</servlet>
...
The IPv4 net 130.59.0.0/16
as well as the IPv6 net 2001:620::/48
have been registered for SWITCH.
If you like to use UTF-8 characters within your usernames oder passwords, the following filter needs to be added to your web.xml.
Important: In case you use uApprove, make sure the filter is added before the uApprove filter.
Edit the /usr/local/src/shibboleth-identityprovider-2.4.4/src/main/webapp/WEB-INF/web.xml
:
... <!-- treat user name and password as UTF-8 encoded parameters --> <filter> <filter-name>encoding-filter</filter-name> <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class> <init-param> <param-name>encoding</param-name> <param-value>UTF-8</param-value> </init-param> </filter> <filter-mapping> <filter-name>encoding-filter</filter-name> <url-pattern>/Authn/UserPassword</url-pattern> </filter-mapping> ...
Check whether you have the following line in your login.jsp:
... <%@ page contentType="text/html; charset=UTF-8" %> ...
Customize the login and error pages of the IdP. These are JSP pages that
lie in src/main/webapp/
of the Shibboleth IdP distribution (/usr/local/src/shibboleth-identityprovider-2.4.4
).
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
which is build when redeploying the IdP. (see the section Shibboleth IdP Installation).
cd /usr/local/src/shibboleth-identityprovider-2.4.4/ env JAVA_HOME=/usr/lib/jvm/default-java ./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)
The IdP's logging is configured in the configuration 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.
Our specific logging.xml
file can be downloaded
as follows:
cd /opt/shibboleth-idp/conf/
curl -O https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.4/idp/deployment/logging.xml
In case you prefer to use the existing default logging configuration, we still recommend to limit the archivation of log files to a maximum of 6 months. You can configure this by adapting the appropriate appenders. Look for the <appender> elements and add an additional <maxHistory> element:
<!-- ... --> <appender name="IDP_ACCESS" class="ch.qos.logback.core.rolling.RollingFileAppender"> <!-- ... --> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>/opt/shibboleth-idp/logs/idp-access-%d{yyyy-MM-dd}.log</FileNamePattern><maxHistory>180</maxHistory>
</rollingPolicy> <!-- ... --> </appender> <appender name="IDP_AUDIT" class="ch.qos.logback.core.rolling.RollingFileAppender"> <!-- ... --> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>/opt/shibboleth-idp/logs/idp-audit-%d{yyyy-MM-dd}.log</FileNamePattern><maxHistory>180</maxHistory>
</rollingPolicy> <!-- ... --> </appender> <appender name="IDP_PROCESS" class="ch.qos.logback.core.rolling.RollingFileAppender"> <!-- ... --> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <FileNamePattern>/opt/shibboleth-idp/logs/idp-process-%d{yyyy-MM-dd}.log</FileNamePattern><maxHistory>180</maxHistory>
</rollingPolicy> </appender> <!-- ... -->
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 750 lib war
chmod 750 conf credentials
chmod 775 logs metadata
The IdP's main log file is /opt/shibboleth-idp/logs/idp-process.log
. Errors and warnings can be found there.
To set the log level for debugging, edit the /opt/shibboleth-idp/conf/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.
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/tomcat6/catalina.out.
The AAI Resource Registry collects configuration information about Service Providers and Identity Providers which participate in the "SWITCHaai", and "AAI Test" federations.
Go to the Home Organisation bootstrap page on the AAI Resource Registry. And provide the basic data for the Identity Provider. After SWITCH then has checked and approved the Home Organisation description (may take up to 1-2 business days), you will receive a confirmation email. From that point on, you then should be able to log in on the AAI Resource Registry using an identity provided by your Identity Provider.
After the new Home Organisation has been approved by SWITCH, a custom-tailored attribute-filter.xml
file can be downloaded for the Identity Provider. The correct download URL has to be obtained from the Resource Registry after the Home Organisation was approved by SWITCH.
The attribute-filter.xml
file is configured in the file service.xml
. The file should be configured such that it is downloaded automatically every hour.
A configuration example in service.xml
is shown below.
Instead of example.org
put in your Identity Provider's hostname or domain name in the corresponding tag.
<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//attribute-filter.xml" file="
switchaai/example.org
/opt/shibboleth-idp/conf/attribute-filter.xml"
/> </srv: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.
First, make sure Apache and Tomcat are running.
/etc/init.d/apache2 status
Apache2 is running (pid 555).
If Tomcat has not been started, start it:
/etc/init.d/tomcat6 start
Starting Tomcat servlet engine: tomcat6
Check the Tomcat log in /var/log/tomcat6/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) or the AAI Demo SP (AAITest 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).
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. https://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. https://www.switch.ch/aai/support/certificates/embeddedcerts-requirements/ .
[LdapServerIssues-MicrosoftActiveDirectory] LdapServerIssues-MicrosoftActiveDirectory. https://wiki.shibboleth.net/confluence/display/SHIB2/LdapServerIssues#LdapServerIssues-MicrosoftActiveDirectory .
[JAAS] Java Authentication and Authorization Service (JAAS) Reference Guide. http://docs.oracle.com/javase/1.5.0/docs/guide/security/jaas/JAASRefGuide.html .
[MySQL] MySQL. https://dev.mysql.com .
[ShibbolethWWW] Shibboleth Website. http://shibboleth.net .
[ShibWiki] Shibboleth Wiki. https://wiki.shibboleth.net/confluence/display/SHIB2/ .
[SunJava] Sun Java. http://java.sun.com .
[uapprove] SWITCH AAI uApprove. https://www.switch.ch/aai/uapprove/ .
[VTLdap] Virginia Tech LDAP Module. http://code.google.com/p/vt-middleware/wiki/vtldapJAAS .