How to Backup and Upgrade GADS

Many IT infrastructures use Active Directory (AD) for centrally provisioning and deprovisioning users and groups. Google has a tool called Google Apps Directory Sync (GADS) to couple AD with Google Apps so that provisioning and deprovisioning tasks can still be performed from the familiar AD interface.

Google recently announced a significant update to GADS. Currently, it stores the login credentials. The new GADS, version 4.0.2, moves authentication from a stored credential to an OAuth token. With the upgrade, it will assign a single use authentication token unique to GADS, which greatly increases security.

Google previously released an updated API which the new GADS leverages. The legacy API will be deprecated in March 2015.  GADS installations older than 4.0.2 will stop synchronizing to Google after that date.  If you’re currently using GADS, any management tasks performed in AD, such as creating or renaming users, changing email addresses or contact information, and adding aliases will no longer propagate to Google. Agosto strongly encourages you to upgrade your GADS installation to the latest version now to ensure continued functionality.

1.) Log into your local GADS server as the user that initially installed GADS

If this user is unknown, it can be identified by locating the GADS sync scheduled task and identifying the owner of the task.

2.) Open the Configuration Manager

This is typically found under Start > All Programs > Google Apps Directory Sync > Configuration Manager.

3.) Locate your active configuration file

Open the Task Scheduler on the GADS server, and look for a task referencing GADS. Within this task’s actions will be command to launch “sync-cmd.exe”. Within the arguments of this command will be an XML file. This is your active configuration file.

GADS after pt 3.png

4.) Backup the existing config file

The upgrade process will write irreversible changes to the current configuration, so you want to have a safe copy around should you need to roll-back for any reason. Locate the config file on the computer, and make a copy of it. Change the “.xml” file extension of the copy to “.backup” and move it to a safe place that you’ll remember. We highly recommend making additional copies of this file and backing them up to other locations such as Google Drive.

5.) Download the update installer

On the GADS Server, open a web browser, and go to

On this page, you’ll find download links for the GADS tool. Select the appropriate version for your server type, and begin the download.

While the app is downloading, we suggest logging into the Google Apps Admin panel to check your Admin Audit Logs (Reports > Audit > Admin) to confirm which user GADS has been using to perform its administrative updates. This is usually pretty clear by looking for the log entries for the user who is performing the majority of the “User Creation” actions. You’ll ideally want to continue using that same user account, so you’ll need to be logged in as that user.

If you don’t know the password for that user account, be careful. If you change the password on this user, you may cause other applications to fail. You may have other tools like Google Blackberry Enterprise Sync (GBES) and Google Apps Password Sync (GAPS) associated with the same account, and both may rely on that administrator account to accomplish their tasks. It’s very common that one Google account has been used in the setup of all of these applications, if they’ve been deployed.

6.) Log in to Google using the GADS Account

Once you’ve Identified the user GADS has been using to synchronize, you’ll need to log into your primary web browser on the GADS server using that user’s credentials. This is important, as it will be used in the authentication process.

7.) Run the update installer

Launch the installer application you’ve downloaded in step 5. During installation, make sure it installs over of the existing installation of GADS by pointing the installer at the same directory as your current GADS installation.

8.) Launch the new Configuration Manager

Once the installation is completed, head back to the Start menu, and launch the new “Configuration Manager” application in Start > All Programs > Google Apps Directory Sync.

9.) Load and update the config file

GADS will always launch with a default blank template file, so you’ll need to open your config file manually. Go to File > Open, and open the file we identified in step 3. Upon opening your config, the software will let you know that it’s from an old version, and needs to be updated. This is accomplished by simply saving the active file (File Menu > Save).

10.) Re-authenticate the config file

Next, you'll need to re-authenticate. On the left column click “Google Apps Configuration”. From here, click “Authorize Now” and follow the process. As you work your way through the authentication, make sure you’re logged in with the GADS account identified in step 6.

Once you login, you’ll need to accept the authorization, and copy the verification code that you’re presented with. Paste the verification code back into the configuration manager, and click validate. If everything went as planned, the window should close, and you’ll now see “Authorized” in green under the “Authorize Now” button.

GADS b4 pt 11.png

11.) Save the config file

With the authentication handled, you’ll need to save the file. Simply do another File > Save.

12.) Validate the config

Simply click the “Sync” tab on the left hand column. You’ll now see a “Validation results” section that will list each section of the GADS configuration. In the right column, you should be met with all blue check marks indicating that all sections validate properly. If there are any warnings, you’ll have to rectify them before you can move forward.

13.) Perform a sync simulation

Finally, make sure everything updated correctly, so run a sync simulation to verify the next time GADS runs it won’t suspend users inappropriately. To run the simulation, just click “Simulate Sync”.

The Application will gather information from Google Apps and AD, and provide you a list of changes that it intends to make. As long as the changes are in line with expectations, you’re all set!

Contact Agosto for more information.