For a Shibboleth Identity Provider to join one of the Tuakiri Federations (Test/Dev or Pilot/Production), the following steps have to be done:
There are two federations available, both fully operational:
We recommend first registering a Test system into Tuakiri-TEST and after successful testing, register a production-ready system into Tuakiri Pilot.
Federation name |
Tuakiri |
Tuakiri TEST |
---|---|---|
Metadata name |
|
|
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 |
||
Discovery Service / WAYF URL |
Go to the respecting Federation Registry URL and:
https://idp.example.org
)$IDP_HOME/credentials/idp.pem
).urn:oasis:names:tc:SAML:2.0:nameid-format:transient
is already selected. If supporting SAML1, select also urn:mace:shibboleth:1.0:nameIdentifier
.
|
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
$IDP_HOME/credentials
:
wget http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.pem |
$IDP_HOME/conf/relying-party.xml
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:FileBackedHttpResource" url="http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml" file="/opt/shibboleth-idp/metadata/tuakiri-metadata.xml" /> </metadata:MetadataProvider> |
<security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
element:
<security:Credential id="Tuakiri-FederationCredentials" xsi:type="security:X509Filesystem"> <security:Certificate>/opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem</security:Certificate> </security:Credential> |
Remember to uncomment the |
http://directory.tuakiri.ac.nz/attribute-filter/
<institution-domain>.xml
<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):
<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: if your |
If configuring this in Shibboleth IdP 2.1.x, do not use the srv: namespace prefix - i.e., use just:
|
configurationResourcePollingFrequency="PT2H0M0.000S"
and configurationResourcePollingRetryAttempts="10"
attributes to the <srv:Service id="shibboleth.AttributeFilterEngine"
element.
<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.
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:
/opt/shibboleth-idp/bin
$IDP_HOME/credentials
:
wget http://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.pem |
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.xml errors@institution.domain.ac.nz |
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 |
$IDP_HOME/conf/relying-party.xml
(the variation from the standard implementation above is using a FilesystemResource
instead of a FileBackedHttpResource
)
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> |
<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> |
<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" /> |
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 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 |
~/inst
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 |
export JAVA_HOME=/usr/lib/jvm/java |
/opt/xmlsectool/xmlsectool.sh
fetch-xml.sh
cron jobs to use XmlSecTool to verify signature:
/opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem
as an additional argument (the certificate to verify signatures with)JAVA_HOME=/usr/lib/jvm/java XMLSECTOOL=/opt/xmlsectool/xmlsectool.sh
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 |
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).
wget http://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-test-metadata-cert.pem |
relying-party.xml
:
<!-- Tuakiri-TEST --> <metadata:MetadataProvider id="Tuakiri-TEST" 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.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-signed.xml" file="/opt/shibboleth-idp/metadata/tuakiri-test-metadata.xml" /> </metadata:MetadataProvider> |
relying-party.xml
in the <security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
element:
<security:Credential id="Tuakiri-Test-FederationCredentials" xsi:type="security:X509Filesystem"> <security:Certificate>/opt/shibboleth-idp/credentials/tuakiri-test-metadata-cert.pem</security:Certificate> </security:Credential> |
<srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource" url="http://directory.test.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml" file="/opt/shibboleth-idp/conf/tuakiri-test-attribute-filter.xml" /> |