Migrating from Shibboleth IdP to the hosted OpenAthens IdP

This page has been created for IdP operators whom are moving from a Shibboleth IdP (including customers on the Jisc Liberate platform which is currently being retired with a SAML IdP instance) to the hosted OpenAthens IdP.

This page assumes that you already have a Shibboleth IdP (or Liberate SAML IdP instance) registered in the UK federation, that you are migrating to the hosted OpenAthens IdP, and that the hosted IdP will have the same entityID as the existing IdP. This means you can generate the same eduPersonTargetedID values and retain personalisations through the migration. We also assume that most of the metadata registered for your IdP remains the same, for example the display name will not change.

Metadata update procedure

  1. A Management Contact for your organisation or the Administrative Contact for the existing IdP must email a request to the UK federation Helpdesk with the information listed below
  2. We will verify this information and perform several technical checks. We may need to communicate with the registrant to rectify any issues.
  3. We then follow an email-based security procedure. The Management Contact or Administrative Contact must reply to our email before we can complete the registration.
  4. Once we have received the authentication email from the Management or Administrative Contact, we will publish your IdP's metadata in the next metadata publishing run, or schedule the change for a future publication. Please note our metadata publication times and that metadata will propagate over the following few hours to the services providers (SPs) your IdP interoperates with.

After publication you verify that your identity provider is properly configured and handling attributes correctly. You can test your IdP using the UK federation test SP before and after the migration to ensure that the released attributes are identical.

Information required for migration

The information required for migration should be provided in the email body of the message as plain text, please do not provide this as an attachment from your office software, if you must provide an attachment please use a text editor. You can use this link to create an IdP migration request email message.

  • entityID
  • User accountability: Specify "yes" or "no". This is a declaration whether the identity provider commits to observe the provisions of 'user accountability', as defined in section 6 of the federation's Rules of Membership. If the hosted Shibboleth IdP uses the same data source as the Shibboleth IdP did, then it's likely to also be able to assert User Accountability. However, please explicitly confirm whether User accountability can still be asserted in your new IdP configuration.
  • Logo URL: The HTTPS-protected URL of an organizational logo, suitable for display on discovery services. It may also appear on a SP's discovery page when a user requires access. Please see the federation MDUI Recommendations page for more information. Please do not send image files; we do not include image files directly in the metadata.
  • Support contact: The name and email address of one or more Support contacts. You may want to include a local email address or the OpenAthens helpdesk (help@openathens.net) or both.
  • Technical contact: The name and email address of one or more Technical contacts. You may want to include a local email address or the OpenAthens helpdesk (help@openathens.net) or both.
  • Administrative contact: The name and email address of one or more Administrative contacts. (This information is not published in the federation metadata.)
  • Automatically generated metadata: The remaining information required for the registration of your IdP is in the metadata generated by your IdP installation. Please attach a file containing the metadata or include a URL where we can download the metadata from (the URL should end with /c/ukfed, and will typically be in the following format https://login.openathens.net/saml/2/metadata-idp/DOMAIN/c/ukfed where DOMAIN is a domain or scope belonging to your organisation, in this scenario that is mostly likely the scope used in the existing IdP registration)
  • Preferred publication date: This will need to be in-line with our metadata publication times, we recommend that requests are submitted at least 5 business days before, we may decline your requested time.

Migration guidance

When moving users from one IdP application to another, it's important for the transfer to be as seamless as possible. The two main causes of disruption are loss of personalisation caused by changes in the value of eduPersonTargetedID (more precisely, the hash value generated from the user credential, salt and the entityID of the SP involved) and failure of direct links to online content due to the failure of WAYFless URLs.

Preservation of eduPersonTargetedID

eduPersonTargetedID is a SAML2 Persistent Name Identifier sent as a SAML attribute called eduPersonTargetedID or urn:oid:1.3.6.1.4.1.5923.1.1.1.10, you should check the values generated for this are consistent before, during and after migration.

WAYFless URLs

Changes to your IdP can result in a need to replace WAYFless URLs used to provide convenient links to SPs' online resources without having to go through the central discovery service, so any such links on portal pages or in your library's online indexes will need to be replaced. Further, some SPs' own discovery services are based around WAYFless URLs, and you may need to contact these SPs to ensure a smooth transfer of service.

You might be able to use the UK federation WAYFless URL generator post-migration to create some new WAYFLess URLs

The URLs to lookout for and work to replace are typically "IdP first", they will reference your IdPs hostname e.g. https://idp.example.ac.uk and then followed by a path being similar to either idp/profile/Shibboleth/SSO?shire= or idp/profile/SAML2/Unsolicited/SSO?providerId=, then followed by either a URL relating to the SP such as AssertionConsumerService Location or an entityID

If you would like further guidance on this please contact us.