How to migrate to Keystone from OpenAthens SP
If any of the following are true then you will want your new instance to use the same entityID as your old instance and this page will cover how.
- you have linked anything to the end-users' targeted IDs such as preferences or personalisations
- your customers are sending you anything in addition to a targetedID and scopedAffiliation (they will have actions in their release policy linked to your entityID to do so)
- some of your customers may have restricted access to specific entityIDs (which is a lot more common than you'd expect)
There are three phases of any migration and our service desk will be happy to help during any of them:
If you don't need to keep the original entityID, you only need phases one and two.
Phase 1: Install Keystone and get it ready to take over
Obviously you'll need a Keystone instance to migrate to so what you need to do is a regular Keystone setup alongside your existing authentication options. This might be by expanding an existing OIDC implementation to have one more relying party, or a dedicated instance. Either way, the only difference between a standard installation and getting ready for migration from OASP is that you will use a temporary entityID, and might un-publish the application after all our service desk tests have been passed.
Installation docs:
Our service desk will be happy to help - please mention that you are migrating from another platform so they can advise you better.
Considerations
- Now would be an excellent time to review best practices to give your end-users the most consistent experience
- Whatever domains you use during development, you will want to switch the configuration to the production domains before migrating. One of the configuration items will require internet domains to be unique (on the linking tab), so these will have to be edited at changeover time.
- The entityID has to be different, but only as much as will make it unique - as little as one character added to the end is enough
- You will want to have gone through our approval process (i.e. an initial publish) before starting the migration process in case there are any code changes that need to be made. If you let our service desk know when you expect that to be, they have a better chance of turning it around quickly
- If you choose to un-publish after being approved, our service desk will have to approve the change once more. As long as they know the circumstance this is usually just a formality.
- If you choose not to un-publish after being approved, you won't have to go through approval for any updates, but your application will appear in customer's catalogues which may cause confusion. You should consider a nondescript name for the application in this case
- If you would like to schedule a conference call so your team can discuss any concerns, our service desk will be happy to set that up
Phase 2: Inform customers about any changes
Mutual customers using the OpenAthens Redirector will be unaffected as long as you have configured those settings properly (our service desk will be happy to help), however customers who do not, or who are in other federations, may have set up wayfless or deep links to your pages. As your wayfless and deep linking format has probably changed, you will need to let them all know.
Phase 3: Move entityIDs between systems
Keystone must be set up with the correct internet domains for production, but with a different entityID - adding a number to the end of the live entityID is sufficient.
If you are only in the OpenAthens federation then you can move on to step 2, but if you are using OASP in other federations then you will need to update your OASP connection settings with some details from Keystone before moving on.
- If Keystone is not currently published, push the button and have our service desk approve it. This can be done ahead of the changeover time - if it's going to be several days, consider using a nondescript name and description to avoid confusing customers. If this is the first time it has been published, our service desk will run some tests and you should allow time for this in the schedule in case any of the tests fail.
- When you are ready to swap the entityIDs you will do two saves and two publishes. The order is important as the two instances can't have the same entityID or redirector domains at the same time.
- Change the entityIDs of OASP in the dashboard to something else (adding a number to the end will be enough), and save.
(Connections > relevant connection > SAML Connector section > Click on the entityID) - Change the entityIDs of Keystone in the dashboard to the live entityID, and save
(Connections > relevant connection > SAML Connector section > Click on the entityID) - Switch to the OASP application and:
- Remove at least the domains from any redirector configurations (Linking tab > dots menu > edit or delete)
- Change the name (Details tab)
- Publish.
- Switch to the Keystone application and:
- Add the domain(s) from the redirector configuration you removed from OASP to Keystone (Linking tag > Add application link)
- Check that the name, description and logo are ok and click Publish.
- Change the entityIDs of OASP in the dashboard to something else (adding a number to the end will be enough), and save.
- Update your login page to point to the new method
After the switch
Even when your customers know the date of the change there will be a crossover period where not all of them have made any updates to their Wayfless links and if the format has changed then users may still be hitting OASP instead of Keystone for a while. Dealing with this may be as simple as not turning OASP off for a couple of days, but a redirect for the Wayfless URL is recommended.
FAQ
Will there be any downtime?
None in other federations, but there may be a break of a couple of minutes (no more than 5) for sign-ins from OpenAthens federation IdPs. The process above is designed to minimise that.
How do I roll back if something goes wrong?
Reverse step 3, and point your login page back to the old method.