The technical configuration of a Shibboleth IdP to connect to eduGAIN has been broken down into three activities described in the KB article. They include;

  • Ensuring you are running the latest stable software
  • Allow for attribute release to service in eduGAIN, and
  • Consuming the AAF eduGAIN metadata.


1. Laster version of software for eduGAIN Identity Providers

What software are you running?

The majority of AAF organisations running an IdPs will be using the Shibboleth IdP software. Please follow the notifications from Shibboleth to ensure you are running the latest, secure and most stable version at all times.


What version are you running?

To determine what version of the Shibboleth IdP software you can run, follow the commands from the bin directory of your Shibboleth IdP installation:


export JAVA_HOME=/usr
./version.sh


Upgrading your software

For IdPs using the AAF Installer please refer to the AAF Installer site for details on upgrading.

 

If you have a current version of Shibboleth, your upgrade path will be based on the documentation available on the Shibboleth wiki.


Does your IdP run with enough memory?

The size of eduGAIN metadata file will continue to grow over time so  IdP needs more memory to load the data. Therefore, we recommend a system with at least 4 GB of memory for an Interfederation-enabled IdP.


Keeping your OS and supporting software up to date

The Identity provider software always operates with a base Operating System, Web Server, crypto software and many other dependent software components. Each of fundamental base software is specific to your environment and will require specific maintenance processes. You need to ensure that these supporting components are regularly patched and upgraded.


2. Attribute Filter for R&S

The following configuration snippets added to your attribute-filter.xml file. This only release attributes to Service providers who assert the R&S entity category.


<!-- for Shibboleth IdP V3.2.0 or later -->
  <AttributeFilterPolicy id="releaseRandSAttributeBundle">
    <PolicyRequirementRule xsi:type="EntityAttributeExactMatch"
      attributeName="http://macedir.org/entity-category"
      attributeValue="http://refeds.org/category/research-and-scholarship"/>
 
  <!-- a fixed subset of the Research & Scholarship Attribute Bundle -->
  <!-- release of ePPN is REQUIRED -->
  <AttributeRule attributeID="eduPersonPrincipalName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- if your deployment of ePPN is non-reassigned, release of ePTID is OPTIONAL -->
  <AttributeRule attributeID="eduPersonTargetedID">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- release of email is REQUIRED -->
  <AttributeRule attributeID="email">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- either displayName or (givenName and sn) is REQUIRED but all three are RECOMMENDED -->
  <AttributeRule attributeID="displayName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="givenName">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
  <AttributeRule attributeID="surname">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
 
  <!-- release of ePSA is OPTIONAL -->
  <AttributeRule attributeID="eduPersonScopedAffiliation">
    <PermitValueRule xsi:type="ANY"/>
  </AttributeRule>
</AttributeFilterPolicy>



3. Consuming eduGAIN metadata

The AAF is providing a separate Metadata feed for eduGAIN which must be consumed by AAF Identity Providers that participate in eduGAIN. The AAF eduGAIN metadata feed contains all authorised entities who can participate with service providers and identity providers within the AAF. These include;

  • All eduGAIN Identity Providers
  • All eduGAIN service providers that identify as Research and Scholarly
  • All other eduGAIN service providers that have been requested by an AAF organisation and approved by the AAF.


Does eduGAIN provide a test environment? 

No, eduGAIN only provides the production environment. You can try it out in the UAT  environment by loading the https://md.test.aaf.edu.au/aaf-edugain-test-metadata.xml available at https://md.test.aaf.edu.au.
However, you won't able to test that your test IdP can connect to eduGAIN services as there is no Test eduGAIN environment available and AAF does not publish test metadata into eduGAIN.  


Production Federation

Identity Providers in the Production federation will use the AAF eduGAIN metadata available at https://md.aaf.edu.au/aaf-edugain-metadata.xml. This metadata is signed by the AAF using the standard AAF SHA256 signing key. You MUST use the public key available at https://md.aaf.edu.au/aaf-metadata-certificate.pem to verify metadata documents whenever it is retrieved.


To download the signing key,


wget https://md.aaf.edu.au/aaf-metadata-certificate.pem -O federation-metadata-cert.pem


To confirm that you have obtained the correct key ensure the file you have downloaded conforms to the following:

$> openssl x509 -subject -dates -fingerprint -in federation-metadata-cert.pem
         subject= /O=Australian Access Federation/CN=AAF Metadata
         notBefore=Nov 24 04:27:20 2015 GMT
         notAfter=Dec  9 04:27:20 2035 GMT
         SHA1 Fingerprint=E2:FC:CC:CB:0E:0F:3B:32:FA:55:87:29:08:DE:E0:34:DA:A2:15:5A


Configuring a Shibboleth IdP

You must allow to incoming metadata from eduGAIN; The following lines are an example of what this should look like:


The following configuration should be added to the metadata-providers.xml file, beneath the AAF federation metadata configuration.

  <!-- eduGAIN metadata -->
  <MetadataProvider id="eduGAINMetadata"
    disregardTLSCertificate="true"
    xsi:type="FileBackedHTTPMetadataProvider"
    refreshDelayFactor="0.125"
    maxRefreshDelay="PT2H"
    httpCaching="memory"
    backingFile="/opt/shibboleth/shibboleth-idp/current/metadata/eduGAIN-metadata.xml"
    metadataURL="https://md.aaf.edu.au/aaf-edugain-metadata.xml">
    <MetadataFilter xsi:type="ChainingFilter">
      <MetadataFilter xsi:type="RequiredValidUntil" maxValidityInterval="P30D" />
      <MetadataFilter xsi:type="SignatureValidation"
        certificateFile="/opt/shibboleth/shibboleth-idp/current/credentials/federation-metadata-cert.pem"
        requireSignedRoot="true">
      </MetadataFilter>
    </MetadataFilter>
    <MetadataFilter xsi:type="EntityRoleWhiteList">
      <RetainedRole>md:SPSSODescriptor</RetainedRole>
    </MetadataFilter>
  </MetadataProvider>


Final Testing

After completing the configurations, we recommended to perform the following tests to see if the IdP is configured properly to load the eduGain metadata.

1) Restart the IdP service and monitor the logs for any errors. If  it is loaded correctly  you will see something like

Loading XML bean definitions from file [/opt/shibboleth/shibboleth-idp/shibboleth-idp-3.3.1/conf/attribute-filter.xml]
2018-06-06 04:20:20,237 - INFO [net.shibboleth.ext.spring.util.SchemaTypeAwareXMLBeanDefinitionReader:317] - Loading XML bean definitions from file [/opt/shibboleth/shibboleth-idp/shibboleth-idp-3.3.1/conf/AAF-eduGAIN-attribute-filter.xml]


2) Check the eduGAIN-metadata file is created at /opt/shibboleth/shibboleth-idp/current/metadata/eduGAIN-metadata.xml
 If there is no eduGAIN-metadata file then you need to check the logs for errors. It may be a file or directory protection issue.

3) You can also perform some additional testing of attribute release using the aacli.sh script. It should output a list of attributes and their values for the user.

./aacli.sh -n VALID-USERNAME -r "https://aai.openminted.eu/proxy/module.php/saml/sp/metadata.php/sso" -u http://localhost:8080/idp


Note: Due to the size of the eduGAIN metadata the IdP may take a little longer to start.