AUSTRALIAN ACCESS FEDERATION
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
4. 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>
5. Ensure your IdP has only one encryption certificate
Some services in eduGAIN will not work with an IdP if the IdP has multiple encryption certificate listed in its metadata. For example the CERN service will only display IdPs that have one and only one encryption certificate. Only users from these IdPs can login to CERN using the organization or institution account option.
Your IdP should only have one encryption key registered at most times, the only exception is during key roll-over which should occur very infrequently at these certificates are long lived.
On occasion at the conclusion of a key roll-over process the old key is not removed from the federation registry even though it is no longer part of the IdP's configuration. The AAF recommends that you verify that your IdP only has the one active encryption certificate registered in the Federation Registry.
To verify your IdP only has the one active encryption certificate registered use the following steps.
- Check the file idp.properties and ensure that idp.encryption.key2 and idp.encryption.cert.2 are commented out
- Check the file credentials.xml and ensure that the key roll over section that references key2 and cert2 above is commented out
- Check that there is only one encryption key registered in the Federation Registry and it is the one referenced by idp.encryption.cert
- Login to the Federation Registry (https://manager.aaf.edu.au/federationregistry)
- Find your IdP
- Goto the SAML / Certificates tab to see the currently registered certificates
- Search for certificates with a Key Type of encryption (there should only be one)
- Compare to the certificate in use by the IdP
- Delete any additional encryption certificates that are not in use by the IdP
Note: The change to the IdPs metadata will take time to propagate around the federation
6. 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
The above test should result in a JSON response with a number of the users attributes including eduPersonScopedAffiliation, eduPersonTargetedID, displayName, surname, givenName and email address.
7. Final Testing
Note: This test can be only perform after your IdPs metadata has been published into the eduGAIN.
To have your IdPs metadata published into the eduGAIN metadata feed you MUST have submitted the Connect to eduGAIN and Request to join eduGAIN for IdPs forms.
4) To check the R&S attribute release, go to : https://release-check.edugain.org/
Note: You only need to include the first test (REFEDS R&S Test), check "No" for other two tests before you click the "Start the test" button otherwise it will throw some errors. If it's successful you will see the consent page and then you will see the test results for your identity provider (see below)
Note: Due to the size of the eduGAIN metadata the IdP may take a little longer to start.
8. Check other eduGAIN services
The AAF does not automatically allow all services providers into the AAF. Only services that have identified themselves as Research and Scholarship and others that have joined the AAF will be accessible to AAF federation IdPs.
Some of the eduGAIN services know to work with IdPs in the AAF are listed below. You can you these services to provide additional verification that your IdP is functioning correctly in eduGAIN.
ORCID - use the Institutional account option
CERN - use the Sign in with your organization or institution account (You may receive an Unauthorized error, as you need to be a registered user).
9. Services not accessible to the AAF
As stated not all eduGAIN services are available to AAF subscribers. If your organisations requires access to such a service please send a request to support@aaf.edu.au with details of the service, reason for inclusion and if possible one or more contacts from the Service Provider that the AAF can use to contact the SP directly.