Migration Guide For Identity Providers

Do you need to migrate?

Are you running Shibboleth IdP v3.x?

Did you use the AAF IdP Installer to perform the upgrade?

Yes, then your migration is probably already done.
No, you may need to perform the migration. See section Migrating Shibboleth IdPv3 below.

If you’re running Shibboleth IdP v2.x, please refer to the Migration Guide for Identity Providers – IdP v2.x

Migrating Shibboleth IdP V3.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. If you have upgraded to v3 manually and used your IdP v2 configuration as the starting point you may still be using the old Attribute Filtering which you will need to change.

Step 1: Change the location which you use to download the metadata

Edit the file metadata-providers.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:

https://ds.aaf.edu.au/distribution/metadata/metadata.aaf.signed.minimal.xml

Change the URL

AAF Test environment use:

https://md.test.aaf.edu.au/aaf-test-metadata.xml

AAF Production environment use:

https://md.aaf.edu.au/aaf-metadata.xml

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 will be found in the same section of the metadata-providers.xml you have just edited.

To find the location of the old metadata signing file search from certificateFile in the SignatureValidation MetadataFilter. This will provide the path to your signing certificate.

Download the new federation signing key. We are now using the same signing key for both the Test and Production federations. It is available at:

https://md.aaf.edu.au/aaf-metadata-certificate.pem

Use the downloaded file to replace the file you found above.

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

SHA1 Fingerprint=E2:FC:CC:CB:0E:0F:3B:32:FA:55:87:29:08:DE:E0:34:DA:A2:15:5A

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.

Test: https://md.test.aaf.edu.au/v3/metadata-based-attribute-filter.xml

Production: https://md.aaf.edu.au/v3/metadata-based-attribute-filter.xml

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 services.xml.

Edit the services.xml file and add the following configuration to load the new metadata based attribute filter.

<util:list id ="shibboleth.AttributeFilterResources">

<value>%{idp.home}/conf/metadata-based-attribute-filter.xml</value>

<value>%{idp.home}/conf/attribute-filter.xml</value>

</util:list>

Step 4: Verify everything is working

Restart your IdP and ensure it starts.

Check log files to verify that are no issues highlighted with the configuration changes.

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 support@aaf.edu.au

Have more questions? Submit a request