Set up Active Directory sync

5 steps 7 min Updated 6 November 2026

On-prem Active Directory works differently from Google and Entra. Instead of Realsmart reaching out to a cloud service, you install a small connector app on a Windows Server at your school. That app pulls the user data Realsmart has prepared for your school and applies it to your local Active Directory. It links to Realsmart using your School ID and a secret connector token.

This page walks the core install. There is also a fuller, external step-by-step guide linked from the page (and in step 5) if you want more depth — but the steps below stand on their own.

Before you start

You must be a school admin with sync settings permission, with the school selected in the switcher. Downloading the application (Step 2) also needs permission to export data; if you get a permission error, ask a full admin to download it for you.
Turn Active Directory on first under School settings → Sync services — enabling it is what generates your connector token. See Enable or disable sync services.
You need access to a Windows Server on your school network that can reach your domain controllers, and permission to install and run software on it.

Steps

Step 1: Check the server prerequisite (.NET 6)

The connector needs at least .NET 6 installed on the server you will run it on. If it isn't already there, install it from Microsoft's .NET downloads page (the app's getting-started screen links to it directly). Without .NET 6 or later, the connector will not start.

Step 2: Download the AD sync application

In the sidebar, go to Active Directory → Getting started. The page is called Active Directory — getting started; select Download a copy of the AD sync application. This downloads a zip file (realsmart.adsync-win-Portable.zip) containing the connector. (Active Directory → Status is a simpler page that only says whether Active Directory is enabled; its Configure settings button opens the older settings screen, so use Active Directory → Settings instead.)

Step 3: Turn on test mode, then unzip and run adsync.exe

IMPORTANT — before your first run, turn on Test mode in Active Directory settings (General section). In test mode, the export appends _tst to every username, email address and OU path it produces, so any objects the connector creates from that run are unmistakably test data — easy to find and clean up if something isn't right, rather than mixed in with your real accounts. In test mode, names that would pass AD's 20-character limit are shortened to 16 characters before _tst is added, so the suffix is never lost. Turn test mode off once you're happy with a test run and ready to go live.

Copy the downloaded zip onto your Windows Server and unzip it there. In the unzipped folder, right-click adsync.exe and select Run as administrator — the connector needs administrator rights to run correctly. If Windows shows a security warning ("Windows protected your PC"), select More info, then Run anyway, to proceed. Then follow the on-screen instructions.

Step 4: Enter your School ID and connector token

When the app prompts for them, enter the two values shown on the Active Directory — getting started page:

School ID — your school's numeric ID.
Connector token — the secret token that authenticates this connector to Realsmart. On the page it is shown masked; use Reveal to see it and Copy to copy it, then paste it into the app. Treat it like a password — keep it secret.

Connector credentials card showing the School ID and a masked connector token with Reveal and Copy buttons

Both values are on that page together, so keep it open while you configure the app.

Step 5: Finish setup and verify

Complete the on-screen setup. Once the connector is running and linked, you can:

Check exactly what it will write using Preview the Active Directory export.
Fine-tune where accounts are placed and how they're named in Active Directory settings.
Follow the full setup guide linked on the page for advanced scenarios (multiple domains, scheduling, service accounts, and troubleshooting the connector itself).

After a run, the connector reports back to Realsmart. If the run created new accounts, an email titled AD Sync - Recent Imports goes to the Email in the Technical box under School settings → Details → School contacts, listing each new account (username, OU, time, and whether test mode was on). A run that creates nobody sends no email. Make sure that address is current so someone actually sees the notification. The date the connector last finished a full run shows as Connector last ran on AD password updates.

If the connector stops running

If the connector hasn't finished a run for 48 hours, Active Directory → Status says so and the Sync status page marks it Stopped running. Realsmart can also alert you with a notification and an email to the Technical contact. You get one email each time it stops, and won't get another until it has run again. This is paused during the end-of-year freeze, and it doesn't apply until the connector has run for the first time.

Changing the connector token stops the connector straight away, until the new token is added to its rssettings.json. That's deliberate, so that a token changed for security can't keep working. You'll still get this alert, because Realsmart can't tell a deliberate stop from a broken server.

This tells you the connector has stopped, not that a run went well. A run that finishes still counts even if some users failed, and those are listed in its log file.

How and when the connector runs

Realsmart doesn't start the connector: it runs when your server's scheduled task starts it (the full setup guide covers scheduling), so how often depends on how you set that up. Each full run downloads the people and settings Realsmart has prepared, creates and updates accounts in your AD, tells Realsmart what it created, then collects any waiting password changes (see Sync passwords to Active Directory). A password-only run (started with --password-only) skips the account work. The connector updates itself when it starts, only runs one copy at a time, and stops a run that goes over six hours (MaxRunHours in its settings file) so the next scheduled run can start.

During the end-of-year pause Realsmart gives the connector nobody to sync: the member feed answers that Active Directory sync is paused for the school during the end-of-year provisioning freeze, and says when it resumes. Nothing is lost; see The provisioning window and the freeze.

If something isn't right

The connector writes a log file for every run to the logs folder next to its settings file (rssettings.json) in its install folder, named like AdSyncLogs.2026-11-04.09-00-00.log. Send the latest one to Realsmart support if you need help. What you might see:

What you see	What it means	What to do
Another AD sync is already running - exiting.	An earlier run hasn't finished (or a second copy was started).	Wait for it, or end the old `adsync` process if it's stuck.
No users found to import / Failed to import CSV. Please recheck token and school ID.	The connector got nobody to import. The School ID or token is wrong, or the school's export is empty (staff and student processing off, everyone excluded, or the school is in the end-of-year pause).	Check the School ID and token on the Getting started page, then open Preview the Active Directory export to see whether anyone would be exported.
Username … for … is already used by a disabled AD account for … — not enabling it. Rename or remove the old account, or change the username in Realsmart.	A new person's username already belongs to a disabled account of someone with a different name (a leaver, say), so the connector skipped them rather than hand over that account.	Rename or remove the old account in AD, or change the new person's username in Realsmart.
A person isn't created and their username is more than 20 characters	AD usernames are limited to 20 characters, so the connector shortens them; two long names that shorten the same way clash.	See Preview the Active Directory export.
SchoolID or Token not set … not syncing	The connector can't find its settings file, or the School ID or token is blank.	Enter both on the connector's first-run prompt (Step 4), or fix `rssettings.json`.

Managing the token later

The connector token is managed under School settings → Sync services, where you can Reveal, Copy, or Regenerate it. Regenerating immediately invalidates the old token, so if you regenerate you must update the connector app with the new value or its sync will stop working. See Enable or disable sync services.

Did this work for you?

If a step looked different on your site, tell us and we'll update the screenshots.