Install Shibboleth 2.3 Identity Provider, Tomcat and Apache

Debian 6.0 (squeeze)

AAI Team

(SWITCH)

2013-05-06 08:46:36 +0200


Table of Contents

1. Introduction
2. Overview
3. Prerequisites
4. Java Installation
5. Tomcat Installation
6. Shibboleth IdP Installation
7. X.509 Certificates
8. User Authentication
9. Tomcat Configuration
10. Apache Configuration
11. Shibboleth IdP Configuration
12. AAI Resource Registry
13. Test the installation
14. Maintenance
Glossary
References

1. Introduction

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 6.0 (squeeze) using authentication handlers provided by the Shibboleth IdP. The ShibWiki provides information about other deployments.

Note

Before going through this guide, please consult the Best Current Practices document about operating an IdP.

Note

Refer to the IdP support pages of the SWITCHaai website for more information.

1.1. Conventions used in this guide

The following typographic conventions are used in this guide:

  • file and directory names are formatted like this.

  • file contents
    

    are formatted like this.

  • shell commands
    and output

    are formatted like this.

  • configuration items different from the standard IdP configuration (as available from www.shibboleth.net/downloads/identity-provider)

    are formatted like this.

  • specific values for an installation

    are formatted like this. They have to be adapted for each installation.

2. Overview

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

3. Prerequisites

As indicated in the title, this guide applies to Debian 6.0 (squeeze) 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 0.9.8, Debian Package: openssl. The OpenSSL tools will be used to handle server certificates.

NTP

Debian 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_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)

4. Java Installation

The official Java 6 from Sun as well as OpenJDK 6 are available as a packages in Debian 6.0 (squeeze). We recommend to install OpenJDK on Debian as the maintainers may prioritize it regarding security updates.

4.1. Install the Java 6 JDK package

apt-get install openjdk-6-jre-headless

Java will be installed in /usr/lib/jvm/java-6-openjdk. To avoid conflicts with other Java virtual machines like gcj, deinstalling them is highly suggested. You may also include the following lines in /etc/profile:

JAVA_HOME=/usr/lib/jvm/java-6-openjdk
export JAVA_HOME

5. Tomcat Installation

Apache Tomcat [ApacheTomcat] 6.0.17 or greater is the required version to run the Shibboleth Identity Provider version 2. We haven't tested running an IdP on Tomcat 7 and we don't support that. This section shows how to install the Tomcat 6 Debian package.

For further information about Tomcat, please refer to the Apache Tomcat website.

Note

Concerning Apache Tomcat on Debian/stable, the Debian community unfortunately has a bad track record when it comes to security updates. If you want to keep your system up-to-date with the latest versions of Tomcat 6, consider installing Tomcat from the archives distributed on the Apache Tomcat website.

5.1. Install Tomcat 6

  1. apt-get install tomcat6
    

  2. 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 Internet2 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"
    

  3. 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">

Note

Make sure Tomcat runs with the user "tomcat6", which is the default of the package.

6. Shibboleth IdP Installation

This section describes the installation of the Shibboleth IdP [ShibbolethInternet2] together with a database for persistent identifiers.

6.1. Shibboleth IdP Installation

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

  1. Get Shibboleth IdP 2.3.8 from the Shibboleth website. File signature and SHA1 digest can also be found there.

    cd /usr/local/src
    curl -O http://shibboleth.net/downloads/identity-provider/2.3.8/shibboleth-identityprovider-2.3.8-bin.zip
    

  2. Extract the shibboleth-identityprovider-2.3.8-bin.zip and ensure the installer script install.sh is executable. The archive will be extracted into the directory shibboleth-identityprovider-2.3.8: Please install unzip in case you don't have it.

    apt-get install unzip
    cd /usr/local/src
    unzip shibboleth-identityprovider-2.3.8-bin.zip
    cd shibboleth-identityprovider-2.3.8
    chmod u+x install.sh
    

  3. 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 /usr/local/src/shibboleth-identityprovider-2.3.8
    mkdir /usr/share/tomcat6/endorsed/
    cp ./endorsed/*.jar /usr/share/tomcat6/endorsed/
    

  4. If you use MySQL as a backend for the persistent identifiers, download the MySQL JDBC connector from dev.mysql.com.

    We recommend using the newest version. We have successfully tested with mysql-connector-java-5.1.22.

    Extract it in /usr/local/src/:

    cd /usr/local/src
    unzip mysql-connector-java-5.1.22.zip mysql-connector-java-5.1.22/mysql-connector-java-5.1.22-bin.jar
    

  5. Move the .jar file with the connector classes to the IdP's library directory:

    mv mysql-connector-java-5.1.22/mysql-connector-java-5.1.22-bin.jar \
      /usr/local/src/shibboleth-identityprovider-2.3.8/lib/

  6. 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.3.8/
    env IdPCertLifetime=3 ./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]
    aai-logon.example.org
    A keystore is about to be generated for you. Please enter a password
    that will be used to protect it.
    changeit
    Updating property file: /usr/local/src/shibboleth-identityprovider-2.3.8/src/i
    nstaller/resources/install.properties
    Created dir: /opt/shibboleth-idp
    Created dir: /opt/shibboleth-idp/bin
    [...]
    BUILD SUCCESSFUL
    Total time: 25 seconds
    

  7. Set a symbolic link for your convenience. Link /var/log/shibboleth to the shibboleth-idp log directory:

    ln -s /opt/shibboleth-idp/logs /var/log/shibboleth
    

  8. Set the IDP_HOME environment variable:

    export IDP_HOME=/opt/shibboleth-idp
    

  9. You may also include the following line into your /etc/profile file:

    IDP_HOME=/opt/shibboleth-idp
    export IDP_HOME
    

  10. 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" />
    

6.2. MySQL Server Installation and Configuration

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.

6.2.1. Install MySQL server

  1. Install the Debian 6.0 (squeeze) package for MySQL server version 5.1:

    apt-get install mysql-server-5.1

    With the defaults, the mysql daemon only listens to localhost on IPv4.

  2. Set password for the root user in MySQL:

    /usr/bin/mysqladmin -u root password 'secret-password'

6.2.2. Create users and databases

  1. 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;

  2. 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;
    	   

  3. 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)
    

  4. 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

  5. Check if the user shibboleth has been created with password demo:

    mysql -u shibboleth -p
    Enter password
    demo
    Welcome to the MySQL monitor.  Commands end with ; or \g.
    [...]		
    

6.2.3. Backup the database

Please backup your MySQL DB to ensure that also the persistent IDs that were changed for some reasons are never lost. As long as you store the seed, the persistent IDs can be recomputed. If you are using uApprove, it is also important to backup the uApprove database.

7. X.509 Certificates

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. SWITCHpki allows the use of Subject Alternative Names in certificates. The desired Subject AltNames can be submitted with the certificate request.

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.

8. User Authentication

This section shows how to configure authentication for the Shibboleth IdP authentication handler with a [JAAS] module.

  1. 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="ldaps://ldap.example.org"
          baseDn="ou=people,dc=example,dc=org"
          bindDn="cn=idp-user,dc=example,dc=org"
          bindCredential="password for idp-user";
    };
        
  2. 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="ldap://ldap.example.org"
          tls="true"
          baseDn="ou=people,dc=example,dc=org"
          bindDn="cn=idp-user,dc=example,dc=org"
          bindCredential="password_for_idp-user";
    };
        

    Note

    For the configuration with an Active Directory server, refer to the LdapServerIssues-MicrosoftActiveDirectory page for more information. In particular, consider using port 3268 instead of 389.

  3. 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="ldap://localhost/ou=people,dc=example,dc=org"
          bindDn="cn=idp-user,dc=example,dc=org"
          bindCredential="password_for_idp-user";
    };
        

9. Tomcat Configuration

  1. 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). Also comment out the APR Listener if the APR libraries are not installed:

      <!--  
        <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
      -->
        

10. Apache Configuration

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/.

10.1. mod_ssl

  1. Copy the aai-logon.example.org.key to the directory /etc/ssl/private/ and aai-logon.example.org.crt to the directory /etc/ssl/certs/.

    cp aai-logon.example.org.key /etc/ssl/private/
    cp aai-logon.example.org.crt /etc/ssl/certs/

  2. 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/

  3. To improve your server's security, consider adding the ServerTokens directive in /etc/apache2/conf.d/security.

    ServerTokens Prod
    

  4. Configure the virtual host on aai-logon.example.org for ports 443 and 8443. Create a new configuration file in /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>
    ServerName aai-logon.example.org:443
    ServerAdmin admin@example.org
    
    DocumentRoot /var/www
    
    SSLEngine On
    SSLCipherSuite HIGH:MEDIUM:!ADH
    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>
    ServerName aai-logon.example.org:8443
    ServerAdmin admin@example.org
    
    DocumentRoot /var/www
    
    SSLEngine On
    SSLCipherSuite HIGH:MEDIUM:!ADH
    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>
    

  5. Enable the virtual hosts:

    a2ensite aai-logon
    Enabling site aai-logon.
    Run '/etc/init.d/apache2 reload' to activate new configuration!

  6. Enable the ssl module.

    a2enmod ssl
    Module ssl installed; run /etc/init.d/apache2 force-reload to enable.

  7. 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.

  8. 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
    

  9. Restart the apache httpd server:

    apache2ctl -t
    Syntax OK
    apache2ctl -k restart

11. Shibboleth IdP Configuration

11.1. Configure Shibboleth IdP

11.1.1. IdP Credentials Configuration

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.

  1. 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.

    cd /opt/shibboleth-idp/credentials
    chown root idp.key
    chgrp tomcat6 idp.{key,crt}
    chmod 440 idp.key
    chmod 644 idp.crt

11.1.2. Metadata Trust Configuration

  1. Download the SWITCHaai metadata trust anchor.

    cd /tmp
    curl -O http://ca.aai.switch.ch/SWITCHaaiRootCA.crt.pem

  2. 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

  3. 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

  4. 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.3/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="https://aai-logon.example.org/idp/shibboleth"
                               defaultSigningCredentialRef="IdPCredential" />
        
        <rp:DefaultRelyingParty provider="https://aai-logon.example.org/idp/shibboleth"
                             defaultSigningCredentialRef="IdPCredential"
                             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="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>
    
    
    
        <!-- ========================================== -->
        <!--      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:ResourceBackedMetadataProvider" >
                <metadata:MetadataResource xsi:type="resource:FilesystemResource" file="/opt/shibboleth-idp/metadata/idp-metadata.xml" />
            </metadata:MetadataProvider>
    
            <!-- SWITCHaai production federation metadata provider -->
            <!-- Reads metadata from a URL and store 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>
    
        </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="3">
                <security:Certificate>/opt/shibboleth-idp/credentials/SWITCHaaiRootCA.crt.pem</security:Certificate>
            </security:ValidationInfo>
    	<security:ValidationOptions
    	xsi:type="security:CertPathValidationOptionsType" 
    	forceRevocationEnabled="true" /> 
    
        </security:TrustEngine>
    
        <!-- DO NOT EDIT BELOW THIS POINT -->    
    <!-- 
        ...
    -->   
    

    Note

    If the Identity Provider is behind a firewall or proxy, it is strongly recommended to configure a proxy for the metadata provider. Creating rules with explicit IP addresses to the file is not recommended as the IP addresses may change without prior notice. Information on the configuration options can be found on the page about the File Backed HTTP Metadata Provider.

11.1.3. Attribute Resolution and Filtering Configuration

Note

For the configuration with an Active Directory server, refer to the LdapServerIssues-MicrosoftActiveDirectory page for more information. In particular, consider using 3268 instead of 389.

  1. 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.3/idp/deployment/attribute-resolver.xml

  2. 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!

    <!--
       ...
    -->
    
        <!-- ========================================== -->
        <!--      Attribute Definitions                 -->
        <!-- ========================================== -->
    
    <!--
       ...
    -->
    
        <!-- ========================================== -->
        <!--      Data Connectors                       -->
        <!-- ========================================== -->
    
        <!-- Example Static Connector -->
        <!--
        <resolver:DataConnector id="staticAttributes" xsi:type="dc:Static">
            <dc:Attribute id="eduPersonAffiliation">
                <Value>member</Value>
            </dc:Attribute>
            <dc:Attribute id="eduPersonEntitlement">
                <Value>urn:mace:dir:entitlement:common-lib-terms</Value>
            </dc:Attribute>
            <dc:Attribute id="swissEduPersonHomeOrganization">
                <Value>aai-logon.example.org</Value>
            </dc:Attribute>
          
            <dc:Attribute id="swissEduPersonHomeOrganizationType">
                <Value>others</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 -->
        <resolver:DataConnector id="myLDAP"
            xsi:type="dc:LDAPDirectory"
            ldapURL="ldap://ldap.example.org"
            baseDN="ou=people,dc=example,dc=org"
            principal="cn=admin,dc=example,dc=org"
            principalCredential="secret-password">
            <dc:FilterTemplate>
                <![CDATA[
                    (uid=$requestContext.principalName)
                ]]>
            </dc:FilterTemplate>
        </resolver:DataConnector>
        
        <!-- StoredID (persistentID) Connector -->
        <resolver:DataConnector id="myStoredId"
            xsi:type="dc:StoredId"
            generatedAttributeID="persistentID"
            sourceAttributeID="swissEduPersonUniqueID"
            salt="your random string here">
            <resolver:Dependency ref="swissEduPersonUniqueID" />
            <dc:ApplicationManagedConnection
                jdbcDriver="com.mysql.jdbc.Driver"
                jdbcURL="jdbc:mysql://localhost:3306/shibboleth?autoReconnect=true"
                jdbcUserName="shibboleth"
                jdbcPassword="demo" />
        </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" />
    
        <resolver:PrincipalConnector xsi:type="pc:StoredId" id="saml2Persistent"  
            nameIDFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" 
            storedIdDataConnectorRef="myStoredId" />
    
    </resolver:AttributeResolver>

  3. 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.3/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 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.

11.1.4. Authentication Handler configuration

  1. 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>
    
    <!--
        ...
    -->        
    

11.1.5. IdP Status URL configuration

Edit the /usr/local/src/shibboleth-identityprovider-2.3.8/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.

11.1.6. Internationalization for username/passwords

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.3.8/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" %>
...     

11.1.7. Login and error pages customization

  1. 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-version).

    The following files are customizable:

    login.jsp

    Login page of the Shibboleth Username/Password authentication handler.

    login-error.jsp

    Error page for container managed authentication. (Does not apply for this guide.)

    error.jsp

    Standard error page.

    error-404.jsp

    Custom 404 page for unconfigured locations in the IdP webapp.

    For SWITCHaai specific design templates, refer to SWITCHaai design web pages.

  2. 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.3.8/
    ./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)

11.1.8. Configuration and Log File Permissions

  1. 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

11.2. Shibboleth IdP Log Files

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 /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. 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.

12. AAI Resource Registry

The SWITCHaai Resource Registry collects configuration information about Service Providers and Identity Providers which participate in the federations "SWITCHaai", and "AAI Test".

  1. 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.

  2. 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 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/switchaai/example.org/attribute-filter.xml"
        file="/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).

  3. Restart Tomcat to enable the new settings.

This concludes the Shibboleth IdP installation.

13. Test the 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.

13.1. IdP Status URL

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”).

13.2. Attribute Viewer Service Provider

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).

14. Maintenance

Make sure you keep the software on your IdP system up to date! Here are some hints that may help you to do so:

  1. Sign up to the aai-operations mailing list.

  2. Regularly check for security updates of your operating system. Debians security page lists the latest updates.

  3. Security updates of the Shibboleth software is announced on their security advisories page.

Glossary

AAI

Authentication and Authorization Infrastructure

Back channel connection

System initiated web-service connection to the IdP

CA

Certification authority

CRL

Certificate revocation list

CSR

Certificate signing request

Front channel connection

User initiated browser connection to the IdP

IdP

Identity Provider

PKI

Public key infrastructure

SAML

Security Assertion Markup Language

References

[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 .

[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. http://dev.mysql.com .

[ShibbolethInternet2] Shibboleth Website. http://shibboleth.internet2.edu .

[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 .