Switch from one SAML IDP to Another With Minimal Impact to Users

You can switch from one SAML Identity Provider (IDP) or even the type of authentication service an authenticator uses with minimal impact to your system or your users. For a major infrastructure change, it can take a while before the new infrastructure is ready and everyone can be transitioned over. So how do you test possibly for a long period of time and then quickly transition users over when your ready?

Consider the following scenario...

You have a SAML authenticator called XYZ that is your preferred method of authentication. It is currently configured to use a SAML-based product called Product_1. Your company has decided to discontinue Product_1 and transition everyone to authenticate using Product_2. Once your company has set up Product_2 and copied the user accounts from Product_1 to Product_2, you are ready to test and then switch your users. Here are the step-by-step instructions on what you would do:

1. Work with the group that is setting up the new SAML IDP to get your TechDoc server authorized as a SAML Server Provider (SP). If they need TechDoc's SP metadata, you can log into your TechDoc server as an Admin, click Admin, and then click Authenticators under "Show...". On the side menu, you will see the "SAML Metadata" link that will fetch your TechDoc server's SP metadata. You can send them that link or you can right click on the link, save it as an XML file, and provide the XML file to them.
2. Obtain the SAML metadata file for the new Product_2 SAML IDP and copy it to the \TechDoc\etc folder on your TechDoc server and note the file name. Do NOT overwrite the current SAML metadata file for the old Product_1 IDP as you still need it for now.
3. Log into TechDoc as a local user with Admin privileges. It is important to have access to a locally authenticated Admin account. If your Admin account is tied to XYZ or the new authenticator and something breaks, you may not be able to log back into TechDoc to fix it.
4. Create a new TEST authenticator with the settings to work against the new Product_2 SAML IDP and assign a couple of people to that authenticator for testing.
5. Perform testing against the new TEST authenticator to verify that everything is working. If you have trouble with the new SAML IDP, here is a FAQ topic that can help. It provides tips for configuring and debugging SAML authenticators.
6. Make note of the current Service Data setting on the XYZ authenticator while it is still configured for Product_1. That way if you run into trouble with Product_2 after you go live, you change always modify XYZ back to the Product_1 settings to "move" all the users back to Product_1 until the problem(s) can be resolved.
7. Once testing is complete and you are ready to make the switch for everyone on the system, just modify the Service Data setting on the XYZ authenticator to have the same Service Data setting as the TEST authenticator.
8. Modify the couple of test people to change them from the TEST authenticator to the XYZ authenticator.
9. Change the DefaultAuthenticator in System Properties back to XYZ if you had changed it to TEST as part of testing.
10. Delete the TEST authenticator.
11. If you enabled logging on the authenticator, remember to remove the -l (lowercase L) on the Service Data setting of the XYZ authenticator when you are no longer testing. That causes logging of the entire authentication process every time someone authenticates. If left on for a busy system, the TechDoc log files can grow very large!