FileSync - How to Use, What is it, How Does it Work?

SecureAuth IdP Version Affected: All

What is FileSync?: 

The FileSync service is an add-on to the SecureAuth IdP product that can be used to keep configuration information synchronized between members of a cluster.

How Does FileSync Work?:

FileSync can work in either a primary-replica configuration, or a multi-master configuration. Lets go over FileSync terminology before moving forward.

• Cluster: Two or more SecureAuth IdP servers running the FileSync service
• Node: A specific SecureAuth IdP server in a FileSync cluster
• Primary-Replica: In a Primary-Replica configuration, one SecureAuth IdP Appliance is the Primary node and all changes for the cluster are made there
• Multi-Master (3.4.5 and older): In a Multi-master configuration, all SecureAuth IdP Appliances are peers; a change made on any node of the cluster propagates to the rest of the cluster nodes (this feature was deprecated after 3.4.5)

Keep in mind FileSync is a pull service. Changes are propagated to other servers only after a change is made on the primary (in a primary-replica configuration), or after a change is made in general (in a multi-master configuration.)

FileSync 3.4.5 and older cannot create realms/folders. Meaning, if you have SecureAuth6 on your primary appliance, you must create SecureAuth6 using the realm management tool on the replica appliance in order for FileSync to pull the settings.

FileSync 4.0.11 and newer do not have the above limitation.

Default files copied by FileSync:

The SecureAuth0 folder contains a file called Paths.list - this file controls what is actually copied by FileSync.

<path name="web.config" />
<path name="Resource\ClientLanguage.cs" />
<path name="Resource\Language_ar.resx" />
<path name="Resource\Language_cs.resx" />
<path name="Resource\Language_de.resx" />
<path name="Resource\Language_en.resx" />
<path name="Resource\Language_es.resx" />
<path name="Resource\Language_fr.resx" />
<path name="Resource\Language_hu.resx" />
<path name="Resource\Language_it.resx" />
<path name="Resource\Language_ja.resx" />
<path name="Resource\Language_ko.resx" />
<path name="Resource\Language_nl.resx" />
<path name="Resource\Language_pl.resx" />
<path name="Resource\Language_pt.resx" />
<path name="Resource\Language_ro.resx" />
<path name="Resource\Language_ru.resx" />
<path name="Resource\Language_sk.resx" />
<path name="Resource\Language_zh1.resx" />
<path name="Resource\Language_zh2.resx" />
<path name="bin\MFA.SecureAuth.Resource.dll" />

You can add new folders to sync by adding a new key like this:

<path name="Images\" />

This will sync files from the Images folder.  HOWEVER, new files that do not exist previously MUST be placed in the Template realm first before Filesync will start syncing.  The "Template" realm is specified when you install FileSync on the primary server.

For example, if you add company-logo.jpg to Images\ and want to sync it.  When you installed Filesync, you specified SecureAuth1 as the Template realm.  So you will need to copy company-logo.jpg to SecureAuth1\Images\ before FileSync will replicate that to all the realms in the secondary server(s).

How to Use FileSync:

It's important to know the proper way to use FileSync. Keep in mind that in a primary-replica configuration that you should only make changes to the primary server. If the time-stamp on a file is newer on the replica server than the primary server, FileSync 3.4.5 and older will not sync that file; FileSync 4.0.11 and newer WILL overwrite the files on the secondary.

The proper way to use FileSync is as follows:

1. Create a realm on the primary server, using the realm management tool.
2. Create a realm on the secondary server, using the realm management tool. (the realm number should match.)  [NOTE: For FileSync 4.0.11 and newer, you can skip this step]
3. For FileSync 3.4.5 and older, wait the default 10 minutes for it to sync over. You can change this time by referring to this document.
   For FileSync 4.0.11 and newer, the sync interval is set to 1 minute.  This is because FileSync 4.0.11 and newer works by detecting changes and pushing out changed files, rather than having the secondaries doing a file-by-file comparison and pulling the changes.
4. For FileSync 3.4.5 and older, you should always use the realm management tool for creating realms that you plan to use with the FileSync service. There is sometimes an issue present when creating realms through the admin UI where the privileges/permissions won't transfer over from the template realm.
5. For FileSync 4.0.11 and newer, you CANNOT use renamed URLs/vanity realms.  This will break the FileSync process and prevent sync from working.  For example, you cannot rename secureauth23 to appname in order to create the https://your.idp.com/appname as the URL for your users.  This is a known issue and our developers are working to address.
6. For FileSync 4.1.5.6 and newer, you can now use Vanity URL's but when using vanity URL's, it must be created as a new application and the original SecureAuthXXX realm must exist along side the vanity URL.
7. If you are attempting to run SABackupTool, you MUST turn off the FileSync service across all servers, or the backup attempt WILL fail.

Installing FileSync:

Refer to this guide, which is only accessible by internal employees. SecureAuth FileSync services should be installed by a SecureAuth support engineer through a scheduled session.

Warning:

The latest FileSync (4.0.11) is unaware of Windows Server 2016.  You should use 4.0.13 and newer to support Server 2016.

FileSync Documentation:

https://docs.secureauth.com/display/KBA/SecureAuth+IdP+FileSync+Service+Troubleshooting