Moving from an OpenAthens MD IdP to a locally-hosted IdP

This is an old page: kept because some of its content is of relevance when moving from one IdP platform to another.

Many organisations, on first joining the UK federation, handle their identity provision requirements by purchasing an OpenAthens MD subscription. After using this IdP for a year or two, they may decide to move on to deploying their own locally-hosted IdP, and switching the identity provision for their users to that. The following notes are intended to assist in planning such a transition.

The issues covered on this page are also relevant to any organisation considering a change of identity provision from one application to another.

Loss of personalisation - a warning

Most service providers use the eduPersonTargetedID attribute, which the IdP generates from the user's identity and the IdP's entityID, to handle personal customisation and storage of specific information, such as saved links or searches, as well as user's registration information. When you switch identity provision to your new IdP, your users' eduPersonTargetedID attribute values will inevitably change, and it follows that users will no longer have access to their previous personalisations or stored content on some services, and they may have to re-register for others. The consequences here can range from the mildly inconvenient to the potential loss of years of work.

WAYFless URLs

Changing to an IdP with a different entityID, or located on a different server, 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.

Setting the scene

Suppose that at present staff and students of Loamshire College are using an OpenAthens MD IdP to access content in the UK federation. For most services, they select "Loamshire College" from the UK federation central discovery service (the CDS - formerly known as the WAYF) and then authenticate with their Athens credentials.

However, Loamshire College has just deployed its own OpenAthens LA or Shibboleth Identity Provider. (See entity registration for details of how to do this.) The College intends to switch its identity provision to the new IdP once it has been tested.

Once the new IdP has been configured, tested and put into service, from a user's point of view it will work in a similar manner to that of the OpenAthens MD IdP, although on selecting it from a discovery page users will be taken to Loamshire College's own sign-on page and they will authenticate with their College credentials.

Recommended approach

Having both the OpenAthens MD IdP and the College's new IdP visible at the same time in the discovery service could be confusing for users. It is better for only the IdP which is currently providing service to be visible. So the new IdP should be registered in the UK federation with visibility "No", and kept invisible while under development. When it is ready to go into service, it should be made visible and the OpenAthens MD IdP hidden.

Another point to consider is the name of an Identity Provider as it appears in the UK federation CDS; this is known technically as its "Organization Display Name". Such a name must be unique within the UK federation, and this requirement applies whether or not an IdP is hidden from the CDS.

Given these conditions, one way for Loamshire College to proceed is as follows:

Specify the Organization Display Name of its new IdP as "Loamshire College (Testing - do not use)" or similar, and specify its visibility as 'No'.
When the testing period is finished, ask the UK federation to change the Organization Display Name of the OpenAthens IdP to "Loamshire College (Athens)", say, and the new IdP to "Loamshire College". At the same time ask for the OpenAthens IdP to be hidden from the CDS and the new IdP made visible.

By this means, users from the College will only ever see "Loamshire College" in the CDS, although the IdP which it represents has been changed behind the scenes.

Testing the new IdP

How does one test an IdP which is hidden from the CDS?

The following federation page

https://test.ukfederation.org.uk/ (Shibboleth 2 test SP)

can be used for testing. To see all IdPs in the UK federation, including those hidden from the standard federation discovery service, you need to click on the "Search over all sites" link at the bottom right of the page. The output from this page gives details, among other things, of the attributes released by the IdP, and is extremely helpful in diagnosing whether the IdP is performing correctly.

Please do not test a newly-registered IdP against an actual live service, unless you have agreed this with the SP maintainers – a misconfigured IdP may cause problems for some SPs.

Keeping your users informed

When you have finished testing, you need to prepare your users for the transition.

You are advised to give your users as much advance notice as you can of this change. They should take a note of service personalisations, saved searches, etc. that they have made, and then restore the settings once they are able to access the services in question via the new IdP when it comes into service.

It's possible that some users may need to continue to access the older service for a period after the new service has been launched. While it would be possible to allow for this by having both IdPs visible in the central discovery service, it may be less confusing for other users to simply tell them how to access the hidden IdP. (In any case, some Service Providers operate their own discovery services and do not necessarily honour the label in the metadata asking them to hide particular IdPs)

Informing your service providers

Some service providers will automatically detect your new Shibboleth IdP when it is made visible and it will appear in their discovery services, whereas others will need to be informed that you wish to start using the new IdP. It is advisable to check this in advance by contacting your service providers directly.

Summary

In summary, the stages go something like this:

Stage 0: OpenAthens MD IdP in use: not hidden, Organization Display Name of "Loamshire College".
Stage 1: Contact the UK federation helpdesk and ask to register your new IdP: to be hidden from the CDS, and given an Organization Display Name of "Loamshire College (Testing - do not use)" or similar. When it is registered, start testing the IdP within the UK federation.
Stage 2: Check with your SPs to find out whether any of them will need to be informed about the change.
Stage 3: Warn your users about the change: give them the opportunity to record the information which they have saved at SPs.
Stage 4: When you have completed testing of the new IdP, inform any SPs who need to know about the change (as determined at Stage 2).
Stage 5: Ask the UK federation helpdesk to switch the visibilities of the OpenAthens MD IdP and your new IdP, and change the Organization Display Names to "Loamshire College (Athens)" and "Loamshire College".
Stage 6: Once you are satisfied that your new IdP is performing satisfactorily, ask the UK federation helpdesk to delete your OpenAthens IdP.

The UK federation helpdesk can provide support throughout this process; just ask.