Child pages
  • Configuring a Shibboleth Identity Provider to join the Tuakiri Federation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: add instructions for loading Tuakiri-TEST 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 Appendix B - the "Tuakiri-TEST Federationspecific" 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

...

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

  • Multiexcerpt
    MultiExcerptNameidp3-load-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.

      Code Block
      xml
      xml
          <MetadataProvider id="TuakiriMetadata"
                            xsi:type="FileBackedHTTPMetadataProvider"
                        refreshDelayFactor="0.125"
                        maxRefreshDelay="PT2H"
                        httpCaching="memory"
                        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="false">
                  </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/HTTPMetadataProvidersFileBackedHTTPMetadataProvider 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.
    Expand
    titleLegacy IdP 2.x configuration to load Tuakiri metadata
    Multiexcerpt
    MultiExcerptNameidp-load-metadata
    No Format
    wget https://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 Blockxmlxml
    • This definition is referring to a certificate used to verify the signature - store the certificate in /opt/shibboleth-idp/credentials

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

     

    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:

    <security:Credential id="Tuakiri-FederationCredentials" xsi:type="security:X509Filesystem"> <security:Certificate>/opt/shibboleth-idp
    • titleTuakiri-TEST specific

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

      Code Block
      xml
      xml
          <MetadataProvider id="TuakiriTESTMetadata"
                            xsi:type="FileBackedHTTPMetadataProvider"
                      
    <!--
    •  
    Tuakiri -->
    •  refreshDelayFactor="0.125"
               
    <metadata:MetadataProvider id="Tuakiri" xsi:type="metadata:ResourceBackedMetadataProvider">
    •          maxRefreshDelay="PT2H"
                      
    <metadata:MetadataFilter
    •  
    xsi:type="metadata:ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
    •  backingFile="%{idp.home}/metadata/tuakiri-test-metadata.xml"
                  
    <metadata:MetadataFilter xsi:type="metadata:SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata"
    •       metadataURL="https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-signed.xml">
      
                  <MetadataFilter xsi:type="SignatureValidation"
                        
    trustEngineRef="shibboleth.MetadataTrustEngine
    •   certificateFile="${idp.home}/credentials/tuakiri-test-metadata-cert.pem"
                          
    requireSignedMetadata
    • requireSignedRoot="
    true
    • false"
    /
    • >
                  </
    metadata:
    • MetadataFilter>
                  
    <metadata:MetadataResource
    • <MetadataFilter xsi:type="
    resource:FileBackedHttpResource
    • EntityRoleWhiteList">
                          <RetainedRole>md:SPSSODescriptor</RetainedRole>
               
    url="
    •    </MetadataFilter>
      
          </MetadataProvider>
      

      and fetch the Tuakiri-TEST metadata signing certificate instead:

      No Format
      wget https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-
    signed
    • cert.
    xml"
    • pem 
    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
    xmlxml
    -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
    titleLegacy IdP 2.x configuration to load Tuakiri metadata
    Multiexcerpt
    MultiExcerptNameidp3-load-attribute-filter
    Multiexcerpt
    MultiExcerptNameidp-request-attribute-filter
    • Contact the federation administrators (by emailing support@tuakiri.ac.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. Once created, the URL will have the form of: https://directory.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml

    Edit $IDP_HOME/conf/services.xml and add the additional attribute filter as an additional resource in the shibboleth.AttributeFilterResources util:list bean, using the built-in FileBackedHTTPResource:

    Code Block
    languagehtml/xml
    Multiexcerpt
    MultiExcerptNameidp-load-metadata

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

      No Format
      wget https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O $IDP_HOME/credentials/tuakiri-metadata-cert.
      pem</security:Certificate>
      pem
    • In $IDP_HOME/conf/relying-party.xml
      • Add the following snippet into the ChainingMetadataProvider:

        Code Block
        xml
        xml
                </security:Credential>
        
        Note
        Remember to uncomment the <security:TrustEngine id="shibboleth.MetadataTrustEngine"
        !-- Tuakiri -->
                <metadata:MetadataProvider id="Tuakiri" xsi:type="
        security
        metadata:
        StaticExplicitKeySignature"> element if it is still commented out (it is commented out in the default configuration).

     

    Configure attribute release/filtering through the federation

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

    Expand
    titleLegacy IdP 2.x syntax to load an attribute filter
      • 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"
                  
    <bean
      •  
    id="TuakiriAttributeFilterResource"
      •  
    class="net.shibboleth.ext.spring.resource.FileBackedHTTPResource"
      •             
    c:client-ref="shibboleth.MemoryCachingHttpClient"
      •  
      •  
    c:
      • url="https://directory.tuakiri.ac.nz/metadata/
    attribute-filter/institution.domain.ac.nz
      • tuakiri-metadata-signed.xml"
                      
    c:backingFile="%{idp.home}/conf/tuakiri-attribute-filter.xml"/>

     

     

    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:

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

    We also strongly recommend you configure your IdP to periodically reload this file - we recommend at 2 hour intervals. 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. 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" +
    Multiexcerpt
    MultiExcerptNameidp-load-attribute-filter

    After requesting the attribute filter:

    • 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
    xmlxml
                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">
               
  • <srv:ConfigurationResource
    •  
    xsi:type="resource:FileBackedHttpResource"
    • <security:Certificate>/opt/shibboleth-idp/credentials/tuakiri-metadata-cert.pem</security:Certificate>
              
    url="https://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
    Code Block
    xmlxml
            <ConfigurationResource xsi:type="resource:FileBackedHttpResource"
                          url="https://directory.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml"
                          file="/opt/shibboleth-idp/conf/tuakiri-attribute-filter.xml" />
    
    
    No Format
    </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).

     

    Configure attribute release/filtering through the federation

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

    Multiexcerpt
    MultiExcerptNameidp3-load-attribute-filter
    Multiexcerpt
    MultiExcerptNameidp-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. Once created, the URL will have the form of: https://directory.tuakiri.ac.nz/attribute-filter/<institution-domain>.xml
    • Edit $IDP_HOME/conf/services.xml and add the additional attribute filter as an additional resource in the shibboleth.AttributeFilterResources util:list bean, using the built-in FileBackedHTTPResource:

      Code Block
      languagehtml/xml
              <bean id="TuakiriAttributeFilterResource" class="net.shibboleth.ext.spring.resource.FileBackedHTTPResource"
                    
    configurationResourcePollingFrequency
    • c:client-ref="
    PT2H0M0
    • shibboleth.
    000S
    • MemoryCachingHttpClient" 
    configurationResourcePollingRetryAttempts="10"
    • 
                    
    xsi
    • c:
    type
    • url="
    attribute-afp:ShibbolethAttributeFilteringEngine">

     

     

    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.

    ...

    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 Production).

    • To download the Tuakiri-TEST metadata signing certificate, run the following command:

      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 loading the Tuakiri-TEST metadata, put the following into relying-party.xml:

    ...

    • https://directory.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
    titleLegacy IdP 2.x syntax to load an attribute filter
    Multiexcerpt
    MultiExcerptNameidp-load-attribute-filter

    After requesting the attribute filter:


    • 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="https://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="https://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 intervals. 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. 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:

      No Format
          <srv:Service id="shibboleth.AttributeFilterEngine"
      +             configurationResourcePollingFrequency="PT2H0M0.000S" configurationResourcePollingRetryAttempts="10"
                   

    ...

    • xsi:type="

    ...

    And the code to load the Tuakiri-TEST metadata signing certificate would be - also in 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>
    

    The snippet to load attribute filter configuration would be (again, drop the srv namespace prefix with Shibboleth IdP 2.1.x):

    ...

    • attribute-afp:ShibbolethAttributeFilteringEngine">
      

     

     

    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.

    Excerpt Include
    Fetching Metadata and Attribute Filter and caching them locally
    nopaneltrue
    Fetching Metadata and Attribute Filter and caching them locally