Directory sync imports employees from Microsoft Entra ID (Azure AD) or Google Workspace, keeps their details up to date every day, and archives people who leave your directory. You manage it from People › Employees & Teams.
What you need
- The Professional plan or above.
- A TimeLeaf admin account.
- Single sign-on already set up and active for the same provider under Integrations › Single Sign-On (see Single Sign-On). The directory sync buttons appear on Employees & Teams once it is.
- Microsoft Entra ID: someone who can grant admin consent in your Microsoft tenant (a Global Administrator or Privileged Role Administrator).
- Google Workspace: a Google Cloud project where you can create a service account, and a Google Workspace super admin to authorize it.
Connect Microsoft Entra ID
Open the consent screen
Go to People › Employees & Teams and click Sync Directory. The first time, TimeLeaf opens Grant Directory Sync Permissions.
Add the redirect URI in Azure
In the Azure portal, open your TimeLeaf app registration, go to Authentication › Add a platform › Web, and paste the redirect URI shown in TimeLeaf. It looks like https://<your-workspace>.timeleaf.io/api/admin/directory-sync-consent/callback. Click Configure.
Grant admin consent
Back in TimeLeaf, click Grant Admin Consent and approve on Microsoft's page. The permissions directory sync uses are the Microsoft Graph application permissions User.Read.All, Group.Read.All and Directory.Read.All (the last one reads manager relationships).
Run the first sync
Wait a few minutes for the permissions to take effect, then click Sync Directory again and choose what to import (see Running a sync).
If you prefer to add the permissions in Azure yourself, Setup Help (the question-mark icon in the toolbar) lists them with the API permissions steps. Granting them does not change your client secret or any other permission on the app.
Connect Google Workspace
Google sign-in can't list other people, so Google directory sync uses a service account with domain-wide delegation, set up separately from single sign-on.
Create a service account
In Google Cloud, create a service account (IAM & Admin › Service Accounts), turn on the Admin SDK API for the project, create a JSON key and download it. Turn on domain-wide delegation for the service account and copy its client ID.
Authorize it in Google Workspace
In the Google Admin console, go to Security › API controls › Domain-wide delegation and authorize the client ID with the scope https://www.googleapis.com/auth/admin.directory.user.readonly.
Enter it in TimeLeaf
On People › Employees & Teams, click Directory Sync Settings (the gear icon in the toolbar). Enter the email of a Google Workspace admin for the service account to act as (for example [email protected]), an optional Google Workspace customer ID, and paste the service account JSON key. It is stored encrypted.
Run the first sync
Click Sync Directory and choose what to import.
Running a sync
Click Sync Directory and choose what to bring in. The first sync is always one you start; after that it also runs every day — see Automatic daily sync.
| Option | What it does |
|---|---|
| Employees Only | Syncs employee profiles and job info. Team assignments are left unchanged. |
| Employees and Teams | Also creates TimeLeaf teams from your directory's departments — this can overwrite existing team assignments. |
The status indicator next to the button shows the connected provider, the time of the last sync, whether automatic sync is on, and whether the last run succeeded, is running, or failed. If Entra ID reports an invalid client secret, the same panel lets you paste a corrected secret and retry the sync.
Accounts that are disabled in Entra ID (including room and equipment mailboxes) or suspended or archived in Google Workspace are never imported, so they never take a seat.
Automatic daily sync
Once you have run a sync by hand, TimeLeaf runs it again automatically every day (early in the morning, your company's time), with the option you last chose. Turning off or replacing the SSO connection stops it; run a sync by hand on the new connection to start it again.
Who is imported
Only enabled accounts are imported: disabled (Entra ID) and suspended or archived (Google Workspace) users are skipped.
Guests — Entra ID B2B guest accounts (outside collaborators invited into your tenant) are not imported. A guest who is already in TimeLeaf — because you added them by hand, or they were matched or imported earlier — keeps syncing like anyone else. Google Workspace's directory has no guest accounts, so every Google user it lists is a member.
Your plan's employee limit — every sync, daily or by hand, adds new people only while your plan has free seats. When the limit is reached, the sync stops adding new people (everyone already in TimeLeaf keeps syncing), lists each person it did not import at the top of Employees & Teams, and notifies admins. Upgrade your plan or archive people who have left, and the next sync imports them.
Leavers
When someone TimeLeaf imported or matched from your directory is later removed from it, or disabled or suspended there, the next sync archives them: their status becomes Terminated with today as their leaving date, their sign-in stops at once, and their seat is freed. Someone who is clocked in at that moment stays signed in only to clock out, however long that takes, and is signed out as soon as they do. Their records — timesheets, leave, contracts — are kept. Any leave request of theirs still waiting for a decision is cancelled, so approvers are no longer asked or reminded about it; restoring them does not bring it back. People you added to TimeLeaf by hand and who were never matched to your directory are never touched.
Every archive is listed for review at the top of Employees & Teams, and admins get a notification. From the list you can Restore anyone archived by mistake (the same Restore as on the Archived view) or Acknowledge to clear them. Someone you restore stays active until they reappear in your directory and later leave again.
Safety stop. If one sync finds more than 10% of the directory-linked employees missing or disabled at once (or the directory returns nobody), it archives nobody — a broken connection or a narrowed scope looks exactly like a mass departure. Everyone it would have archived is listed for review instead and admins are notified. Check the directory connection first; if the people really left, archive them from the list.
Held people wait for you. Anyone listed for review without being archived — by the safety stop, a first or re-scoped sync, or because they are protected — stays on the list, and stays active, until an admin chooses Archive or Keep active. Later syncs never archive them on their own, even once the connection looks healthy again. Only new leavers, not held before, are archived automatically (and only under the 10% stop).
The first sync of a directory connection — and the first one after you change which directory it reads (another Entra tenant, Google customer ID or domain, or switching provider) — never archives anyone: people outside a new scope look exactly like leavers, so they are listed for review instead. Run that sync by hand; later syncs archive new leavers again, while the people that first sync listed wait for you to archive or keep them.
The workspace owner and the admins who set up or ran directory sync (and, for Google Workspace, the admin account the service account impersonates) are never archived automatically — they are listed for review instead.
Contract type field mapping
Directory sync can set each employee's TimeLeaf contract type from a field in your directory. Open Field Mapping (the sliders icon in the toolbar) and set:
- Azure AD / Microsoft Graph field — e.g.
employeeType, or an extension attribute such asonPremisesExtensionAttributes.extensionAttribute1. - Google Workspace field — e.g.
employeeType,department,jobTitle, orcompanyName.
Write-back
Write-back pushes an employee's TimeLeaf contract type back to the field it's mapped to in your directory. It's available on Enterprise, off by default, and enabled per provider from Write-back Settings (the checkmark icon in the toolbar).
Write-back only pushes the mapped contract type field — it does not push employment status, job title, or department changes back to your directory.
Troubleshooting
No Sync Directory button. Single sign-on isn't active yet for Microsoft Entra ID or Google Workspace. Set it up under Integrations › Single Sign-On and tick Set as active provider.
The status says the client secret is invalid. The secret in Azure expired or was replaced. Click Update Client Secret in the directory sync status panel, paste the new Client Secret Value from Azure, and sync again.
People were listed for review but not archived. The safety stop or a changed scope held them (see Leavers). Check the directory connection, then choose Archive or Keep active for each.
Someone wasn't imported. They are disabled, suspended or a guest in your directory, or your plan had no free seat. People refused for lack of seats are listed at the top of Employees & Teams.
Someone you erased came back. Remove people from your directory before erasing their details in TimeLeaf; otherwise the next sync adds them again as a new employee.