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:

• Integrate OpenAthens Keystone

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.

1. 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.

   How do I quickly check if I'm in other federations?

   1. Go to the connection used by your OASP application (Connections > relevant connection) and scroll to the bottom.
   2. In the Identity providers section, look for any that have a green icon saying Active. They'll be at the top of the list if you have any, and if you do then you are active in other federations 
   3. If you only see switches set to 'Deny' or icons saying 'Error', then you are not active in other federations with this OASP instance.
   How to update your OASP connection settings

   1. First you need to view the metadata of your Keystone connection:
      1. Publisher dashboard > Connections > Relevant connection > dots menu next to the entityID > View
         
         
   2. Copy the certificate
      
      
      1. The certificate is between the tags <ds:X509Certificate> and </ds:X509Certificate>. There are two certificates in the metadata, but they're the same.
         
         
      2. Manually add '-----BEGIN CERTIFICATE-----' before the first line and '-----END CERTIFICATE-----' below the last (there are 5 dashes).
          
   3. Copy the AssociationConsumerService location
      
      
      1. This is near the bottom on a line that starts '<md:AssociationConsumerService Binding=...' and will start 'https://connect.openathens.net...'
         
         
   4. Now change to your OASP instance's connection
      
      
      1. In the SAML connector section click on 'Add a certificate' and paste in the certificate you copied earlier including the begin and end certificate tags.
         
         
      2. Now click on the dots menu beside the entityID and select the endpoints option. This will default to a SAML 2 POST ACS endpoint, which is what we want. Paste in the location URL from earlier and click done.
         
         
      3. Click Save changes at the top of the page.
         
         
   5. OASP will pick up the changes the next time the webserver is restarted. You will be able to check by looking for the changes to appear at https://YOURDOMAIN/oa/metadata.
      
      
   6. Contact each federation you are a member of and have them update your metadata. Passing them a copy of your metadata or the link to it is usually helpful. Some may ask you to read them the certificate thumbprint over the phone and you can see this by hovering over the certificate in the publisher dashboard.
      
      
   7. Ensure the change is live in each federation before moving on to step 2 below.
2. 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.
   
   
3. 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. 
   
   
   1. 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)
      
      
   2. Change the entityIDs of Keystone in the dashboard to the live entityID, and save
      (Connections > relevant connection > SAML Connector section > Click on the entityID)
      
      
   3. Switch to the OASP application and:
      1. Remove at least the domains from any redirector configurations (Linking tab > dots menu > edit or delete)
      2. Change the name (Details tab)
      3. Publish.
         
         
   4. Switch to the Keystone application and:
       
      1. Add the domain(s) from the redirector configuration you removed from OASP to Keystone (Linking tag > Add application link)
      2. Check that the name, description and logo are ok and click Publish.
         
         
4. 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.