For a Shibboleth Identity Provider to join one of the Tuakiri Federations (Test/Dev or Pilot/ 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 will be are two federations available, both fully operational:
- Tuakiri TESTTest/Dev (work in progress)
- Tuakiri Prod/Pilot (release date TBA)
- 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.
Federation Details
...
...
...
...
tuakiri.ac.nz
...
test.tuakiri.ac.nz
...
Metadata distribution point
...
https://directory.tuakiri.ac.nz/metadata/metadata-tuakiri.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.test.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
Registering an IdP into the Federation Registry
| Multiexcerpt |
|---|
| MultiExcerptName | register-idp-into-FR |
|---|
|
Go to the respecting Federation Registry URL and: - Register an Organisation for your institution (if not already registered)
- 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. - Submit the details and wait for your IdP to be approved.
|
...
ECP support
If supporting ECP, advertise also your ECP SSO EndPoint:
| Multiexcerpt |
|---|
| MultiExcerptName | idp-register-ecp |
|---|
|
| Note |
|---|
As of version 2.6.0, the Federation Registry automatically registers the ECP endpoint on new registrations, so no explicit action should be required. To add an ECP endpoint to an existing IdP registration, perform the following: |
In the Federation Registry registration for your IdP: |
The IdP also needs to be configured to support ECP.
Configuring your IdP to load the federation metadata
...
The code snippets in this section have values for Tuakiri TEST/DEV Production federation. Please update them accordingly as per the table above - which boils down to removing the "test" component from the file names / URLs in all of the casesif 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:
| Multiexcerpt |
|---|
| MultiExcerptName | idp3-load-metadata |
|---|
|
|
...
metadata-cert.pem -O $IDP_HOME/credentials/tuakiri- |
|
...
...
| Note |
|---|
| title | Tuakiri-TEST specific |
|---|
| When building a TEST IdP and registering into Tuakiri-TEST instead, please load instead the Tuakiri-TEST metadata with: | Code Block |
|---|
| <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: | No Format |
|---|
wget https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-test-metadata-cert.pem
|
|
|
For archival purposes, we also keep the original instructions for configuring the Tuakiri metadata into a 2.x IdP - unfold the box below to see the IdP 2.x compatible syntax:
| Expand |
|---|
| title | Legacy IdP 2.x configuration to load Tuakiri metadata |
|---|
|
| Multiexcerpt |
|---|
| MultiExcerptName | idp-load-metadata |
|---|
|
|
|
...
<security:Credential id="Tuakiri |
|
|
...
...
" xsi:type="security:X509Filesystem">
<security:Certificate>/ |
|
|
...
opt/shibboleth-idp/credentials/tuakiri- |
|
|
...
metadata-cert.pem</security:Certificate>
</security:Credential>
|
|
|
Configure attribute release/filtering through the federation
To configure a 3.x IdP to Load the Tuakiri-managed attribute filter:
| Multiexcerpt |
|---|
| MultiExcerptName | idp3-load-attribute-filter |
|---|
|
| Multiexcerpt |
|---|
| MultiExcerptName | idp-request-attribute-filter |
|---|
| - Contact the federation administrators (by emailing tuakiri@reannz.co.nz) and request a URL for the Attribute Filter for your IdP.
- In the request, please include:
- The name (hostname or entityID) of your IdP
- An email address that should receive notifications whenever the attribute filter changes (these are notifications only, no action will be required).
- The attribute filter may have to be manually added to the list of attribute filters published.
|
|
...
...
tuakiri.ac.nz/attribute-filter/ |
|
...
institution.domain.ac.nz.xml"
c:backingFile="%{idp.home}/conf/tuakiri-attribute-filter.xml"/>
|
- For Tuakiri-TEST, the configuration would be the same, just the URL would be different - please use the URL provided by the federation administrators.
|
For archival purposes, we also keep the original instructions for configuring the Tuakiri-managed attribute filter into a 2.x IdP - unfold the box below to see the IdP 2.x compatible syntax:
| Expand |
|---|
| title | Legacy IdP 2.x syntax to load an attribute filter |
|---|
|
| Multiexcerpt |
|---|
| MultiExcerptName | idp-load-attribute-filter |
|---|
| After requesting the attribute filter:
|
|
...
<srv:ConfigurationResource xsi:type="resource:FileBackedHttpResource"
url=" |
|
|
...
...
tuakiri.ac.nz/attribute-filter/<institution-domain>.xml"
file="/opt/shibboleth-idp/conf/tuakiri- |
|
|
...
...
...
Attribute Filter sections. The simple step is to add the configurationResourcePollingFrequency="PT2H0M0.000S" and configurationResourcePollingRetryAttempts="10" attributes to the <srv:Service id="shibboleth.AttributeFilterEngine"element. If you already have these attributes set for reloading the local configuration file - with a shorter interval, please adjust them accordingly to 2 hours for the remotely loaded attribute filter:
|
|
...
<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 providers within the Tuakiri (Test/Dev) federation.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.
| Excerpt Include |
|---|
| Fetching Metadata and Attribute Filter and caching them locally |
|---|
| Fetching Metadata and Attribute Filter and caching them locally |
|---|
| nopanel | true |
|---|
|