...

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 will be are two federations available, both fully operational:

Tuakiri Test/Development Environment (Operational and available now)Environment (Tuakiri-TEST) for testing deployments and developing new features
Tuakiri Pilot Federation Service (Available from the 7th June11)

Table of Contents

outline	true
indent	20px

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

Table of Contents

outline	true
indent	20px

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/federationregistry/	https://registry.test.tuakiri.ac.nz/federationregistry/
Discovery Service / WAYF URL	https://directory.tuakiri.ac.nz/ds/DS	https://directory.test.tuakiri.ac.nz/ds/DS

...

Register an Organisation for your institution (if not already registered)

Wait for the Organisation to be approved
Register your IdP under that Organisation
- Provide the Contact Details for the IdP admin
- Select the organisation and provide a name and description for your IdP
- Enter the base URL for your IdP (https://idp.example.org)
- Enter the PEM encoded certificate used by your IdP for signing Shibboleth assertions (the default is $IDP_HOME/credentials/idp.pem).
- Select the For Contact Details, do not use a shared mailbox, alias or mailing list when entering an email address because the confirmation email contains a single-use link and may cause some confusion should more than one person attempt to use it
- For Organization Name, enter your DNS domain name.
- For Organization Display Name, enter your actual organization name.
Wait for the Organisation to be approved

Register your IdP under that Organisation

Provide the Contact Details for the IdP admin (again, do not use a shared mailbox)
Select the organisation and provide a name and description for your IdP
Enter the base URL for your IdP (https://idp.example.org)
Enter the PEM encoded certificate used by your IdP for signing Shibboleth assertions (the default is $IDP_HOME/credentials/idp.pem).
Select the attributes the IdP will be able to release to the federation
Select supported NameID formats. By default, urn:oasis:names:tc:SAML:2.0:nameid-format:transient is already selected. If supporting SAML1, select also urn:mace:shibboleth:1.0:nameIdentifier.
Submit the details and wait for your IdP to be approved.
After having your IdP registration approved, click on the link sent to you to become an Administrator of the IdP's registration.
If supporting SAML1, define the SAML1 endpoints for your IdP.
Configuring your IdP to load the federation metadata:
The code snippets in this section have values for Tuakiri (Pilot) 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 Appendix A - Tuakiri-TEST Federation 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
- Download the metadata signing certificate into $IDP_HOME/credentials:
No Format
wget http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.pem

In $IDP_HOME/conf/relying-party.xml

Add the following snippet into the ChainingMetadataProvider:  <metadata:MetadataProvider id="Tuakiri" xsi:type="

Code Block

xml

Note

title	Confirmation email

It is important to click on the link in the confirmation email, as this makes the recipient of the email an administrator of the Identity Provider being registered in the Tuakiri Federation Registry.
- The link in the confirmation email can only be used once.
- Same applies for the link sent for the Organization registration.

If supporting SAML1, define the SAML1 endpoints for your IdP.

Configuring your IdP to load the federation metadata:

The code snippets in this section have values for Tuakiri (Pilot) 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 Appendix B - Tuakiri-TEST Federation 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

Download the metadata signing certificate into $IDP_HOME/credentials:

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

In $IDP_HOME/conf/relying-party.xml

Add the following snippet into the ChainingMetadataProvider:

Code Block

	xml
	xml


        <!-- 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:FileBackedHttpResource"
                          url="http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml"
                          file="/opt/shibboleth-idp/metadata/tuakiri-metadata.xml" />
        </metadata:MetadataProvider>

And add the following snippet into the <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature"> element:

Code Block

	xml
	xml

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

Note
Remember to uncomment the `<security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">` element if it is still commented out (it is commented out in the default configuration).

...

Add the following entry into <srv:Service id="shibboleth.AttributeFilterEngine" in $IDP_HOME/conf/service.xml (note that the URL varies for each IdP and has to be obtained from the federation administrators):

Code Block

	xml
	xml

        <srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                              url="http://directory.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml"
                              file="/opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml" />

Note
Note: if your `$IDP_HOME` is different from `/opt/shibboleth-idp`, change the file path in the above snippet accordingly.

Note

If configuring this in Shibboleth IdP 2.1.x, do not use the srv: namespace prefix - i.e., use just:

Code Block

	xml
	xml

        <ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                      url="http://directory.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml"
                      file="/opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml" />

We also strongly recommend you configure your IdP to periodically reload this file - we recommend at 2 hour interval. This is documented in detail in the IdP Install Manual: Reloading configuration section and Load AAF Atribute Filter sections. The simple step is to add the configurationResourcePollingFrequency="PT2H0M0.000S" and configurationResourcePollingRetryAttempts="10" attributes to the <srv:Service id="shibboleth.AttributeFilterEngine" element.

No Format

    <srv:Service id="shibboleth.AttributeFilterEngine"
+             configurationResourcePollingFrequency="PT2H0M0.000S" configurationResourcePollingRetryAttempts="10"
             xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">

Now your IdP should be able to access service provides within the Tuakiri (Test/Dev) 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 the 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 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 IdP would then detect a change and reload the file.

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 attached fetch-xml.sh script into /opt/shibboleth-idp/bin
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:

No Format
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:

No Format
/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

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

No Format
/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

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:

Code Block

	xml
	xml


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

Code Block

	xml
	xml


        <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:
Code Block
xml
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):

No Format


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

Optional: Installing XmlSecTool

Download latest version (1.1.5 as of September 2011) from http://www.shibboleth.net/downloads/tools/xmlsectool/latest/ into ~/inst

Unzip into /opt/xmlsectool-$XMLSECTOOL_VERSION

Symlink as /opt/xmlsectool

No Format


export XMLSECTOOL_VERSION="1.1.5"
wget -P ~/inst/ http://www.shibboleth.net/downloads/tools/xmlsectool/latest/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:
No Format
export JAVA_HOME=/usr/lib/jvm/java
Invoke as /opt/xmlsectool/xmlsectool.sh

Modify fetch-xml.sh cron 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:

No Format


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

xsi:type="attribute-afp:ShibbolethAttributeFilteringEngine">

Now your IdP should be able to access service provides within the Tuakiri (Test/Dev) federation.

...

errors@institution.domain.ac.nz /opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem

Appendix B - Tuakiri-TEST Federation

This section gives the variants of the commands to be used when configuring the IdP to join the Tuakiri-TEST Federation (instead of Tuakiri Pilot).

...

Child pages

Versions Compared

Old Version 6

New Version 7

Key

Federation Details

Configuring your IdP to load the federation metadata:

Configuring your IdP to load the federation metadata:

Appendix A - Alternative implementation

Optional: Installing XmlSecTool

Appendix B - Tuakiri-TEST Federation

Child pages

Page History

Versions Compared

Old Version 6

New Version 7

Key

Federation Details

Configuring your IdP to load the federation metadata:

Configuring your IdP to load the federation metadata:

Appendix A - Alternative implementation

Optional: Installing XmlSecTool

Appendix B - Tuakiri-TEST Federation