Tuakiri Documentation

Configuring a Shibboleth Identity Provider to join the Tuakiri Federation

For a Shibboleth Identity Provider to join one of the Tuakiri Federations (Test/Dev or Production), the following steps have to be done:

  • Registering the IdP in the Federation Registry
  • Configuring the IdP to load the federation metadata
  • Configuring the IdP to release the attributes required by the federation.

There are two federations available, both fully operational:

  • Tuakiri Test/Development Environment (Tuakiri-TEST) for testing deployments and developing new features
  • Tuakiri Production Federation Service (Tuakiri) for ready-for-production Identity Providers and services.

We recommend first registering a Test system into Tuakiri-TEST and after successful testing, register a production-ready system into Tuakiri Production.

  1. Federation Details
  2. Registering an IdP into the Federation Registry
  3. Configuring your IdP to load the federation metadata
  4. Configure attribute release/filtering through the federation
  5. Appendix A - Alternative implementation
    1. Optional: Installing XmlSecTool

Federation Details

Federation name Tuakiri Tuakiri TEST
Metadata name tuakiri.ac.nz test.tuakiri.ac.nz
Metadata distribution point https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-signed.xml
Metadata signing certificate https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem
Federation Registry URL https://registry.tuakiri.ac.nz/ https://registry.test.tuakiri.ac.nz/
Discovery Service / WAYF URL https://directory.tuakiri.ac.nz/ds/DS https://directory.test.tuakiri.ac.nz/ds/DS

Registering an IdP into the Federation Registry

Registrations into Tuakiri are done Using the Metadata Tool. However, as the Metadata Tool uses Tuakiri to authenticate, and before the IdP is registered, you will not likely be able to authenticate, please get in touch with the Tuakiri Service Desk to register your IdP into Tuakiri.

Configuring your IdP to load the federation metadata

The code snippets in this section have values for Tuakiri Production federation. Please update them accordingly as per the table above if configuring your IdP to join the Tuakiri TEST/DEV federation. (The key code snippets are for convenience given in the “Tuakiri-TEST specific” box below).

NOTE: Check what your IdP home directory is: the directory is typically called shibboleth-idp - and on Debian and Ubuntu systems, it’s commonly /usr/local/shibboleth-idp, while on RedHat and CentOS it’s /opt/shibboleth-idp. The snippets below are referring to the IdP home directory as $IDP_HOME

To configure a 3.x IdP to Load the Tuakiri metadata:

  • Configure the IdP to load the Federation Metadata in /opt/shibboleth-idp/conf/metadata-providers.xml by adding the following snippet into the Chaining MetadataProvider.

        <MetadataProvider id="TuakiriMetadata"
                      xsi:type="FileBackedHTTPMetadataProvider"
                  refreshDelayFactor="0.125"
                  maxRefreshDelay="PT2H"
                  backingFile="%{idp.home}/metadata/tuakiri-metadata.xml"
                  metadataURL="https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml">
    
            <MetadataFilter xsi:type="SignatureValidation"
                    certificateFile="%{idp.home}/credentials/tuakiri-metadata-cert.pem"
                    requireSignedRoot="true">
            </MetadataFilter>
            <MetadataFilter xsi:type="EntityRoleWhiteList">
                    <RetainedRole>md:SPSSODescriptor</RetainedRole>
            </MetadataFilter>
    
    </MetadataProvider>
    • Note: validity checking is implicitly turned on, so it is not needed to explicitly add the RequiredValidUntil metadata filter, which would only be useful to reject metadata published with a validity longer then maxValidityInterval milliseconds.  We recommend to rely on signature validation.  The Tuakiri metadata are being generated with a validity of one week.
    • Note: by default, metadata get refreshed only every 3 hours (0.75 factor out of 4 hours maximum refresh interval). 
      • To make metadata changes propagate faster (reload every 15 minutes), set the maximum refresh interval to 2 hours and the factor to 0.125 as above.
      • To avoid re-fetching the file even when not changed, turn on caching (memory caching is enough as we already do have a backing file)
    • See the IDP30 https://wiki.shibboleth.net/confluence/display/IDP30/MetadataConfiguration and https://wiki.shibboleth.net/confluence/display/IDP30/FileBackedHTTPMetadataProvider documentation for more information.
    • Note: in IdP 3.0.0, the RetainedRole element was incorrectly using the namespace samlmd - as of 3.1.1, the namespace declared in metadata-providers.xml and used in the examples is md, consistent with other use.

  • This definition is referring to a certificate used to verify the signature - store the certificate in /opt/shibboleth-idp/credentials

    wget https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.pem

    Note
    Tuakiri-TEST specific

    When building a TEST IdP and registering into Tuakiri-TEST instead, please load instead the Tuakiri-TEST metadata with:

        <MetadataProvider id="TuakiriTESTMetadata"
                      xsi:type="FileBackedHTTPMetadataProvider"
                  refreshDelayFactor="0.125"
                  maxRefreshDelay="PT2H"
                  backingFile="%{idp.home}/metadata/tuakiri-test-metadata.xml"
                  metadataURL="https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-signed.xml">

            <MetadataFilter xsi:type="SignatureValidation"
                    certificateFile="%{idp.home}/credentials/tuakiri-test-metadata-cert.pem"
                    requireSignedRoot="true">
            </MetadataFilter>
            <MetadataFilter xsi:type="EntityRoleWhiteList">
                    <RetainedRole>md:SPSSODescriptor</RetainedRole>
            </MetadataFilter>

    </MetadataProvider>

    and fetch the Tuakiri-TEST metadata signing certificate instead:

    wget https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-test-metadata-cert.pem

Configure attribute release/filtering through the federation

To configure a 3.x IdP to Load the Tuakiri-provided attribute filter:

In the initial IdP deployment for Tuakiri, IdPs were configured to automatically release attributes according to an attribute filter constructed by the Tuakiri Federation Registry, based on attribute request information gathered from the Service Providers (SPs).  This approach would not scale for eduGAIN.

Attribute release for eduGAIN is driven by two separate mechanisms:

  • Research and Scholarship (R&S) entity category: SPs in the R&S entity category expect attributes from a small predefined set to be automatically released by the IdP.  IdPs supporting the R&S category MUST release these attributes.  Tuakiri requires that IdPs joining eduGAIN declare support for R&S and automatically release the R&S attributes to R&S SPs.
  • Metadata-based attribute release: SP requests for attributes can also be recorded in the metadata.  We strongly recommend to configure the IdP to release attributes as requested in the metadata - these requests would have been vetted by the home federation of the SP, and the attribute release is crucial for the login to succeed.

To configure the attribute release:

  • download rns-attribute-filter.xml  and metadata-based-attribute-filter.xml from https://github.com/REANNZ/Tuakiri-public/tree/master/shibboleth-idp/idp into your /opt/shibboleth-idp/conf  :

    wget -O /opt/shibboleth-idp/conf/rns-attribute-filter.xml https://github.com/REANNZ/Tuakiri-public/raw/master/shibboleth-idp/idp/rns-attribute-filter.xml
wget -O /opt/shibboleth-idp/conf/metadata-based-attribute-filter.xml https://github.com/REANNZ/Tuakiri-public/raw/master/shibboleth-idp/idp/metadata-based-attribute-filter.xml

    Warning
    If deploying these rules on a TEST IdP connected to Tuakiri-TEST, edit the downloaded metadata-based-attribute-filter.xml  and change the PoliceRequirementRule  at the top of the file as per the instructions in the file.

  • add the files to the list of attribute filters in /opt/shibboleth-idp/conf/services.xml stored in the shibboleth.AttributeFilterResources list:

        <util:list id ="shibboleth.AttributeFilterResources">
        <value>%{idp.home}/conf/attribute-filter.xml</value>
        <value>%{idp.home}/conf/rns-attribute-filter.xml</value>
        <value>%{idp.home}/conf/metadata-based-attribute-filter.xml</value>
        ...

    Note
    With the metadata-based-attribute-filter.xml  filter in place, the original attribute filter generated by the Federation Registry (loaded by the IdP in the same section) can be removed - it would be only duplicating the metadata-based attribute filter for Tuakiri SPs.  (The only exception are value-specific rules with regular expressions - please contact Tuakiri at tuakiri@reannz.co.nz if your IdP uses these).

    After removing the remotely loaded attribute filter, we recommend to reduce the reload interval of attribute filter files from 15m to 5s (now that all files are local).  In /opt/shibboleth-idp/conf/services.properties , change idp.service.attribute.filter.checkInterval  to PT5S :

    idp.service.attribute.filter.checkInterval = PT5S

    Note that if the Tuakiri-generated attribute filter was loaded from a local file refreshed by an external script (cron job), when no longer loaded this file, the cron job can be (and should be) removed.

  • and restart the IdP to pick up the change:

    service tomcat restart

Now your IdP should be able to access service providers within the Tuakiri federation.

Appendix A - Alternative implementation

Loading the metadata and the attribute filter files from a remote URL makes the IdP depend on the accessibility of the remote URL. While for metadata itself, the IdP software should be sufficiently resilient, for attribute filter configuration, this is not the case. Tuakiri will be running their servers serving these XML files according to best practices. However, some sites may prefer not to take on the risk and put the XML file loading outside of the IdP, into a separate process. This section describes this alternative implementation. This implementation first downloads the XML file into a temporary file on the local machine. Once this is completed it then replaces the original configuration file with the new one, and this will be detected by the IdP and will cause a reload of this file.

This documents an alternative solution to managing refreshes to the metadata and attribute filter files.  The easier solution recommended in the installation manual is to let the IdP manage the refreshes.

This implementation is based on using an external script (fetch-xml.sh). This script loads the XML file (over an HTTPS connection), checks the XML document for well-formedness, optionally verifies the signature on the downloaded XML document - and if all tests are passed, replaces the original file with a single “mv”.

The script takes three arguments: the remote URL, the local file name, and an email address to send any errors to (no email sent if everything goes well).

An extra optional step (documented below) is to install XmlSecTool for verifying the signature. Otherwise, downloading the file over HTTPS and checking the XML structure provides also reasonable guarantees. If using XmlSecTool, the script takes a fourth argument, the certificate to check the signature with. And in this case, XmlSecTool must be found either in the PATH or in the XMLSECTOOL environment variable.

To deploy this solution without XmlSecTool:

  • Download the fetch-xml.sh script into /opt/shibboleth-idp/bin

    wget -O /opt/shibboleth-idp/bin/fetch-xml.sh https://github.com/REANNZ/Tuakiri-public/raw/master/scripts/fetch-xml.sh
chmod +x /opt/shibboleth-idp/bin/fetch-xml.sh
  • Determine the URLs you will be loading the files (metadata and attribute filter) from and locations you will be putting them into - same as in the standard implementation above.

  • Download the metadata signing certificate into $IDP_HOME/credentials:

    wget http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.pem

  • Invoke fetch-xml.sh once to download the metadata:

    /opt/shibboleth-idp/bin/fetch-xml.sh https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml /opt/shibboleth-idp/metadata/tuakiri-metadata-signed.xml errors@institution.domain.ac.nz

  • Invoke fetch-xml.sh once to download the attribute filter for your IdP (note that you have to request one to be published, same as in the standard implementation above):

    /opt/shibboleth-idp/bin/fetch-xml.sh http://directory.tuakiri.ac.nz/attribute-filter/institution.domain.ac.nz.xml /opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml errors@institution.domain.ac.nz

  • Configure a 3.x IdP to load the Tuakiri metadata and atribute filter files:

    • Configure the IdP to load the Federation Metadata in /opt/shibboleth-idp/conf/metadata-providers.xml by adding the following snippet into the ChainingMetadataProvider.

          <MetadataProvider id="TuakiriMetadata"
                      xsi:type="FilesystemMetadataProvider"
                  refreshDelayFactor="0.125"
                  maxRefreshDelay="PT2H"
                  metadataFile="%{idp.home}/metadata/tuakiri-metadata.xml">
        
            <MetadataFilter xsi:type="SignatureValidation"
                    certificateFile="%{idp.home}/credentials/tuakiri-metadata-cert.pem"
                    requireSignedRoot="false">
            </MetadataFilter>
            <MetadataFilter xsi:type="EntityRoleWhiteList">
                    <RetainedRole>md:SPSSODescriptor</RetainedRole>
            </MetadataFilter>
        
    </MetadataProvider>

    • Edit $IDP_HOME/conf/services.xml and add the additional attribute filter as an additional value in the shibboleth.AttributeFilterResources [util:list](http://utillist) bean:

      <value>%{idp.home}/conf/tuakiri-attribute-filter.xml</value> 

  • For archival purposes, we also keep the original instructions for configuring the Tuakiri metadata and attribute filter on a 2.x IdP - unfold the box below to see the IdP 2.x compatible syntax:

    Legacy IdP 2.x syntax for loading metadata and attribute filter
    • Load the metadata from the local file: add the following into $IDP_HOME/conf/relying-party.xml (the variation from the standard implementation above is using a FilesystemResource instead of a FileBackedHttpResource)

      • Add the following snippet into the ChainingMetadataProvider:

                <!-- Tuakiri -->
        <metadata:MetadataProvider id="Tuakiri" xsi:type="metadata:ResourceBackedMetadataProvider">
          <metadata:MetadataFilter xsi:type="metadata:ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
            <metadata:MetadataFilter xsi:type="metadata:SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata"
                            trustEngineRef="shibboleth.MetadataTrustEngine"
                            requireSignedMetadata="true" />
          </metadata:MetadataFilter>
          <metadata:MetadataResource xsi:type="resource:FilesystemResource" file="/opt/shibboleth-idp/metadata/tuakiri-metadata.xml" />
        </metadata:MetadataProvider>

      • Same as in the standard implementation, uncomment the <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature"> element if it is still commented out and add in this snippet to load the metadata signing certificate

                <security:Credential id="Tuakiri-FederationCredentials" xsi:type="security:X509Filesystem">
            <security:Certificate>/opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem</security:Certificate>
        </security:Credential>

    • Load the attribute filter from a local file: Add the following entry into <srv:Service id="shibboleth.AttributeFilterEngine" in $IDP_HOME/conf/service.xml:

              <srv:ConfigurationResource file="/opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml" xsi:type="resource:FilesystemResource" />

  • Create a cron job to periodically (every 2 hours) download the metadata and the attribute filter: run crontab -e and add the following entry (matching the command you had run on the command line earlier):

    02 */2 * * * /opt/shibboleth-idp/bin/fetch-xml.sh https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml /opt/shibboleth-idp/metadata/tuakiri-metadata.xml errors@institution.domain.ac.nz
02 */2 * * * /opt/shibboleth-idp/bin/fetch-xml.sh https://directory.tuakiri.ac.nz/attribute-filter/institution.domain.ac.nz.xml /opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml errors@institution.domain.ac.nz

Optional: Installing XmlSecTool

  • Download latest version (2.0.0 as of July 2016) from http://www.shibboleth.net/downloads/tools/xmlsectool/ into ~/inst
    • Unzip into /opt/xmlsectool-$XMLSECTOOL_VERSION

    • Symlink as /opt/xmlsectool

      export XMLSECTOOL_VERSION="2.0.0"
wget -P ~/inst/ http://www.shibboleth.net/downloads/tools/xmlsectool/$XMLSECTOOL_VERSION/xmlsectool-$XMLSECTOOL_VERSION-bin.zip
cd /opt
unzip ~/inst/xmlsectool-$XMLSECTOOL_VERSION-bin.zip
ln -s xmlsectool-$XMLSECTOOL_VERSION xmlsectool

  • Set JAVA_HOME to your Java installation:

    export JAVA_HOME=/usr/lib/jvm/java

  • Invoke as **/opt/xmlsectool/xmlsectool.sh**

  • Modify fetch-xml.shcron jobs to use XmlSecTool to verify signature:
    • Add /opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem as an additional argument (the certificate to verify signatures with)
    • Prefix the commands with environment variable settings to tell the script where to find XmlSecTool and tell XmlSecTool where to find Java: JAVA_HOME=/usr/lib/jvm/java XMLSECTOOL=/opt/xmlsectool/xmlsectool.sh

    • The final form of the cron jobs is:

      02 */2 * * * JAVA_HOME=/usr/lib/jvm/java XMLSECTOOL=/opt/xmlsectool/xmlsectool.sh /opt/shibboleth-idp/bin/fetch-xml.sh https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml /opt/shibboleth-idp/metadata/tuakiri-metadata.xml errors@institution.domain.ac.nz /opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem
02 */2 * * * JAVA_HOME=/usr/lib/jvm/java XMLSECTOOL=/opt/xmlsectool/xmlsectool.sh /opt/shibboleth-idp/bin/fetch-xml.sh http://directory.tuakiri.ac.nz/attribute-filter/institution.domain.ac.nz.xml /opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml errors@institution.domain.ac.nz /opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem
Documentation