End of Life Warning

The Shibboleth IdPv2 series will be End-Of-Life on the 31 July 2016. A complete schedule of the dates can be found here. All deployments should upgrade to V3.

This does not apply to the Service Provider software, which remains supported indefinitely.


Installing a Shibboleth 2.4.x IdP

 Software  Version Provide by  Since
 Shibboleth  2.4.4 A Project of the Internet2 Middleware InitiativeFeb 25th, 2015 
 uApprove  2.6.0 SWITCHaaiNov 28th, 2014

This page is a guide to installing a Shibboleth 2.4.4 and later IdP. This page assumes the IdP would be installed on a vanilla Linux system (typically a virtual machine) and follows from that point on. The IdP will be installed both with the Shibboleth IdP software and the uApprove attribute release approval web application.

This guide is periodically updated as new versions of the software installed become available. This guide is current for IdP 2.4.4 and uApprove 2.6.0. The guide is written with assumption that CentOS/RHEL 6  or above as the OS and Tomcat 6/7 as the web application server.


New Features Included with this guide

  • Enable ECP Support
  • Java Cryptography Extension (JCE) - Oracle JDK only
  • Apache Web Server Hardening Tips
  • New Metadata with SHA256 will be coming soon.(please refer back to this guide)


Before starting the install/upgrade, please note the following changes. 

If you are upgrading from a previous version, please make a backup of your existing IdP installation and install the 2.4.4 release into a clean directory. Configuration files from previous 2.4.x versions can be copied for use with with 2.4.4. Please note the configuration changes below.

 Changes

  •  Shibboleth IdP no longer requires endorsed libraries to be installed into Tomcat.
  • The metadata trust engine configurations has now changed from previous versions.


Securing your server on which you deploy your IdP is essential to maintain the federation trust. This guide does not cover server setup or security.

During the installation there will be a number of tests to confirm previous steps have been performed correctly. These tests are tagged with the icon to the left. For a successful installation please ensure all tests are completed before moving to the next step. If you have difficulty completing a test please contact the AAF support desk support@aaf.edu.au for assistance.

 

Contents

  1. 1 Modifications to Identity Management system
    1. 1.1 Preliminaries
      1. 1.1.1 System firewall configuration
    2. 1.2 Bootstrapping the VM
      1. 1.2.1 Install packages
      2. 1.2.2 For Centos 7
      3. 1.2.3 Local configuration
    3. 1.3 Basic Shibboleth IdP and uApprove installation
      1. 1.3.1 Rationale and planning
      2. 1.3.2 Basic Shibboleth Installation
      3. 1.3.3 Configure Tomcat and deploy the IdP WAR
  2. 2 Service Temporarily Unavailable
    1. 2.1 Basic Shibboleth Configuration
      1. 2.1.1 Load the Federation Metadata
      2. 2.1.2 Configure IdP with a login screen
      3. 2.1.3 LDAP connections with TLS/SSL with an untrusted certificate
      4. 2.1.4 uApprove
      5. 2.1.5 Start Tomcat
      6. 2.1.6 Advanced uApprove Deployment
      7. 2.1.7 Additional Information on uApprove
    2. 2.2 Configure Attribute Resolver
      1. 2.2.1 Link your Attribute Resolver to your LDAP server
      2. 2.2.2 Link existing attributes
      3. 2.2.3 Define static attributes
      4. 2.2.4 Define scripted attributes
      5. 2.2.5 Define sharedToken
      6. 2.2.6 eduPersonTargetedID
    3. 2.3 Joining the federation
      1. 2.3.1 Register your IdP
      2. 2.3.2 Setting up Automated Attribute release
      3. 2.3.3 Automating attribute release for Shibboleth 2 IdP
      4. 2.3.4 Attribute name checks
      5. 2.3.5 Logging into the Federation Registry
      6. 2.3.6 Becoming an Identity Provider Administrator 
      7. 2.3.7 Registering SAML1.x Endpoints
      8. 2.3.8 Monitoring your IdP
      9. 2.3.9 Setting the Automatic Attribute Release Flag
    4. 2.4 Advanced IdP Configuration
      1. 2.4.1 Enabling automatic reload
      2. 2.4.2 Enabling ECP support
    5. 2.5 ECP Overview
      1. 2.5.1 Direct vs. Delegated Authentication
      2. 2.5.2 Current AAF support
    6. 2.6 Enabling ECP support in your Identity Provider
      1. 2.6.1 Technical Prerequisites
      2. 2.6.2 Internal IdP configuration
      3. 2.6.3 Authenticating ECP requests
      4. 2.6.4 Alternative options
      5. 2.6.5 Verify configuration
      6. 2.6.6 Registering the change in Federation Registry
    7. 2.7 End to End testing
    8. 2.8 Customization and Branding
      1. 2.8.1 Customizing and branding IdP login screen
      2. 2.8.2 Using the AAF logo
      3. 2.8.3 Customizing and branding uApprove
      4. 2.8.4 Friendly attribute names
    9. 2.9 Testing
    10. 2.10 Summary


Modifications to Identity Management system

Your Identity Management System (IdMS) will probably already have most of the attributes required for by the federation, or will have enough information to synthesize the attribute values on the fly inside the IdP. However, for some attributes, the IdMS might not have enough information. The following information should be considered for addition to your IdMS:
  • eduPersonEntitlement: The eduPersonEntitlement attribute is a storage container for values representing privileges to access resources within the federation. It is a multi-valued string attribute. The values will have the form of a URI with specific values that are yet to be defined.

eduPersonEntitlement

Origin/ObjectClass: 
eduPerson [eduPerson]
OID:  1.3.6.1.4.1.5923.1.1.1.7 
SAML attribute name: urn:mace:dir:attribute-def:eduPersonEntitlement 
LDAP syntax:  directoryString [1.3.6.1.4.1.1466.115.121.1.15] 
Number of values:  Multiple 
Example values:  urn:mace:washington.edu:confocalMicroscope 
http://publisher.example.com/contract/GL123
  • auEduPersonSharedToken: The auEduPersonSharedToken uniquely identifies users across the whole federation when accessing certain resources, particularly within the computational grid and data grid. The values should be opaque, non-reassignable, persistent and transferrable when a user moves between institutions. Even though the values are typically created as hash-values on first use, they MUST be stored and each institution must be ready to accept values users already have when coming from another institution. The attribute can be stored in either the IdMS directly (preferred), or in a database. 

auEduPersonSharedToken

Origin/ObjectClass:  auEduPerson 
OID:  1.3.6.1.4.1.27856.1.2.5 
SAML attribute name:   urn:mace:federation.org.au:attribute:auEduPersonSharedToken 
LDAP syntax:  directoryString [1.3.6.1.4.1.27856.1.2.5] 
Number of values:  Single 
Example values:  ZsiAvfxa0BXULgcz7QXknbGtfxk 


  • eduPersonAssurance: This attribute represents the Levels of Assurance. Either add the attribute into the IdMS directly, or start collecting enough information to synthesize the values later in a scripted attribute definition (like done for Affiliation below).  

eduPersonAssurance

Origin/ObjectClass:  eduPerson 
OID:  1.3.6.1.4.1.5923.1.1.1.11 
SAML attribute name:  urn:oid:1.3.6.1.4.1.5923.1.1.1.11 
LDAP syntax:   directoryString [1.3.6.1.4.1.1466.115.121.1.15] 
Number of values:  multiple 
Example values:  See AAF IdentityLoA Vocabulary 



Preliminaries

System firewall configuration

If you are implementing a local firewall on the server using iptables, you need to permit incoming traffic to ports 80, 443 and 8443. The following configuration will apply.

For CentOS 6, Redhat 6

  • Edit /etc/sysconfig/iptables and add rules to permit incoming traffic to ports 80, 443, and 8443;
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 80 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 443 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 8443 -j ACCEPT

  • Restart iptables:

$ service iptables restart



For CentOS 7/RHEL7,
  • Ensure firewalld is installed this can be checked by running the following command as a root 

$ firewall-cmd --state
running


  • Add firewall rules appropriate for and Identity Provider; Services http and https and port 8443/tcp.
           

$ firewall-cmd --add-service https --permanent

$ firewall-cmd --add-service http --permanent

$ firewall-cmd --add-port=8443/tcp --permanent


  • Reload and view the firewall rules

$ firewall-cmd --reload

$ firewall-cmd --list-all
public (default, active)
  interfaces: ...
  sources: 
  services: dhcpv6-client http https ssh
  ports: 8443/tcp
  masquerade: no
  forward-ports: 
  icmp-blocks:
  rich rules:



Bootstrapping the VM

We assume you are starting with vanilla install of either CentOS or RHEL 6 /7 



Install packages

Base packages

  • Apache with mod_ssl, unzip and wget
$ yum install httpd mod_ssl unzip wget

Java 

The AAF recommends using the version 1.7 of the Java OpenJDK installed using YUM. 

Note: Version 1.8 of the OpenJDK is available but there are a number of changes that would require modifications to your IdP configuration that are beyond the scope of this document. See the Shibboleth document IdP Java 1.8 for more details.
  •       Install the JDK Package

$ yum install java-1.7.0-openjdk-devel

Tomcat

Tomcat will be installed from a tarball from the Apache Tomcat site instead of installing from the YUM repository.

  • Download the latest Tomcat 7 from the Apache Tomcat download site. At writing version 7.0.59 was the latest version. Ensure the sha1sum of the downloaded file equals sha1 value available on the Tomcat download site. 
  • Unpack Tomcat into /opt and create a symbolic link from /opt/tomcat to the unpacked tomcat directory.

$ cp apache-tomcat-7.0.59.zip /opt

$ cd /opt

$ unzip apache-tomcat-7.0.59.zip 

$ ln -s apache-tomcat-7.0.59 tomcat

  • Remove unnecessary files and applications from Tomcat.

$ cd /opt/tomcat/webapps

$ rm -rf *

  • Add a tomcat user and group to your system. This account will run the tomcat instance. Change the ownership of the all of Tomcat files and directories.
$ useradd tomcat -b /opt/tomcat

$ chown -R tomcat.tomcat /opt/apache-tomcat-7.0.59

Create the /opt/tomcat/bin/setenv.sh with the following content.
  • Ensure that Tomcat runs with sufficient memory. 
  • Ensure that Tomcat can load the AAF metadata and attribute filter.
JAVA_OPTS="${JAVA_OPTS} -Xms256m -Xmx1024m -Djdk.tls.trustNameService=true"

  •  Ensure the start up files are owned by the tomcat user and are executable.
$ chown tomcat.tomcat /opt/tomcat/bin/setenv.sh

$ chmod 644 /opt/tomcat/bin/setenv.sh

$ chmod 755 /opt/tomcat/bin/catalina.sh

$ chmod 744 /opt/tomcat/bin/startup.sh

$ chmod 744 /opt/tomcat/bin/shutdown.sh

  • Add a Tomcat start-up script to start and stop the Tomcat server.
For Centos 6

Create the file /etc/init.d/tomcat with the following
 
#!/bin/bash
#description:Tomcat Start, Stop and Restart
#process name : tomcat
#chkconfig: 345 20 80 
#declare Java Home
JAVA_HOME=/usr/lib/jvm/java 
export JAVA_HOME
PATH=$JAVA_HOME/bin:$PATH
export PATH
CATALINA_HOME=/opt/tomcat
TOMCAT_USER=tomcat
case $1 in
    start)

       /bin/su $TOMCAT_USER $CATALINA_HOME/bin/startup.sh

        ;; 

    stop)

        /bin/su $TOMCAT_USER $CATALINA_HOME/bin/shutdown.sh 

        ;; 

    restart)

        /bin/su $TOMCAT_USER $CATALINA_HOME/bin/shutdown.sh

        /bin/su $TOMCAT_USER $CATALINA_HOME/bin/startup.sh

        ;; 

esac

exit 0


For Centos 7

Create the file /lib/systemd/system/tomcat.service with the following content. This file should have an owner of root with access permissions of 644.

[Unit]
  Description=Tomcat webserver
  After=syslog.target network.target

[Service]
  Type=forking
  User=tomcat
  ExecStart=/opt/tomcat/bin/startup.sh
  ExecStop=/opt/tomcat/bin/shutdown.sh
  SuccessExitStatus=143

[Install]
  WantedBy=multi-user.target
  • Ensure Tomcat starts whenever the system is re-booted.
Centos 6 version

    $ chmod 755 /etc/init.d/tomcat
    $ chkconfig --add tomcat
    $ chkconfig tomcat on

Centos 7 version

    $ systemctl enable tomcat


Java Cryptography Extension (JCE) 

Note: This step is only required if you are using the ORACLE JDK; it is not required for the OpenJDK.
  • Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files
    • Download the JCE for the version of Java you have installed from the Oracle web site: http://www.oracle.com/technetwork/java/javase/downloads/index.html.
  • Unzip the file and replace two .jar
    • Overwrite local_policy.jar and US_export_policy.jar
    • Try the directory: /usr/lib/jvm/java/jre/lib/security
$ unzip UnlimitedJCEPolicyJDK7.zip
$ cd UnlimitedJCEPolicy
$ cp local_policy.jar /usr/lib/jvm/java-1.7.0-openjdk-1.7.0.75-2.5.4.2.el7_0.x86_64/jre/lib/security
$ cp US_export_policy.jar /usr/lib/jvm/java-1.7.0-openjdk-1.7.0.75-2.5.4.2.el7_0.x86_64/jre/lib/security

Local Database

For Centos 6 / Redhat 6 use MySQL
  • MySQL (needed for storing sharedToken values and uApprove attribute release approvals)
MySQL is not strictly required, and an alternative database system may be used if already available on site. This guide is based on using the local MYSQL database on the IdP server. if you wish to use an external database please ensure that it has been properly secured.We recommend that you speak to your database administrator about ensuring the database is secure. Whether the IdP database is local or external to the IdP server, it should be behind a firewall to secure it from the public internet and access should require the use of a strong secret( eg: long random password). Just use the corresponding JDBC drivers for the alternative database.
$ yum install mysql mysql-server
$ service mysqld start




 For CentOS 7 / Redhat 7 use MariaDB
  • MariaDB is an enhanced, drop-in replacement for MySQL.

$ yum install mariadb mariadb-server

$ systemctl start mariadb


 Secure your Database

  • Run the post install MySQL secure installation script. This will allow you to set the root password as well as apply other security settings. This applies to both MySQL and MariaDB.
$ /usr/bin/mysql_secure_installation

   

 Time Synchronization

  • Install NTP (if time synchronization is to be done inside the VM)
$ yum install ntp

Local configuration

  • Configure NTP: time synchronisation is crucial for the Shibboleth IdP to correctly interact with Service Providers in the federation. Please gather beforehand the hostname or IP address of the time server provided within your organisation. Further on, we'll assume it's ntp.institution.domain.edu.au. If your organisation is not providing one, you may use an external source (including the default servers listed in /etc/ntp.conf), but make sure your firewall allows the NTP traffic through (outgoing UDP port 123 traffic + reply packets).
    • Do a one-off synchronization
ntpdate -s ntp.institution.domain.edu.au

    • Edit /etc/ntp.conf and:
      • Comment out local server (server 127.127.1.0 and fudge 127.127.1.0)
      • Comment out CentOS servers (all lines starting with server)
      • Add the local time server:
server ntp.institution.domain.edu.au

    • Make ntpd start on system startup

CentOS 6 / Redhat 6

chkconfig ntpd on

CentOS 7 / Redhat 7

systemctl enable ntpd

    • Start ntpd now

CentOS 6 / Redhat 6

service ntpd start

CentOS 7 / Redhat 7

systemctl start ntpd

    • Check ntpd is running and synchronizing: run
ntpdc -p

  • Disable SELinux: the Apache LDAP module does not work with SELinux.  SELinux would not allow the module to open outgoing TCP connections.
    • Disable SELinux now:

CentOS 6 / Redhat 6

echo 0 > /selinux/enforce

CentOS 7 / Redhat 7

setenforce 0

    • And for future restarts, edit /etc/selinux/config and change:
SELINUX=permissive



Basic Shibboleth IdP and uApprove installation

Rationale and planning

From the very beginning, we will install the Shibboleth IdP:
  • as a WAR (web application) file managed by Tomcat
  • with uApprove integrated into the web application
  • with a Tomcat login screen used for authentication
Having done these steps early in the installation is strongly  recommended to prevent insidious issues that are difficult to debug in the future.

The installation paths will be (as close to defaults as possible, putting all IdP files under /opt)
  • IDP_HOME - /opt/shibboleth-idp (default)
  • Tomcat home: /opt/$TOMCAT_NAME (where Tomcat web applications and common files live)
Your IdP hostname will be idp.institution.domain.edu.au

Your scope, home organization name and security domain will be institution.domain.edu.au

Your IdP entityId will be https://idp.institution.domain.edu.au/idp/shibboleth

  • The Shibboleth IdP installation directory (from where Shibboleth IdP software is installed) will be /home/shibsrc/shibboleth-identityprovider-<version> - and the name of the directory will be stored in SHIB_INST_HOME (here, we assume version is 2.4.4)
  • The uApprove installation directory will be /home/shibsrc/uApprove-<version> and the name of the directory will be stored in UAPPROVE_INST_HOME (here, we assume version is 2.6.0)
  • Configure the corresponding environment variables: create /etc/profile.d/shib.sh with the following content and make the file executable by all users:

/etc/profile.d/shib.sh

IDP_VERSION="2.4.4"

UAPPROVE_VERSION="2.6.0"
 
SHIB_HOME=/opt/shibboleth-idp
 
SHIB_INST_HOME=/home/shibsrc/shibboleth-identityprovider-$IDP_VERSION
 
IDP_HOME=/opt/shibboleth-idp
 
JAVA_HOME=/usr/lib/jvm/java

TOMCAT_NAME=tomcat
 
TOMCAT_HOME=/opt/$TOMCAT_NAME
 
UAPPROVE_INSTALL=/home/shibsrc/uApprove-$UAPPROVE_VERSION

export IDP_VERSION UAPPROVE_VERSION SHIB_HOME SHIB_INST_HOME IDP_HOME JAVA_HOME TOMCAT_HOME UAPPROVE_INSTALL


  • Load the environment variables into your current environment.
$ source /etc/profile.d/shib.sh

  • Create a shibsrc user to retain the shibboleth IdP installation files. These will be needed when upgrading your IdP software.
$ useradd shibsrc



Basic Shibboleth Installation

  • Create an installation directory and download Shibboleth
$ cd /home/shibsrc
$ wget http://www.shibboleth.net/downloads/identity-provider/${IDP_VERSION}/shibboleth-identityprovider-${IDP_VERSION}-bin.zip

$ wget http://www.shibboleth.net/downloads/identity-provider/${IDP_VERSION}/shibboleth-identityprovider-${IDP_VERSION}-bin.zip.sha1

$ sha1sum shibboleth-identityprovider-${IDP_VERSION}-bin.zip

# Compare the result SHA1 values with that provided in the .sha1 file. Only continue if they are equal.

$ unzip shibboleth-identityprovider-${IDP_VERSION}-bin.zip

$ cd $SHIB_INST_HOME
  • Invoke installer
sh ./install.sh
  • When prompted, give the following non-default answers:
    • FQDN is the hostname assigned to your IdP, typically idp.institution.domain.edu.au
    • Keystore password would be used to create the java keystore containing the back-channel certificates. As the private key will be also stored on disk in an unencrypted X509 key file, there is no need to choose a secure keystore password...
FQDN: idp.institution.domain.edu.au
Keystore: changeit

Important

When re-running the installer in the future (you'll be asked to do so further on in this guide), you'll be asked whether to overwrite the configuration files. 
It is important you answer NO to that question - otherwise, all modifications made to the configuration files will be lost.
  • This installs the Shibboleth IdP web application into /opt/shibboleth-idp/war/idp.war

Configure Tomcat and deploy the IdP WAR

Context Deployment Fragment

  • Create /opt/$TOMCAT_NAME/conf/Catalina/localhost/idp.xml with the following content:

idp.xml

      <Context docBase="/opt/shibboleth-idp/war/idp.war"
               privileged="true"
               antiResourceLocking="false"
               antiJARLocking="false"
               unpackWAR="false"
               swallowOutput="true" />


Connectors

  • Connectors in /opt/$TOMCAT_NAME/conf/server.xml, if not already defined, define a new AJP connector at port 8009

Note: Tomcat already has this connector defined, but in an insecure way that would be opening the connector to outside connections as well. Comment the original definition out and instead put this definition in.

<Connector port="8009"
           address="127.0.0.1"
           enableLookups="false"
           redirectPort="8443"
           protocol="AJP/1.3"
           tomcatAuthentication="false" />

  • Comment out the existing http connector defined for port 8080:
<!--
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
-->

 

File and Directory permissions

  • Make all files under /opt/shibboleth-idp owned by Tomcat
chown -R tomcat:tomcat $IDP_HOME


Tomcat start-up test

  • At this point Tomcat should start without any errors and the un-configured IdP should also start, but will not be able to process logins at this point.  It might take some time for Tomcat to deploy the web application the first time you start it.

CentOS 6 / Redhat 6

service $TOMCAT_NAME start

CentOS 7 / Redhat 7

systemctl start $TOMCAT_NAME


  • To verify there are no errors, you should check the following log files:
Tomcat logs
    • /opt/$TOMCAT_NAME/logs/catalina.out 
If Tomcat fails to start, or the IdP application fails to start, then the catalina.out file will likely identify the cause of the problem(s).

IdP log
    • $IDP_HOME/logs/idp-process.log

     ON Success

    • The will only be INFO notices in catalina.out
    • The final line of the IdP log file idp-process.log will look similar to the following;
INFO [edu.internet2.middleware.shibboleth.common.config.BaseService:180] - shibboleth.HandlerManager service loaded new configuration

Common issues

Invalid Hostname

The following errors are found in the catalina.out log file.

-ERROR in ch.qos.logback.core.util.ContextUtil@48fe5d98 - Failed to get local hostname java.net.UnknownHostException: idp-x: idp-x: Name or service not known

 - ERROR [net.sf.ehcache.Cache:145] - Unable to set localhost. This prevents creation of a GUID. Cause was: idp-x: idp-x: Name or service not known
java.net.UnknownHostException: idp-x: idp-x: Name or service not known

-ERROR in ch.qos.logback.core.util.ContextUtil@1b5ac06e - Failed to get local hostname java.net.UnknownHostException: idp-x: idp-x: Name or service not known at java.net.UnknownHostException: idp-x: idp-x: Name or service not known

These errors occurred because the servers hostname have the value "idp-x".

The systems hostname is incorrectly defined and does not refer to a host name that is defined as a Domain name. Use the hostname command to verify what the server's name is. The name must resolve to a DNS entry.

hostname

To resolve use the hostname to set a valid value

hostname idp.institution.domain.edu.au

Permission denied

The following error is found in the catalina.out log file.

-ERROR in ch.qos.logback.core.rolling.RollingFileAppender[IDP_ACCESS] - openFile(/opt/shibboleth-idp/logs/idp-access.log,true) call failed. java.io.FileNotFoundException: /opt/shibboleth-idp/logs/idp-access.log (Permission denied)

The permissions on the IdP configuration files does not allow the Tomcat server the appropriate access. Refer to the "File and Directory permissions" section above to correct.

 



Configure Apache

Configuration

Apache needs to be configured to:
  • Listen on port 443 - this is done via a separate configuration file idp.conf  (bypassing parts of the default configuration in ssl.conf)

  • Listen on port  8443 - this allows Shibboleth IdPs and SPs may communicate directly, as opposed to sending messages via the user's browser, during certain operations (Attribute Query, Artifact Resolution, and Logout).

  • Apply some basic Apache server hardening options; Edit the apache configure file (/etc/httpd/conf/httpd.conf) and and set the following configurations values;
  • To configure the virtual host for ports 443, download the files attached to this page into idp.conf the Apache configuration directory /etc/httpd/conf.d
 
    • In the files, replace all occurrences of  idp.institute.edu.au with the hostname of your IdP
 
    • In idp.conf, configure the SSL VirtualHost to use the commercial certificate issued for your IdP by your CA, modify the file paths in the following configuration settings to point to your Certificate, Key and Key Chain for your certificate.
Note: The key and CABUNDLE will be provided by your CA.

SSLCertificateFile /etc/pki/tls/certs/idp.crt

SSLCertificateKeyFile /etc/pki/tls/private/idp.key

SSLCertificateChainFile /etc/pki/tls/certs/CABUNDLE.CRT

 

To begin make a backup of your ssl.conf

cd /etc/httpd/conf.d/
cp ssl.conf ssl.conf.dist

  • Configured to disable SSL session cache to work around a bug. Edit your ssl.conf,
    • Disable SSL session cache by commenting out the default SSLSessionCache directive and instead setting the cache to none:
#SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
SSLSessionCache         none

    • Delete the whole default <VirtualHost> section from ssl.conf (the definitions in idp.conf will be used instead).
    • Delete the entry for Listen 443 (because we now have the directive in idp.conf).

Testing Apache

  • Start Apache.

CentOS 6 / Redhat 6

service httpd start

CentOS 7 / Redhat 7

systemctl start httpd


  • Navigate to the IdP login page https://idp.institute.domain.edu.au/idp/Authn/UserPassword
      On Success you should receive a page similar to the following.


Common issues

Service Temporarily Unavailable

The web server responds with a Service Temporarily Unavailable generally means that the Tomcat server is not running or is incorrectly configured.
  •  Check that Tomcat is running, the following commands will tell you if tomcat is running or not.

CentOS 6 / Redhat 6

service $TOMCAT_NAME status

Will respond with "tomcat is stopped" if tomcat is not running.

CentOS 7 / Redhat 7

systemctl status $TOMCAT_NAME

Will respond with a brief report with "Active: inactive (dead)" on the third line if tomcat is not running.

  • Check that Tomcat is listening on port 8009, that is used by Apache to proxy requests

CentOS 6 / Redhat 6

netstat -a | grep 8009

Will respond with the following output if tomcat running and configured correctly:

tcp   0   0 localhost:8009     *:*          LISTEN

CentOS 7 / Redhat 7

ss -a | grep 8009

Will respond with the following output if tomcat running and configured correctly:

tcp    LISTEN     0      100       ::ffff:127.0.0.1:8009                 :::*




Review the section on configuring Tomcat above.
 

Basic Shibboleth Configuration

Load the Federation Metadata

  • Configure the IdP to load the federation metadata in $IDP_HOME/conf/relying-party.xml by adding the following snippets into the Chaining MetadataProvider.
Note: There are two versions of the AAF metadata.  This installation uses the Complete Metadata. This version of the metadata will continue to expand and grow as new features become available. For more information on the other version of metadata see the knowledge base article "AAF Metadata".

The metadata site itself is protected with an AUSCert SSL certificate and should only be accessed over HTTPS.
<!-- AAF Federation metadata -->
<metadata:MetadataProvider id="AAF" xsi:type="metadata:FileBackedHTTPMetadataProvider"
                          metadataURL="https://ds.[test.]aaf.edu.au/distribution/metadata/metadata.aaf.signed.complete.xml"
                          backingFile="/opt/shibboleth-idp/metadata/AAF-metadata.xml">
            <metadata:MetadataFilter xsi:type="metadata:ChainingFilter">
                <metadata:MetadataFilter xsi:type="metadata:RequiredValidUntil"
                                maxValidityInterval="P10D" />
                <metadata:MetadataFilter xsi:type="metadata:SignatureValidation"
                                trustEngineRef="shibboleth.MetadataTrustEngine"
                                requireSignedMetadata="true" />
                <metadata:MetadataFilter xsi:type="metadata:EntityRoleWhiteList">
                    <metadata:RetainedRole>samlmd:SPSSODescriptor</metadata:RetainedRole>
                </metadata:MetadataFilter>
                <metadata:MetadataFilter xsi:type="metadata:SchemaValidation"/>
            </metadata:MetadataFilter>
        </metadata:MetadataProvider>

Important: AAF Test environment metadata is being loaded. Remove '.test' from the Metadata URL to use the AAF Production version.

  • The AAF metadata should have its signature verified.  Add the trust engine definition as well (or uncomment and configure it further down in the file):
<!-- Trust engine used to evaluate the signature on loaded AAF metadata. --> 

<security:TrustEngine xsi:type="security:StaticExplicitKeySignature" id="shibboleth.MetadataTrustEngine">    
   <security:Credential xsi:type="X509Filesystem" xmlns="urn:mace:shibboleth:2.0:security" id="AAFCredentials">     
    <security:Certificate>/opt/shibboleth-idp/credentials/aaf-metadata-cert.pem</security:Certificate>       
  </security:Credential>    
</security:TrustEngine>



  • This definition is refers to a certificate used to verify the signature.  Store the certificate in /opt/shibboleth-idp/credentials
cd /opt/shibboleth-idp/credentials

# For the AAF Test Environment
wget https://ds.test.aaf.edu.au/distribution/metadata/metadata-cert.pem -O aaf-metadata-cert.pem

# For the AAF Production Environment
wget  https://ds.aaf.edu.au/distribution/metadata/metadata-cert.pem -O aaf-metadata-cert.pem

  • Note that the relying-party.xml file also refers to:
    • Our own metadata generated for the IdP in /opt/shibboleth-idp/metadata/idp-metadata.xml
    • Our own credentials stored in /opt/shibboleth-idp/credentials/idp.crt and /opt/shibboleth-idp/credentials/idp.key
    • Our own entityId (also stored in the self-metadata in /opt/shibboleth-idp/metadata/idp-metadata.xml

Test Metadata Loading

  • Restart Tomcat to force the IdP to download and consume the AAF metadata.

CentOS 6 / Redhat 6

service $TOMCAT_NAME restart

CentOS 7 / Redhat 7

systemctl restart $TOMCAT_NAME


  • Check that Tomcat restarted with no problems.  Note that it might take some time for Tomcat to download the metadata files.  Evidence of this occurring will be found by
    • The creation or updating of the AAF metadata file /opt/shibboleth-idp/metadata/AAF-metadata.xml
    • Logs in the log file /opt/shibboleth-idp/logs/idp-process.log




Configure IdP with a login screen

It is recommended that you have a site-branded login screen, which makes it easier for users to recognize the proper login screen, and may be necessary for deploying site-wide login and password-handling policies. This section enables a form based login page. Details on how to customise and brand the login screen and associated pages is described in more detail in Customisation and Branding section below.

For deploying a login screen for a Shibboleth 2.x IdP:
  • Edit $IDP_HOME/conf/handler.xml and
    • Uncomment Username/Password Login Handler
Note: The AAF core attribute AuthenticationMethod is populated from the value provided in the ph:AuthenticationMethod below.
<!--  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:LoginHandler>


    • Comment out RemoteUser LoginHandler
<!-- Login Handlers -->
<!--
    <ph:LoginHandler xsi:type="ph:RemoteUser">
        <ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</ph:AuthenticationMethod>
    </ph:LoginHandler>
-->

  • Optionally, customize session duration (default 30 minutes): add the following attribute (with the duration either in minutes or using the PT notation) to the UsernamePassword login handler: (Example extends session inactivity duration to 1 hour).
authenticationDuration="PT1H0M0.000S"

  • Edit $IDP_HOME/conf/login.config and provide details for the LDAP server (uncomment and configure LdapLoginModule section). You may have to provide more attributes than what's in the default commented-out section: namely subtreeSearch="true" and serviceUser and serviceCredential with login details for a privileged account (to look up users). 
   edu.vt.middleware.ldap.jaas.LdapLoginModule required
      ldapUrl="ldap://ldap.institute.domain.edu.au"
      base="ou=people,dc=institute,dc=domain,dc=edu,dc=au"
      serviceUser="<ldap user DN here>"
      serviceCredential="<ldap password here>"
      subtreeSearch="true"
      ssl="false"
      tls="false"
      userFilter="uid={0}";

  • Ensure form-based auth managed by the container is enabled. Edit $SHIB_INST_HOME/src/main/webapp/WEB-INF/web.xml and uncomment the Form based login-config.
    <!-- Uncomment if you want form-based auth managed by the container -->
    <login-config> <auth-method>FORM</auth-method> <realm-name>IdP Password Authentication</realm-name> <form-login-config>
        <form-login-page>/login.jsp</form-login-page> <form-error-page>/login-error.jsp</form-error-page> </form-login-config> </login-config>


  • Rebuild and redeploy the WAR file afterwards by re-running the installer:
cd $SHIB_INST_HOME
sh ./install.sh

LDAP connections with TLS/SSL with an untrusted certificate

The connection to the LDAP server can be established either over plain LDAP (no cryptographic protection), or over LDAP with either TLS/SSL. Some LDAP servers may be configured to only accept a bind operation over an cryptographically protected channel (TLS or SSL). Some LDAP servers might however be using a self-signed certificate - or a certificate issued by a CA not trusted by the default Java trust store. In that case, it is necessary to add the CA certificate issuing the LDAP server certificate (or alternatively the LDAP server cerificate itself) to the Java keystore.

  • Get the CA certificate and save it into /opt/shibboleth-idp/credentials/local-ca.crt (picking an appropriate file name)
  • Make a copy of the default Java key store:
cp $JAVA_HOME/jre/lib/security/cacerts $JAVA_HOME/jre/lib/security/cacerts.orig

  • Import the CA certificate into the Java keystore:
keytool -import -trustcacerts -alias "Local-CA" -file /opt/shibboleth-idp/credentials/_local-ca_.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

  • Change the alias to something descriptive for the local CA
  • You will get prompted for the passphrase protecting the Java keystore. The default password is "changeit" (literally).
    1. only works for TLS and not SSL
    2. only works for the LDAP resolver itself, but not for the login screen connector in login.conf

Verify the LDAP connection

To verify that the connectivity to your LDAP server works you can again point your web browser at the IdP login page https://idp.institute.domain.edu.au/idp/Authn/UserPassword.

To test the LDAP connection, attempt to login with a known username and password. If you enter the correct username and password, the IdP will respond with an error, "An error occurred while processing your request". This indicates that the authentication to the LDAP server has been successful and you are ready to move to the next stage. (This Error can be ignored at this time)

If you continue to receive "
Login has failed. Double-check your username and password." even though you are entering a correct username and password, check the serviceUser and serviceCredential in login.config.

If the response is taking a long time before returning 
"Login has failed. Double-check your username and password.", you should check the connection options, host, ssl, tls, etc. values in login.config. You should also check that there are no firewalls blocking packets between the IdP server and the LDAP server.  You should also look in the idp-process.log file for any LDAP connection errors.


uApprove

Rule 8.4 from the AAF Federation Rules states that "Identity Providers may only release Attributes to a Service Provider, or another Identity Provider, with the permission of the End User." The AAF recommends IdPs install uApprove to provide a mechanism for users to provide their consent to the release of personal attributes.

The uApprove application will step in the first time the user logs into a service. It will ask the user for permission to release the required (and desired) attributes to the service. The user will be asked again if the set of attributes released to the service changes, or if the values previously released change. The user also has the option of giving a global consent which gives their permission to release any attributes to any service the user accesses in the future. The global consent can be later revoked (via the Reset-approvals feature) and can also be completely disabled in the system-wide configuration (if the institution decided their users shouldn't be allowed to give global consent).

More information about uApprove, as well as links for downloading the software, can be found at http://www.switch.ch/aai/support/tools/uApprove.html

As uApprove plugs into the IdP, the version of uApprove must be matched to be compatible with the version of the IdP. The most recent version of uApprove 2.6.0 is compatible with IdP 2.4.4, which is the most recent stable version of Shibboleth.

The following instructions are closely based on the uApprove 2.6.0 installation manual, http://www.switch.ch/aai/downloads/uApprove-manual/.

You should confirm at the uApprove website that 2.6.0 is still the most recent version.  If not, you should refer to the new version's installation manual for updated instructions.

uApprove can store the approval information in either a SQL database, or in a flat file. Storing the information in a SQL database is more scalable, and it also allows users to revoke consent already given. This guide documents installing uApprove configured to use a local MySQL database on the IdP server.Please refer to the uApprove installation manual for other alternatives (such as connecting to an external database).



Install uApprove

  • Download the uApprove binary distribution, unpack it into /home/shibsrc.
$ cd /home/shibsrc
$ wget  https://forge.switch.ch/redmine/attachments/download/1823/uApprove-2.6.0.zip

$ unzip uApprove-${UAPPROVE_VERSION}.zip


Library Installation

Copy the libraries to the IdPs library directory:

cp $UAPPROVE_INSTALL/lib/*.jar $SHIB_INST_HOME/lib

cp $UAPPROVE_INSTALL/lib/jdbc/*.jar $SHIB_INST_HOME/lib

Provide the JDBC connector for your database to the classpath of the IdP. You might use one of the provided MySQL or HSQL JDBC connector:


cp $UAPPROVE_INSTALL/lib/jdbc/optional/#jdbc-connector#.jar $SHIB_INST_HOME/lib

Ensure that only one version of each library is present in $SHIB_INST_HOME/lib.

Configuration Template

Copy the configuration template to the IdPs configuration directory:

cp $UAPPROVE_INSTALL/manual/configuration/uApprove.properties $SHIB_HOME/conf

cp $UAPPROVE_INSTALL/manual/configuration/uApprove.xml $SHIB_HOME/conf

Webapp files


Copy of the web application files like the JSPs, CSS files and images to the IdPs webapp directory:

mkdir $SHIB_INST_HOME/src/main/webapp/uApprove

cp $UAPPROVE_INSTALL/webapp/* $SHIB_INST_HOME/src/main/webapp/uApprove

Database Preparation

Configure MySQL for a very long connection timeout. By default, MySQL closes connections after 8 hours of inactivity. This breaks connections overnight - and the database clients running on the IdP (uApprove and also SharedToken) report errors when reconnecting to the database (even when using autoReconnect=true). Edit /etc/my.cnf and add the following into the [mysqld] section:

wait_timeout=31536000 # 3600*24*365 - one year

  • Restart the Database after the configuration change

CentOS 6 / Redhat 6

/etc/init.d/mysqld restart


CentOS 7 / Redhat 7

systemctl restart mariadb


Setup the database, the following database parameters are as a guide only.
  • Create a MySQL database (uApprove), a user (also uApprove), and grant the user full access over the database (replace DB-PASSWORD with a suitable password):
mysql -u root -p
mysql>
CREATE DATABASE uApprove;
CREATE USER 'uApprove'@'localhost' IDENTIFIED BY 'DB-PASSWORD';
GRANT INSERT, SELECT, UPDATE, DELETE ON uApprove.* TO 'uApprove'@'localhost';
ALTER DATABASE uApprove DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

Create the initial table structures using the schema creation files
mysql -u root -p -D uApprove < $UAPPROVE_INSTALL/manual/storage/terms-of-use-schema.sql

mysql -u root -p -D uApprove < $UAPPROVE_INSTALL/manual/storage/attribute-release-schema.sql

Web Application Deployment Descriptor

Extend the IdP web application deployment descriptor ( $SHIB_INST_HOME/src/main/webapp/WEB-INF/web.xml):

Add $IDP_HOME$/conf/uApprove.xml to the <context-param...> area in the web.xml file.


<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>$IDP_HOME$/conf/internal.xml; 
$IDP_HOME$/conf/service.xml;
 
$IDP_HOME$/conf/uApprove.xml;
</param-value> 
</context-param>


Add the uApprove Filter and Servlets ( $SHIB_INST_HOME/src/main/webapp/WEB-INF/web.xml):

Add the following to the web.xml file just after the last closing </filter-mapping>.

<!-- uApprove Filter and Servlets -->
<filter>
<filter-name>uApprove</filter-name>
<filter-class>ch.SWITCH.aai.uApprove.Intercepter</filter-class>
</filter>
<filter-mapping>

    <filter-name>uApprove</filter-name>
        <url-pattern>/profile/Shibboleth/SSO</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/AttributeQuery</url-pattern>
        <url-pattern>/profile/SAML1/SOAP/ArtifactResolution</url-pattern>
        <url-pattern>/profile/SAML2/POST/SSO</url-pattern>
        <url-pattern>/profile/SAML2/POST-SimpleSign/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Redirect/SSO</url-pattern>
        <url-pattern>/profile/SAML2/Unsolicited/SSO</url-pattern>
        <url-pattern>/Authn/UserPassword</url-pattern>
</filter-mapping>

<servlet>
<servlet-name>uApprove - Terms Of Use</servlet-name>
<servlet-class>ch.SWITCH.aai.uApprove.tou.ToUServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>uApprove - Terms Of Use</servlet-name>
<url-pattern>/uApprove/TermsOfUse</url-pattern>
</servlet-mapping>

<servlet>
<servlet-name>uApprove - Attribute Release</servlet-name>
<servlet-class>ch.SWITCH.aai.uApprove.ar.AttributeReleaseServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>uApprove - Attribute Release</servlet-name>
 <url-pattern>/uApprove/AttributeRelease</url-pattern>
</servlet-mapping>


Custom Configuration


In $SHIB_HOME/conf/uApprove.xml change:
<context:property-placeholder location="classpath:/configuration/uApprove.properties" />
to
<context:property-placeholder location="file:$SHIB_HOME$/conf/uApprove.properties" />
Note: You must expand $SHIB_HOME$ to it's actual values, e.g. /opt/shibboleth-idp
Customize $SHIB_HOME/conf/uApprove.properties according your database environment and required features. See inline documentation for configuration options.

Deployment


To activate uApprove the IdP must be re-deployed.


cd $SHIB_INST_HOME
./install.sh






Start Tomcat

  • Start MySQL, Tomcat and Apache and make them auto start:

CentOS 6 / Redhat 6

service mysqld start
service tomcat start
service httpd start
chkconfig mysqld on
chkconfig tomcat on
chkconfig httpd on

CentOS 7 / Redhat 7

systemctl start mariadb
systemctl start tomcat
systemctl start httpd
systemctl enable mariadb
systemctl enable tomcat
systemctl enable httpd

 

Advanced uApprove Deployment

This sections contains advanced configuration topics.

Reset Attribute Release Consent

To provide an option that allows users to clear their attribute release consent during the login flow, add a check box to $SHIB_INST_HOME/src/main/webapp/login.jsp. You must re-deployed the IdP for this change to take effect.

<form action="<%=request.getAttribute("actionUrl")%>" method="post">   

...
<section>
<input id="uApprove.consent-revocation" type="checkbox" name="uApprove.consent-revocation" value="true"/>
Clear my attribute release consent
</section>
...

</form>

Additional Information on uApprove

Additional configuration is possible with uApprove for more details refer to the uApprove manual provided on the SWITCHaai web site.





Configure Attribute Resolver

All user attributes (except AuthenticationMethod) are retrieved, generated or defined using the Attribute Resolver.  This section will show how all of the AAF Core attributes and Recommended attributes (as described in the Attributes section of the wiki) are retrieved using the Attribute Resolver.

All attribute configuration is done in /opt/shibboleth-idp/conf/attribute-resolver.xml.

Edit this file to implement the following changes:

Link your Attribute Resolver to your LDAP server

In /opt/shibboleth-idp/conf/attribute-resolver.xml, uncomment the LDAP DataConnector element and configure it with local LDAP connection parameters to connect to your LDAP server (ldapURL, baseDN, principal, principalCredential) and also set the property java.naming.referral to "follow":

<resolver:DataConnector id="myLDAP" xsi:type="dc:LDAPDirectory" 
    ldapURL="ldap://ldap.institution.domain.com.au"
    baseDN="dc=institution,dc=domain,dc=com,dc=au
    principal="LDAP-BIND-DN-HERE"
    principalCredential="PASSWORD-HERE">
    <dc:FilterTemplate>
        <![CDATA[
            (uid=$requestContext.principalName)
        ]]>
    </dc:FilterTemplate>
    <dc:LDAPProperty name="java.naming.referral" value="follow"/>
</resolver:DataConnector>

Link existing attributes

mail, sn (surname), givenName and displayName

Define attributes available directly in LDAP: mail, sn, givenName and displayName: just uncomment the relevant AttributeDefinition element for each of these attributes.

Define static attributes

o (organizationName),  schacHomeOrganization, schacHomeOrganizationType

We need to define several attributes that would have a static value for each user. We do so by first defining a StaticDataConnector (close to where the commented-out example is):

Provide actual meaningful values for your institution: full organization name, home organization name (same as scope), and home Organization Type.
  • For full list of homeOrganizationType values the format is "urn:mace:terena.org:schac:homeOrganizationType:<country-code>:<string>" where,
    • The <country-code> must be a valid two-letter ISO 3166 country code identifier
    • <string> from a nationally controlled vocabulary
  • Examples values
      • urn:mace:terena.org:schac:homeOrganizationType:au:university
      • urn:mace:terena.org:schac:homeOrganizationType:au:research-institution
      • urn:mace:terena.org:schac:homeOrganizationType:au:other

DataConnector - staticAttributes

<!-- Static Connector -->
<resolver:DataConnector id="staticAttributes" xsi:type="dc:Static">
    <dc:Attribute id="o">
        <dc:Value>The EXAMPLE Institution</dc:Value>
    </dc:Attribute>
    <dc:Attribute id="homeOrganization">
        <dc:Value>example.domain.edu.au</dc:Value>
    </dc:Attribute>
    <dc:Attribute id="homeOrganizationType">
        <dc:Value>urn:mace:terena.org:schac:homeOrganizationType:au:EXAMPLE</dc:Value>
    </dc:Attribute>
</resolver:DataConnector>

Now define the attributes:

  • Define organizationName by uncommenting the definition and changing the connector dependency from "myLDAP" to "staticAttributes"
  • Pasting in the definitions for homeOrganization and homeOrganizationType, not provided in the default configuration:

homeOrganization

<resolver:AttributeDefinition id="homeOrganization" xsi:type="ad:Simple" sourceAttributeID="homeOrganization">
    <resolver:Dependency ref="staticAttributes" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:oid:1.3.6.1.4.1.25178.1.2.9" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.9" friendlyName="homeOrganization" />
</resolver:AttributeDefinition>

 

homeOrganizationType

<resolver:AttributeDefinition id="homeOrganizationType" xsi:type="ad:Simple" sourceAttributeID="homeOrganizationType">
    <resolver:Dependency ref="staticAttributes" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:oid:1.3.6.1.4.1.25178.1.2.10" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:1.3.6.1.4.1.25178.1.2.10" friendlyName="homeOrganizationType" />
</resolver:AttributeDefinition>

Define scripted attributes

eduPersonAffiliation, eduPersonScopedAffiliation and cn (commonName)

The eduPersonAffiliation describe the affiliation type of the user authenticating. The typical question is: "Is this person staff or student?" The full set of values (with definitions available in the AAF Attribute Recommendation) is: faculty / student / staff / employee / member / affiliate / alum / library-walk-in. The eduPersonAffiliation attribute is multi-valued and should include all values that apply to the user.

Typically, the LDAP server will not be directly providing values for these attributes, but it would have some attributes that allow to determine at least some of the affiliation type values applying to the user - e.g. to tell whether the user is a staff member or a student.

In this case, we recommend defining the attributes using a scriptlet, synthesizing the value from the LDAP attributes available.

This would be very specific for each institution. We illustrate this in an example (based on an actual setup), where we assume the LDAP server has attributes:
  • isUnderGrad (boolean)
  • isPostGrad (boolean)
  • isStaff (boolean)
We decide to give anyone with isStaff=TRUE the "staff" affiliation, and to anyone with isUnderGrad=TRUE OR isPostGrad=TRUE the "student" affiliation. Also, anyone who is staff or student also gets the "member" affiliation.
  • We first define these attributes at the Shibboleth level, importing them from LDAP, using the following definitions. Note that as these attributes are not expected to be passed in Shibboleth assertions, the definitions don't have any AttributeEncoder elements. Otherwise, we would have to decide on attribute names / OIDs to use in the encoder definitions.

isUnderGrad, isPostGrad and isStaff

<!-- prerequisite to scripted eduPersonAffiliation -->
<resolver:AttributeDefinition id="isUnderGrad" xsi:type="ad:Simple" sourceAttributeID="isUnderGrad">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->
</resolver:AttributeDefinition>
 
<resolver:AttributeDefinition id="isPostGrad" xsi:type="ad:Simple" sourceAttributeID="isPostGrad">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->
</resolver:AttributeDefinition>
 
<resolver:AttributeDefinition id="isStaff" xsi:type="ad:Simple" sourceAttributeID="isStaff">
    <resolver:Dependency ref="myLDAP" />
    <!-- no encoder needed -->
</resolver:AttributeDefinition>

  • We follow by defining eduPersonAffiliation using an AttributeDefinition of type Script:
<resolver:AttributeDefinition id="eduPersonAffiliation" xsi:type="ad:Script">
    <resolver:Dependency ref="isUnderGrad" />
    <resolver:Dependency ref="isPostGrad" />
    <resolver:Dependency ref="isStaff" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:eduPersonAffiliation" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1" friendlyName="eduPersonAffiliation" />
    <ad:Script>
    <![CDATA[
            importPackage(Packages.edu.internet2.middleware.shibboleth.common.attribute.provider);
            if (eduPersonAffiliation == null) {
                    eduPersonAffiliation = new BasicAttribute("eduPersonAffiliation");
            }
            is_UnderGrad = isUnderGrad != null && isUnderGrad.getValues().size()>0 && isUnderGrad.getValues().get(0).equals("TRUE");
            is_PostGrad = isPostGrad != null && isPostGrad.getValues().size()>0 && isPostGrad.getValues().get(0).equals("TRUE");
            is_Staff = isStaff != null && isStaff.getValues().size()>0 && isStaff.getValues().get(0).equals("TRUE");
 
            if (is_Staff) { eduPersonAffiliation.getValues().add("staff"); };
            if (is_UnderGrad || is_PostGrad ) { eduPersonAffiliation.getValues().add("student"); };
            if (is_UnderGrad || is_PostGrad || is_Staff ) { eduPersonAffiliation.getValues().add("member"); };
    ]]>
    </ad:Script>
</resolver:AttributeDefinition>

  • Finally, we define the eduPersonScopedAffiliation attribute by uncommenting the definition and:
    • setting your institution's scope, in the format scope="institution.domain.edu.au"
    • changing the dependency from LDAP to the previously defined attribute eduPersonAffiliation:
<resolver:Dependency ref="eduPersonAffiliation" />

The cn (commonName) in some directories will be the user's login name, but the AAF requires the cn to contain only the user's given name and surname separated by a space. The simplest way to achieve this is to script the cn value from the user's actual given name and surname as follows.

cn

    <resolver:AttributeDefinition xsi:type="ad:Script" id="commonName">
       <resolver:Dependency ref="givenName" />
       <resolver:Dependency ref="surname" />
       <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:cn" />
       <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:2.5.4.3" friendlyName="cn" />


       <ad:Script><![CDATA[
           importPackage(Packages.edu.internet2.middleware.shibboleth.common.attribute.provider);

            commonName = new BasicAttribute("commonName");

            if ((typeof givenName != "undefined" && givenName != null && givenName.getValues().size()>0) &&
                (typeof surname != "undefined" && surname != null && surname.getValues().size()>0)) {

                commonName.getValues().add(givenName.getValues().get(0) + " " + surname.getValues().get(0));
            }

            if ((typeof givenName == "undefined" || givenName == null || givenName.getValues().size()==0) &&
                (typeof surname != "undefined" && surname != null && surname.getValues().size()>0)) {
                commonName.getValues().add(" " + surname.getValues().get(0));
            }

            if ((typeof givenName != "undefined" && givenName != null && givenName.getValues().size()>0) &&
                (typeof surname == "undefined" && surname == null && surname.getValues().size()==0)) {
                commonName.getValues().add(givenName.getValues().get(0) +" ");
            }

       ]]>
       </ad:Script>
    </resolver:AttributeDefinition>


Define sharedToken

auEduPersonSharedToken

The auEduPersonSharedToken attribute is an AAF core attribute that is based on the auEduPerson schema. The shared token is not part of the standard Shibboleth installation. It requires a specific plugin to be installed together with some additional configuration. This following section describes who to install the plugin that will generated Shared Tokens for users and store the shared token in either a database or a ldap directory.

  1. Following the full sharedToken install guide, we will choose to store the SharedToken value in a MySQL database - to keep track of values issued and have a means of inserting a different value if someone asks for portability.
  • Download binary from AAF Files download site
wget http://www.aaf.edu.au/download/arcs-shibext-1.5.4.jar

The shared token value MUST be stored in either the LDAP server itself (preferred, keeps the values alongside primary identity information), or alternatively in a MySQL database (easier to get going by running a MySQL server directly on the IdP).

In this section, some instructions are specific to storing the shared token values in an LDAP server, some are specific to storing the values in a local MySQL server - please choose accordingly.

  • If storing the sharedToken value in your LDAP server, edit the conf/sharedtoken.properties inside the jar and change the following settings - the search filter should be the same as in your LDAP connector - configuring which LDAP attribute is the principal name:

Note: If your ldap uses "uid" then no change is required.

DEFAULT_IDP_HOME=/opt/shibboleth-idp
ATTRIBUTE_RESOLVER=$IDP_HOME/conf/attribute-resolver.xml
SEARCH_FILTER_SPEC=cn={0}



  • Copy the JAR into $SHIB_INST_HOME/lib and (later) rerun the Shibboleth IdP installer to rebuild the webapp WAR archive. (When rerunning the installer, accept the default install location (or specify your install location, stored also in $IDP_HOME) and answer no to the question on overwriting configuration.)
cp arcs-shibext-*.jar $SHIB_INST_HOME/lib
cd $SHIB_INST_HOME
sh ./install.sh

Configuring a MySQL database for storing sharedToken values

    • Install the driver (mysql-connector-java-5.x.y-bin.jar) into $SHIB_INST_HOME/lib and also into /opt/shibboleth-idp/lib (and rerun the Shibboleth IdP installer - now)
  • Create a MySQL user: run "mysql" as root and enter the following commands:
 
create user 'idp_admin'@'localhost' identified by 'IDP_ADMIN_PASSWORD';
 grant all privileges on idp_db.* to 'idp_admin'@'localhost';
  • Create a MySQL schema: run "mysql" as idp_admin and enter the following commands:
 mysql -u idp_admin -p

 CREATE DATABASE idp_db;
 use idp_db;

 CREATE TABLE tb_st (
 uid VARCHAR(100) NOT NULL,
 sharedToken VARCHAR(50),
 PRIMARY KEY  (uid)
 );

Defining sharedToken attribute (both LDAP and MySQL)

  • Add schema definition to attribute-resolver.xml: add urn:mace:arcs.org.au:shibboleth:2.0:resolver:dc classpath:/schema/arcs-shibext-dc.xsd to the list of schema locations at the top of the file.
  • Add connector definition to attribute-resolver.xml (sharedToken) with the following customizations:
    • idPIdentifier - your IdP entityId, sourceAttributeID: combination of attributes that is unique, non-reassignable and if possible persistent - if usernames are not reused at your institution, username is perfectly fine - so the "cn" or "uid" attribute would do
    • If using a MySQL server, enter the database connection details, with the IDP_ADMIN_PASSWORD as defined just above
    • If storing sharedToken in an LDAP server:
      • Omit the DatabaseConnection element from the below snippet
      • Change the values to storeLdap="true" and storeDatabase="false"
<!-- ==================== auEduPersonSharedToken data connector ================== -->
 
<resolver:DataConnector xsi:type="SharedToken" xmlns="urn:mace:arcs.org.au:shibboleth:2.0:resolver:dc"
                    id="sharedToken"
                    idpIdentifier="https://idp.institution.domain.edu.au/idp/shibboleth"
                    sourceAttributeID="uid"
                    storeLdap="false"
                    storeDatabase="true"
                    salt="SALT-GOES-HERE">
    <resolver:Dependency ref="myLDAP" />
 
    <DatabaseConnection jdbcDriver="com.mysql.jdbc.Driver"
                        jdbcURL="jdbc:mysql://localhost/idp_db?autoReconnect=true"
                        jdbcUserName="idp_admin"
                        jdbcPassword="IDP_ADMIN_PASSWORD"
                        primaryKeyName="uid"/>
 
</resolver:DataConnector>

  • Note: on the first install, generate a suitable salt value with:
 
openssl rand -base64 36
 
    • On subsequent installs, reuse the same value (stored somewhere carefully)
  • Note also that the SharedToken value depends on the IdP entityID - which could be picked up from the environment, but is better set in the configuration.
  • Note that the JdbcURL uses "?autoReconnect=true" - which is an extension from the original shared-token installation instructions.

  • IMPORTANT: If storing the values in an LDAP server, modify the LDAP DataConnector so that the FilterTemplate element is defined without any namespace qualifier, just with a default namespace, as in the following snippet. Make the same change for any LDAPPropertyElements. This is needed due to a known problem in the shared-token implementation.
        <FilterTemplate xmlns="urn:mace:shibboleth:2.0:resolver:dc">
            <![CDATA[
                (cn=$requestContext.principalName)
            ]]>
        </FilterTemplate>
        <LDAPProperty name="java.naming.referral" value="follow" xmlns="urn:mace:shibboleth:2.0:resolver:dc" />

  • Add attribute definition to attribute-resolver.xml (auEduPersonSharedToken)
<!-- ==================== auEduPersonSharedToken attribute definition ================== -->
<resolver:AttributeDefinition id="auEduPersonSharedToken" xsi:type="ad:Simple" sourceAttributeID="auEduPersonSharedToken">
    <resolver:Dependency ref="sharedToken" />
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:federation.org.au:attribute:auEduPersonSharedToken" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:1.3.6.1.4.1.27856.1.2.5" friendlyName="auEduPersonSharedToken" />
</resolver:AttributeDefinition>


eduPersonTargetedID


The AAF Recommends using the StoreIDDataConnector over the computedID. See https://wiki.shibboleth.net/confluence/display/SHIB2/ResolverStoredIDDataConnector for configuration details.

     1. Define the database table.
The Stored ID data connector stores its created ID in a database. You must create a database table with the following definition. This can be done in the same schema use for the auEduPersonSharedToken if you use the database for storing this values.

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;

     2. Define the Connector
To define a new computed ID data connector, create a <DataConnector xsi:type="StoredId" xmlns="urn:mace:shibboleth:2.0:resolver:dc"> element,

    <!-- Stored targted ID connector -->
    <resolver:DataConnector xsi:type="StoredId"
        xmlns="urn:mace:shibboleth:2.0:resolver:dc" id="storedID"
        sourceAttributeID="uid"
        generatedAttributeID="storedID"
        salt="ThisIsRandomText">

        <resolver:Dependency ref="myLDAP" />

        <ApplicationManagedConnection
                jdbcDriver="DRIVER_CLASS"
                jdbcURL="DATABASE_URL"
                jdbcUserName="DATABASE_USER"
                jdbcPassword="DATABASE_USER_PASSWORD" />

    </resolver:DataConnector>


     3. Set the salt value used by the data connector.
openssl rand -base64 36

     4. Uncommenting AttributeDefinition id="eduPersonTargetedID" and modifying to use the storedID data connector.

    <resolver:AttributeDefinition xsi:type="ad:SAML2NameID" id="eduPersonTargetedID"
                                  nameIdFormat="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" sourceAttributeID="storedID">
        <resolver:Dependency ref="storedID" />
        <resolver:AttributeEncoder xsi:type="enc:SAML1XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" />
        <resolver:AttributeEncoder xsi:type="enc:SAML2XMLObject" name="urn:oid:1.3.6.1.4.1.5923.1.1.1.10" friendlyName="eduPersonTargetedID" />
    </resolver:AttributeDefinition>


Verify changes to attribute-resolver.xml

A number of changes have been made to the attribute-resolver.xml file. Before continuing you should verify the changes you have made by restarting the Tomcat server and checking the idp-process.log file for errors.



Joining the federation

To join your IdP to the AAF you must register it in the AAF Federation Registry. An overview of this process is provided in the Knowledge base article: How to technically join the Australian Access Federation

Register your IdP

  • Select the "Create Identity Provider" tab and follow the instructions. You need to provide various pieces of information about your identity providers including
    • The Organisation to which the IdP belongs
    • The host your IdP is running on
    • The scope for which the IdP can assert attributes
    • The public key (/opt/shibboleth-idp/credentials/idp.crt)
    • The attributes supported by the IdP
  • After you submit your IdP to be registered you will receive an an email stating the following:
 


This email confirms that the Identity Provider which you've registered with the Australian Access Federation has been 
received but is not yet ready for use. 

Your Identity Provider will now move through a workflow process that requires approvals by AAF staff and potentially your organisation. 

Please allow up to 48 hours for this to occur. Upon completion of the process you will receive another email confirming activation of your Identity Provider and further instructions for completing your deployment. 

Important Details

Internal ID:9,999
Entity ID:https://example.uni.edu.au/idp/shibboleth
Display Name:Example IdP
Description:For demonstration purposes
Owner:Example


Please contact the AAF support desk if the details are incorrect or if you have not received a response within 48 hours.

  • When your IdP has been approved you will receive a followup email. 
  • READ this email carefully and follow all steps. There are important actions you must perform after your IdP is accepted.


The Identity Provider which you've registered with the Australian Access Federation has been
accepted. You can now complete final setup tasks. 

Please keep this email for future reference. 

Your unique code for administrative access (required in step 4 below)
a69ff70478


Important Details

Internal ID:9,888
Entity ID:https://example.uni.aaf.edu.au/idp/shibboleth
Display Name:Example IdP
Description:For demonstration purposes
Owner:Example

Next Steps

1. Validate EntityID 
Your Identity Provider must use a unique EntityID to identify it to the rest of the federation and this value must match both your local configuration and Federation Registry. 


Please verify your Identity Provider configuration uses the EntityID shown above under 'Important Details'. If it doesn't, you can't go any further. Contact the AAF support desk for help in resolving this fault. 

2. Ensure Time Sync 
The server which runs your Identity Provider must be synchronized to a suitable NTP source and remain in sync at all times. 


Users from an Identity Provider which is out of time sync will fail to login to remote services.


3. Configure Attribute Release 
Configure your Identity Provider to correctly release attributes to the federation as documented in Automating Attribute Release. When asked for the value of [YOUR UNIQUE URL] please provide https://ds.test.aaf.edu.au/distribution/attributefilter/9999.xml. 



Ensure at least an hour has passed since you received this email before continuing. This allows distribution of metadata including details of your new Identity Provider to circulate to the federation. 


4. Claim your administrative access 
Navigate to your Identity Provider's management page and access the administrator tab. Enter the unique code provided below in the box labelled CODE. This can only be used once. Once applied you can then provide access to other administrators on your team. 


Your unique code for administrative access in Federation Registry:
a69ff70478



5. Double check all information associated with your Identity Provider that is stored in Federation Registry making changes if you note any inaccuracies. 


6. Ensure you've applied appropriate branding to all of your Identity Providers pages including the login screen and all error pages. 


Branding should be consistent with that used on your organisation's website. 


7. Test your new Identity Provider with other services connected to the federation, especially those which are of importance to your organisation. 


8. You're all done! Welcome to the Australian Access Federation.


Setting up Automated Attribute release

One of the most complex tasks an Identity Provider (IdP) administrator has to keep up with is the constantly changing set of services and attribute requirements each service has.

The AAF Federation Registry service automates this process in 2 ways:

1. Keeping metadata up to date in a standards compliant manner to advertise what IdPs offer and what SPs have been approved to receive (This is useful for non Shibboleth, SAML 2 MD specification compliant implementations)

2. Generation of Shibboleth 2 compliant Attribute-Filter policies, which are published over https and automatically consumed by IdP. Using this approach your IdP is always in Sync.


Automating attribute release for Shibboleth 2 IdP

1. Determine your unique attribute filter URL via one of the methods below:

  1. If you've received your IDP acceptance email with the subject "Your Identity Provider has been accepted" go to the Configure Attribute Release section to find the URL to use.
  2. If you have an existing IdP, navigate to Federation Registry and view your IdP details. In the SAML section and under the Attribute Filter sub section you will find the required URL
This is your Unique URL that will be used in the next few steps.

2. Navigate to your IdP configuration directory (generally /opt/shibboleth-idp/conf). Run wget (or similar under windows)

wget [YOUR UNIQUE URL] -O AAF-attribute-filter.xml

Check that the file downloads correctly and make sure it is writable by the user your IDP tomcat container runs as. You may need to install the default SSL CA bundle on your system if you have SSL verification problems. Please contact your system administrator who will be able to install appropriate packages.

If you view the first few lines of the downloaded file you should see that it indicates it was uniquely created for your IdP and its associated entityID.

3. Edit the file service.xml to contain the following (note the use of the XML srv namespace which is required on Shibboleth IdP 2.4 and greater):

<srv:Service id="shibboleth.AttributeFilterEngine"
          configurationResourcePollingFrequency="PT1H" 
          configurationResourcePollingRetryAttempts="10"
          xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-filter.xml" xsi:type="resource:FilesystemResource" />
             <srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                   url="[YOUR UNIQUE URL]"
                   file="/opt/shibboleth-idp/conf/AAF-attribute-filter.xml" />
</srv:Service>

Here is an example of ours (this is a pre shibboleth 2.4 IdP example, note the lack of XML srv namespace which is required on Shibboleth IdP 2.4 and a difference in the way polling frequency is defined):

Text Box

<Service id="shibboleth.AttributeFilterEngine" configurationResourcePollingFrequency="1800000" 
    configurationResourcePollingRetryAttempts="10" xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
        <ConfigurationResource  xsi:type="resource:FileBackedHttpResource"
	url="https://ds.test.aaf.edu.au/distribution/attributefilter/299.xml"
	file="/opt/shibboleth-idp/conf/AAF-attribute-filter.xml" />
</Service> 

4. If your IdP is already functioning restart your IdP to pick up these changes. If you are undertaking an initial install continue on with the advertised steps.

Attribute name checks

The attribute names used in the downloaded policy file AAF-attribute-filter.xml must match the local attribute names. Check that the attribute names in the downloaded attribute filter against their names in existing configuration files:

  1. attribute-resolver.xml ensure the values for attributeID in the AAF-attribute-filter.xml file map to id values in your resolver eg for auEduPersonSharedToken:

    AAF-attribute-filter.xml
    <AttributeRule attributeID="auEduPersonSharedToken"><PermitValueRule xsi:type="basic:ANY"/></AttributeRule>

    attribute-resolver.xml
    <resolver:AttributeDefinition id="auEduPersonSharedToken" xsi:type="Simple" xmlns="urn:mace:shibboleth:2.0:resolver:ad"
                sourceAttributeID="auEduPersonSharedToken">

    AAF-attribute-filter.xml will likely contain many policies for numerous services. Validating the attributes within the policy for https://manager[.test].aaf.edu.au/shibboleth is more than sufficient.
  2. /opt/shibboleth-idp/uApprove.properties under sections ar.attributes.order and ar.attributes.blacklist ensuring values for attributeID in the AAF-attribute-filter.xml file map to the values configured here.

Logging into the Federation Registry

After you receive the email confirming the successful activation of your IdP several changes to the federation will occur within 60 minutes.
  • Your IdP will be listed on in the Where are You From (WAYF) 
  • Your IdP's metadata will be included in the federation metadata
You must wait until both of these events have completed before attempting to login to the AAF Federation Registry for the first time.
Note: You may have to restart Tomcat to get your IdP to load the latest Metadata with your IdP included as your IdP may take up to 2 hours to do so automatically.

You are now ready to login to the Federation Registry for the first time. Navigate to the Federation Registry and select Login. This will take you to the WAYF, select you IdP and login. If all went well you should be logged into the Federation Registry.

The most common issue that occurs when logging in for the first time is missing required attributes. The Federation Registry will tell you which attributes where missing.

Becoming an Identity Provider Administrator 

When your Identity Provider was approved you will have received an email "Your Identity Provider has been accepted. Important information and next steps."In this email is a unique code that will enable you to become an administrator.
This email will also describe how to use this code.
  • Click on this link and login to the Federation Registry with the account you wish to use as Administrator.
As Identity Provider administrator you will be able to perform the following functions on your Identity Provider.
  • Add and modify the lists of contacts. See the list above for available contact roles.
  • Add and modify Identity provider administrators
  • Modify Identity Provider details.
Warning: Changing details of your Identity Provider can result in changes to the federation metadata which may impact on the operation of your IdP.

Registering SAML1.x Endpoints

Some Identity provides will need to work with older SAML1 (Shibboleth 1.3.x) service providers. By default the Federation Registry does not create the SAML1.x endpoints. Log a job with support@aaf.edu.au to request the addition of SAML 1.x endpoint. For more details set the Knowledge base article: SAML 1.x endpoints and Federation Registry

Monitoring your IdP

The AAF provides a monitoring service that regularly updates the Federation Status page. Use the federation registry to define which monitors you want enabled for your new IdP. At a minimun your should enable the Time Sync monitor using the IdP Status address and the location, eg.

https://idp.institute.domain.edu.au/idp/profile/Status

If the IdP is functioning the this address should return with a value of "ok". The http header will also return a timestamp of the current time on the server running the IdP. If the time differs by more the three minutes to other servers within the federation users may begin to see errors when attempting to login.

Other monitors are available and are described in the AAF Monitoring documentation.

Setting the Automatic Attribute Release Flag

If you have deployed your IdP to use Automatic Attribute Release (recommended by the AAF) you need to indicate this in the Federation Registry tool to inform all service providers that you are doing so. IdP's that use Automatic Attribute Release will in general work better with all new and modified service providers because of the automation.

To flag that you are using Automatic Attribute Release is enable go to the Overview tab of your IdP and click on the Edit button. Ensure Yes is selected then click Save.

Advanced IdP Configuration

Enabling automatic reload

To automatically reload a service configuration (such as the attribute-filter.xml file), one has to add two attributes to the service definition: configurationResourcePollingFrequency (in milliseconds) and configurationResourcePollingRetryAttempts.

  • The change done to /opt/shibboleth-idp/conf/service.xml is thus:
     <srv:Service id="shibboleth.AttributeResolver"
              configurationResourcePollingFrequency="PT5.000S" 
     configurationResourcePollingRetryAttempts="10"
              xsi:type="attribute-resolver:ShibbolethAttributeResolver">
         <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-resolver.xml" xsi:type="resource:FilesystemResource" />
     </srv:Service>

     <srv:Service id="shibboleth.AttributeFilterEngine"
              configurationResourcePollingFrequency="PT5.000S" 
              configurationResourcePollingRetryAttempts="10"
              xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">
         <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/attribute-filter.xml" xsi:type="resource:FilesystemResource" />
     </srv:Service>


and

     <srv:Service id="shibboleth.RelyingPartyConfigurationManager"
          configurationResourcePollingFrequency="PT5.000S" 
          configurationResourcePollingRetryAttempts="10"
          xsi:type="relyingParty:SAMLMDRelyingPartyConfigurationManager"
          depends-on="shibboleth.SAML1AttributeAuthority shibboleth.SAML2AttributeAuthority">
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/relying-party.xml" xsi:type="resource:FilesystemResource" />
     </srv:Service>

     <srv:Service id="shibboleth.HandlerManager"
          configurationResourcePollingFrequency="PT5.000S" 
          configurationResourcePollingRetryAttempts="10" 
          depends-on="shibboleth.RelyingPartyConfigurationManager"
          xsi:type="profile:IdPProfileHandlerManager">
        <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/handler.xml" xsi:type="resource:FilesystemResource" />
     </srv:Service>




Enabling ECP support

ECP Overview

The ECP profile is an adaptation of the SAML profile used for Browser SSO with the parts that were designed around the limitations of a browser removed.

It is designed for clients such as:

  • Desktop applications;
  • Server-side code running in a web application; and
  • Anything else that isn't a browser.

Version 2.0 of the ECP profile is now standardised, and is the best choice to base a new implementation or project around. Version 2.0 is:

  • Backwardly-compatible with the original;
  • Adds support for "Holder of Key" subject confirmation;
  • Adds support for channel bindings; and
  • Is defined more succinctly.

Direct vs. Delegated Authentication

The basic definition of the ECP profile is designed around the same set of "actors" as the Browser SSO profile:

  1. A subject controlling a client;
  2. An IdP that can authenticate the subject; and
  3. An SP that can accept an assertion from the IdP to establish a session with the subject.

Generally speaking ECP is a "single tier" profile for a user accessing a service.

A more advanced variant of the ECP work can be combined with some other profiles to solve a more complicated problem, that of multi-tier delegation. In the delegated case, the "client" accessing the web service is acting on behalf of an earlier client that authenticated to it with SAML.

With delegation, the web service can recognize both the original client/subject and the "delegate" that is accessing it on behalf of that subject, and control or limit access based on both identities.

Current AAF support

At this time the AAF is only supporting the basic, direct modes of working with ECP and is not supporting the more advanced uses of holder of key or channel bindings.

This may change in the future if there is sufficient need and would require further investigation.

Enabling ECP support in your Identity Provider

Technical Prerequisites

This section assumes you already have a tested, fully functioning Identity Provider with a minimum version number of 2.3.0 or greater as described in the Identity Provider install guide that has at a minimum been used successfully with the AAF Attribute Validator. The documentation here was developed on Shibboleth IdP version 2.4.2 and AAF support strongly recommends subscribers on older releases upgrade to the latest release of Shibboleth IdP in order to ensure they have all security patches and bug fixes.

If this is not the case please ensure you successfully complete an install or upgrade before continuing.

Internal IdP configuration

The basics of enabling the Shibboleth IdP to support ECP are reasonably straight forward. Ensure the following exists in the your IdP's configuration files (generally under /opt/shibboleth-idp/conf) and add them if not:

  • relying-party.xml: A definition of SAML2ECPProfile
  <rp:ProfileConfiguration xsi:type="saml:SAML2ECPProfile"
        signAssertions="always"
        includeAttributeStatement="true"/>


  • handler.xml: An ECP endpoint definition:

  <ph:ProfileHandler xsi:type="ph:SAML2ECP"
       inboundBinding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
       outboundBindingEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:SOAP">
      <ph:RequestPath>/SAML2/SOAP/ECP</ph:RequestPath>
    </ph:ProfileHandler>


Authenticating ECP requests

This is where ECP gets somewhat complex. The authentication method that you're already using for web browser clients will not work for ECP.

There are many ways your IdP may choose to authenticate an ECP request but the most common is via basic authentication using the HTTP Authorize header. If you choose to not use basic authentication then applications wishing to use your IdP for ECP purposes may find it difficult to establish a session.

In order to not break your existing web browser clients be sure that your ECP basic auth configuration applies only to requests sent to /idp/profile/SAML2/SOAP/ECP. A successful authentication MUST set the REMOTE_USER value so that the Shibboleth IdP can establish a session.

How you undertake basic authentication is a decision that needs to be made by each Identity Provider and largely depends on what sort of backend you have available. 

Using an Apache webserver

If you're using Apache HTTPD as your webserver the following example will probably suit your deployment in order to undertake the basic authentication process for ECP.

Protect the /idp/profile/SAML2/SOAP/ECP location on your IdP with authentication against your LDAP - add the following (customized for your LDAP server) into /etc/httpd/conf.d/idp.conf:

   <Location /idp/profile/SAML2/SOAP/ECP>
                AuthType Basic
                AuthName "Example Institution Shibboleth Identity Provider - ECP profile"
                AuthzLDAPAuthoritative Off
                AuthBasicProvider ldap
                AuthLDAPURL ldap://ldap.example.org/ou=People,dc=example,dc=org?uid
                AuthLDAPBindDN "cn=read,dc=example,dc=org"
                AuthLDAPBindPassword "password"
                Require valid-user
                # enable this only over SSL -  not needed when defined in the context of a https VirtualHost
                SSLRequireSSL
        </Location>


Notes
  • The Apache LDAP module cannot handle LDAP referrals. When connecting to an Active Directory server (which typically includes referrals to other domains in the AD forest in the results), you will need to connect to the Global Catalog at port 3268.
  • In order for the ECP handler (running as part of the Identity Provider web application inside Tomcat) to receive the REMOTE_USER variable set by Apache, the AJP connector in Tomcat must have the tomcatAuthentication="false"

Alternative options


Verify configuration

Restart your Identity Provider. Ensure in logs that everything starts back up as expected and test to ensure that login to the AAF Attribute Validator still functions.

You should also be able to check that the authentication part of your basic authentication process is working by opening https://<idp-url>/idp/profile/SAML2/SOAP/ECP in your web browser. You should be presented with the standard basic authentication login prompt by your browser and on successful login be given a 404 response. Check your logs for details on how the entire process went on your server.

Registering the change in Federation Registry

Once you've completed the technical changes on your server you need to advertise ECP support from Federation Registry.

Navigate to Federation Registry (production | test) and open your Identity Provider management page, this should be linked from your dashboard view, then:

  • Select the SAML tab;
  • Select the second level Endpoints tab and the "Single Sign On Services" category;
  • Click on Add Endpoint;
  • Select Binding urn:oasis:names:tc:SAML:2.0:bindings:SOAP;
  • Enter Location https://<idp-url>/idp/profile/SAML2/SOAP/ECP (substituting your Identity Provider hostname); and
  • Click save

Give this change between 1 and 24 hours to distribute out through the AAF.

End to End testing

The easiest way to check this is by using the AAF ECP Validator service. Undertake the following steps on a Linux/OSX machine:

  1. Ensure you have Python available on your system path. We've tested with version 2.7.5, other versions should work as well but YMMV;
  2. Download the latest version of aaf-ecp-validator.py from Github;
  3. Ensure that you can successfully login to the Attribute Validator using your browser of choice. If there are any problems these must be fixed before continuing;
  4. Navigate to the list of Identity Providers within Federation Registry and find your Identity Providers listing (this might also be linked from your Federation Registry dashboard);
  5. Click on: 
    SAML > Endpoints > Single Sign On Services
  6. Take a copy of the location for the ECP endpoint associated with your Identity Provider, this will be used next as <ssourl>

    To help you identify the correct endpoint it should have the form: https://idp.university.edu.au/idp/profile/SAML2/SOAP/ECP 

  7. Run the following command: 

    $> python aaf-ecp-validator.py <ssourl> https://ecpvalidator[.test].aaf.edu.au/validate <your username> 

  1. You should receive output similar to the following if all is well or a specific error message for your attention. 

    $> python aaf-ecp-validator.py https://vho.test.aaf.edu.au/idp/profile/SAML2/SOAP/ECP https://ecpvalidator.test.aaf.edu.au/validate bradleybeddoes
    
    Enter password for login 'bradleybeddoes':
    
    The AAF ECP Validator was provided the following about your account via ECP session establishment:
    
    eduPersonTargetedID:          https://vho.test.aaf.edu.au/idp/shibboleth!https://ecpvalidator.test.aaf.edu.au/shibboleth!mHCYKXzzZGZMtSOJ090wfSpE0hA=
    displayName:                  Bradley Beddoes
    
    
    Raw JSON response:
    {"service":{"name":"AAF ECP Validator","version":"0.1.0"},"subject":{"principal":"https://vho.test.aaf.edu.au/idp/shibboleth!https://ecpvalidator.test.aaf.edu.au/shibboleth!mHCYKXzzZGZMtSOJ090wfSpE0hA=","display_name":"Bradley Beddoes"}}
    
    ECP session completed.
    
    $>
    
  2. Should you have errors and need extra output add the -d flag for debug output immediently after the client name as follows: 

    $> python aaf-ecp-validator.py -d <ssourl> https://ecpvalidator[.test].aaf.edu.au/validate <your username> 

    In addition a list of open source clients is available from https://wiki.shibboleth.net/confluence/display/SHIB2/Contributions#Contributions-OtherRelatedContributions




Customization and Branding

Customizing and branding IdP login screen

In a default install, the IdP login screen is displaying the unbranded skin. To establish trust with users, this page should at the very least have the proper institution logo and name and the instructions to customize the page should be removed. Each institution may also wish to customize the graphics to match the style of their corporate pages.

Full branding instructions are available at the Shibboleth wiki Login Page customization page: https://wiki.shibboleth.net/confluence/display/SHIB2/IdPAuthUserPassLoginPage

In addition to the login page there are a number of other pages that may be visited by your users when interacting with your IdP. You should apply the branding to all the following pages.

 Files Description
 login.jsp Main login page
 login.css Cascading Style Sheets associate with the login page
 error-404.jsp Error page - Invalid URL entered
 error.jsp Error page – General IdP error
 login-error.jsp Error page – An error occurred while logging in
 logout.jsp Page shown on successful completion of the logout process
 images/ Directory for images used by the IdP UI

Note: You should only edit the files in the Shibboleth source directory then rebuild the .war file (Do not make midifications directly to the .war file as they may be overwritten in the future).

Using the AAF logo

You can include the AAF Logo on your login page to alter users that they are accessing a service that is part of the AAF. The logo and logo use policy is available at: https://www.aaf.edu.au/about/documents-and-reports/.

Customizing and branding uApprove

The uApprove web application by default displays place markers for local branding. To customize this for the local institution (display the institution logo, etc), the following files need to be modified. These files are located in the IdP source tree under /src/main/webapp/uApprove. When complete you need to rebuild the .war file to deploy the changes.

 File Description
 attribute-release.jsp uApprove user consent of attribute release main page
 header.jsp Header for uApprove pages
 footer.jsp Footer for uApprove pages
 styles.css Cascading Style Sheets associate with the uApprove pages
 logo.png Logo that appears on the uApprove pages
 attribute-release.properties If you want to change the titles on the uApprove page concatenate this file to /opt/shibboleth-idp/conf/uApprove.properties. Then modify as required.

Friendly attribute names

By default, uApprove would be representing attributes by their local alias - which may not provide the best possible user experience. Names like "eduPersonPrincipalName" look quite cryptic to an ordinary user. The metadata syntax allows to provide friendly names (even locale-specific multiple names) in the attribute-resolver.xml file, and uApprove will pick the attribute names from there.

The syntax for specifying the attribute names is:

<resolver:AttributeDefinition xsi:type="ad:Simple" id="email" sourceAttributeID="mail">
    <resolver:Dependency ref="myLDAP" />
    <resolver:DisplayName xml:lang="en">Email address</resolver:DisplayName>
    <resolver:AttributeEncoder xsi:type="enc:SAML1String" name="urn:mace:dir:attribute-def:mail" />
    <resolver:AttributeEncoder xsi:type="enc:SAML2String" name="urn:oid:0.9.2342.19200300.100.1.3" friendlyName="mail" />
</resolver:AttributeDefinition>

Add the following attribute descriptions for the respective attributes into attribute-resolver.xml, right between the Dependency and AttributeEncoder elements: 

The table below provides a list of user readable names to replace technical names on uApprove. There are only examples and can be replaced any appropriate string that will aid your users understanding of the type of data that they are agreeing to release to a service provider.


 Attribute   User readable name
 uid Local user ID
 email Email address
 commonName Common name
 surname Surname
 givenName Given name
 eduPersonPrincipalName Global username (EPPN)
 displayName Display name
 organizationName Institution name
 homeOrganization Institution domain
 homeOrganizationType Institution type
 eduPersonAffiliation Affiliation type
 eduPersonScopedAffiliation Affiliation type (with institution)
 eduPersonEntitlement Entitlements
 eduPersonAssurance Identity assurance level
 auEduPersonSharedToken Shared token



Testing

The best way to test an IdP is to try to log into a Service Provider in the federation - and the most convenient way for that is to access an attribute reflector or validator - a page that displays all of the attributes received in the Shibboleth session. The AAF runs an attribute validator in both AAF test and production federation. The attribute validator has been designed to test the attribute your IdP releases and provide feedback when issues are identified.

The attribute reflector URLs are:
  • AAF: https://manager.aaf.edu.au/attributevalidator/
An alternative tool for testing IdP is the Attribute Authority Command Line Interface client - aacli.sh. For a given user TEST_USERNAME, invoke the tool with:

$SHIB_HOME/bin/aacli.sh --principal $TEST_USERNAME --requester [EntityID of a service]

  • The tool output is the set of attributes that would be released for this user to the given application (identified by it's entityID).


Summary

The installation of an Identity Provider into the Australian Access Federation is not a difficult task, but, given the large number of steps currently involved, there is a lot of room for error. Debugging some of these errors can be time consuming. We recommend that you follow this guide from start to finish and ensure all test points throughout are successfully completed before moving on.

The AAF strongly recommends that you deploy an Identity provider into the AAF Test Federation first to become familiar with the software and its configuration. Further we recommend that you maintain your Test IdP using it for upgrade testing and making it available as a test platform for service providers deploying services on behalf of your organisation.

Finally, the AAF team is here to help. If you have any issues with regards to your IdP deployment, please contact us at support@aaf.edu.au, or search for solutions at the AAF Knowledge base.