Do you need to migrate?
Are you running Shibboleth IdP v2.x?
If you are still running any version 2.x of the Shibboleth IdP then you have two options.
- Highly Recommended - Upgrade your IdP to x before the end of October. Go to the AAF IdP Installer for more details on upgrading.
- Modify your IdP x to use the new Metadata source. See the section Migrating Shibboleth IdPv2 below.
Are you running Shibboleth IdP v3.x?
- Please refer to the Migration Guide for Identity Providers – IdP v3.x
Migrating Shibboleth IdP V2.x
There are four tasks to perform which are broken down into simple steps below.
- Change the location which you use to download the metadata.
- Load the new Metadata Signing certificate.
- Modify how your IdP does its Attribute Filtering.
- Verify everything is working.
Note: The AAF now provides a simpler mechanism for Attribute Filtering that is based on data now being provided in the new federation metadata feed. The old method of having the AAF Federation Registry provide individual files to each IdP will be deprecated at some time after the old metadata has been removed.
Step 1: Change the location which you use to download the metadata
Edit the file relying-party.xml
Search for “metadataURL=”
You should see the URL to one of the AAF metadata files. If you are using the old metadata, then the host name will be either ds.test.aaf.edu.au for the AAF Test environment, or ds.aaf.edu.au for the AAF Production environment. For example:
Change the URL
AAF Test environment use:
AAF Production environment use:
Note: The new Metadata source is hosted on AWS's S3 service which has their CDS in front of the that. This means the IP addresses assigned to md.[test].aaf.edu.au will most likely change over time. If your IdP does not have direct access to the entire Internet on port 443 and you have access to a local proxy service then the IdP can be configured to use a proxy service when retrieving the federation metadata. To use the proxy there are a number of optional attributes you can add to the MetadataProvider config... (see https://wiki.shibboleth.net/confluence/display/SHIB2/IdPMetadataProviderfor more details)
Depending on how you proxy is configured will determine which options you require.
Step 2: Load the new Metadata Signing certificate
The new metadata needs to be verified after your IdP downloads it. This ensures that it has not changed in transit across the Internet.
In this step you will be replacing the old metadata signing certificate with a new one. The location of the old metadata signing certificate can be found in the relying-party.xml file.
Find the location of the old metadata signing file, edit file relying-party.xml and search for the MetadataProvider that downloads the federation metadata.
In this section of XML you should find a MetadataFilter with a type of metadata:SignatureValidation. Within this section you should find a trustEngineRef, for example:
Search for the security:TrustEngine that has an id equal to “shibboleth.MetadataTrustEngine”.
In this section you should find the security:Certificate. This will have a file path to the certificate that is used to verify the federation metadata. This is the file that needs to be replaced with the new federation signing certificate.
Download the federation signing key. We are now using the same signing key for both the Test and Production federations. It is available at:
Use the downloaded file to replace the file referenced in the security:Certificate
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 aaf-metadata-certificate.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
Step 3: Modify how your IdP does its Attribute Filtering
The AAF will stop supporting individual IdP Attribute filters in the future. By migrating to the new federation metadata the old IdP Attribute filter you regularly download from the AAF will no longer work.
The new mechanism for IdP attribute filtering that ensures only requested attributes are sent to SPs depends on data provided in the Metadata. Therefore a new attribute filter file is required.
Download the new AAF federation metadata file. The file is called metadata-based-attribute-filter.xml. Two versions have been provided, one for Test and one for production. Ensure you use the correct URL to download the new attribute filter file.
The file should be located in your conf directory and readable by the user that runs IdP process.
To have your IdP load the new file and stop loading the old file you need not modify the file service.xml.
Edit the service.xml file
In this file you will find a Service with an id of shibboleth.AttributeFilterEngine. Within this section you will see a number of srv:ConfigurationResource sections.
First remove the srv:ConfigurationResource that uses a FileBackedHttpResource to download your old IdP specific attribute filter file.
Next, add the following configuration to load the new attribute filter file that is based on data provided by the new metadata file.
<srv:ConfigurationResource file="$IDP_HOME$/conf/ metadata-based-attribute-filter.xml " xsi:type="resource:FilesystemResource"/>
Step 4: Verify everything is working
Restart your IdP and ensure it starts.
Check log files to verify that there are no issues highlighted with the configuration changes.
NOTE: There may be errors loading the metadata from the new source, but the IdP may seem to have started correctly! If these errors can not be resolved you may need to create a separate process (cron job) to download the metadata and have the IdP regularly refresh from the local file.
Verify that the new AAF Federation Metadata has been successfully downloaded. Open the downloaded Metadata file and verify that the first line contains the following:
Test Environment - Name=https://md.test.aaf.edu.au/aaf-test-metadata.xml
Production Environment - Name=https://md.aaf.edu.au/aaf-metadata.xml
Verify that the new attribute filter is working correctly by logging into the Attribute Validator.
Test Environment - https://validator.test.aaf.edu.au/
Production Environment - https://validator.aaf.edu.au/
Your migration to the new AAF Federation Metadata is now complete.
If you have any issues or questions about the upgrade, please email us at firstname.lastname@example.org