Changing the Metadata File for a SAML Authenticator

From time to time it may become necessary to update the metadata file for a SAML Authenticator. It may change because certificates are changing, IDP host names are changing, because the IDP sofware is changing, etc. This article describes the easiest way to change the metadata file for a SAML authenticator that allows for easy fallback in case there are problems and you have to roll back changes.

1. First, obtain the new IDP metadata file. The IDP metadata file is an XML file that contains all the information about how TechDoc should interact with the SAML IDP. The IDP maintainer may email you the file or give you a URL to fetch the file with.
2. Copy the IDP metadata file to D:\TechDoc\etc (changing D: if necessary depending on which drive TechDoc is located on). Choose a different file name if necessary to avoid overwriting any existing file in the folder. Make note of the IDP metadata file name as you will need it later.
3. Now wait until it is time to make the IDP changes take affect.
4. Log into TechDoc with a user account that has Admin privileges.
5. On the top menu bar, click Admin to go to the Admin screen.
6. Select Authenticators... under the Show... section.
7. Click on the lock icon for the SAML authenticator that you are changing the IDP metadata for.
8. Click Modify on the side menu.
9. Edit the Service Data box and change the metadata file name to the new name. The metadata file name is specified in the Service Data box using the -m option. The -m option should be directly followed by the file name with no spaces, drive, or path specified. For example, assume the old Service Data box contains:
   
   -dmydom -moldmetadata.xml -t60 -s -e
   
   Then the old IDP metadata file name is oldmetadata.xml. Let's say that the new IDP metadata file name is newmetadata.xml. Then you would change the example Service data to look like this:
   
   -dmydom -mnewmetadata.xml -t60 -s -e
    
10. Enter a reason and click OK to immediately start using the new IDP metadata file.
11. Test to ensure that the new IDP metadata is working.
12. If not and you decide to roll back the changes, simple modify the Service Data on the Authenticator to change the -m option to specify the old IDP metadata file name again.