Sync people from Microsoft Entra ID
Register an app in Microsoft Entra ID and Polzy reads your directory on a schedule: members arrive with their department, office and manager, and disabled accounts stop receiving surveys.
On this page
Connect Microsoft Entra ID as a people source and Polzy reads the users in your directory through Microsoft Graph, on a schedule. New users arrive as members of this workspace with their job title, department, office and manager; changes follow at the next sync; and accounts you disable or delete stop receiving surveys.
People sync is on Team and up, and only workspace admins can connect a source. Polzy only reads your directory: it never changes a user in Entra ID.
Sync, SCIM or single sign-on?
Polzy connects to Microsoft Entra ID in three ways, for three different jobs:
- Directory sync (this article). Polzy reads users from Entra ID into one workspace on a schedule, with the attributes you group results by — department, office, job title, manager. Team and up, set up by a workspace admin.
- SCIM provisioning. Entra ID pushes members to your organization the moment they change, and places them in workspaces by group. Enterprise, set up by the Owner — see SCIM.
- Single sign-on. People sign in to Polzy with their Microsoft account instead of a password. It decides how people sign in, not who is in a workspace. Enterprise, set up by the Owner — see Single sign-on.
Single sign-on works with either of the other two. Directory sync and SCIM cannot run in the same organization: while it has a SCIM token, no workspace can connect a people source.
Before you start
You need:
- To be an admin of the Polzy workspace, on Team or higher, with People sync switched on under Settings → General → What this workspace does.
- In Microsoft Entra ID, a role that may register applications, and someone who may grant admin consent, such as a Cloud Application Administrator.
- The fields you want to group results by already added in Polzy, such as Department or Office.
A workspace syncs from one source at a time. If another source is connected, disconnect it first.
Register an app in Microsoft Entra ID
- In the Microsoft Entra admin center, go to Entra ID → App registrations and choose New registration.
- Name it Polzy, choose Single tenant only under Supported account types, and choose Register. No redirect address is needed.
- On the app's Overview, copy the Application (client) ID and the Directory (tenant) ID.
- Open API permissions, choose Add a permission → Microsoft Graph → Application permissions, select
User.Read.Alland choose Add permissions. - Choose Grant admin consent for your organization, and confirm. The permission's status turns to granted.
- Open Certificates & secrets → Client secrets → New client secret. Give it a description and an expiry, and choose Add.
- Copy the secret's Value at once — not its Secret ID. Microsoft never shows it again.
Secrets last two years at most. Put a reminder in your calendar a few weeks before yours expires: when it does, syncing stops until you paste a new one. See Microsoft: Register an application, Microsoft: Add an application permission and grant admin consent and Microsoft: Add a client secret.
Connect Entra ID in Polzy
- Open Contacts → Sync & fields.
- Under Available sources, find Microsoft Entra ID and choose Connect. A panel opens with three steps: Connection, Sync settings and Field mapping.
- Paste the Tenant ID (the directory ID), the Application (Client) ID and the Client Secret value.
- Choose Test connection. A message starting Successfully connected to Entra ID means Polzy could read your directory.
- Choose Next, check the sync settings (see below), and choose Next again.
- On Field mapping, keep the default mapping or switch on Custom field mapping (see below), then choose Connect.
The secret is stored encrypted and is only used to read your directory. Polzy checks it again when you choose Connect: if Microsoft refuses it, nothing is saved.
Sync settings
| Setting | What it does | Default |
|---|---|---|
| Sync Frequency | How often Polzy reads Entra ID: every 15 minutes, every 30 minutes, every hour, every 4 hours or daily. | Every hour |
| Disable Removed Users | Someone Polzy brought in from Entra ID who no longer appears there is deactivated at the next sync. | On |
| Send Invitation Emails | New members get an invitation to sign in to Polzy. | On |
| Default Role for New Users | The role new members get: Viewer, Editor or Admin. It applies only to people the sync creates. | Viewer |
| Filter Query (Optional) | Reads only the users that match a Microsoft Graph filter, such as department eq 'Sales'. Empty, Polzy reads every member of your directory and leaves guests out. | Empty |
| Save Raw Data for Debugging | Keeps a copy of each user as Microsoft sent it beside the person in Polzy. Leave it off unless you are troubleshooting a mapping: it stores more personal data than you need. | Off |
A filter you write replaces the one that leaves guests out. To keep guests out, add it yourself: userType eq 'Member' and department eq 'Sales'. Polzy sends the filter as it is, so use the simple filters Microsoft Graph accepts on users without advanced queries, such as eq, in and startswith. See Microsoft: Use the $filter query parameter.
Map the fields
The default mapping fills:
| Polzy field | From Entra ID |
|---|---|
userPrincipalName | |
| First name, last name | givenName, surname |
| Job title, department | jobTitle, department |
| Office | officeLocation |
| Phone number | mobilePhone |
| Employee ID | employeeId |
| Active status | accountEnabled |
| Manager | the manager's userPrincipalName |
If your people sign in with a name that is not their email address, switch on Custom field mapping and map Email to mail instead. Each row also has an If empty, use value, written when Entra ID has nothing for that person — a value it does send is never overwritten. Polzy reads these attributes of each user: userPrincipalName, mail, givenName, surname, displayName, jobTitle, department, officeLocation, mobilePhone, employeeId, accountEnabled and the manager.
A few things to know:
- Only your workspace's fields are filled. Department or office are kept only if your workspace has a field with that name. Add one with Add field on Sync & fields, then map it.
- Groups. To compare results by a field, make it a List field and switch on Groups beside it in the Field mapping table. Values from Entra ID are matched to the field's options.
- Real examples. Once connected, choose Settings on Sync & fields and open Field mapping again: the list then comes from five real users, each with an Example.
- Managers. The manager is linked when they are in Polzy too. If they are not there yet, the link is made at a later sync. Managers need Reporting lines switched on in the workspace.
Preview and run the first sync
- On Sync & fields, choose Preview a sync under Sync history. Polzy works out what a sync would add, update and deactivate, without changing anything, and opens the log where the result appears as Preview.
- Check the preview. If the wrong people would arrive, adjust the Filter Query under Settings and preview again.
- Choose Sync Now. The result appears in Sync history.
People are matched by their Entra ID object ID, and then by email address, so someone you had already invited by hand is updated rather than added twice.
Schedule and sync history
After the first sync Polzy runs on its own, at the frequency you chose, give or take a few minutes. When Microsoft asks Polzy to slow down, it waits as told and carries on. Sync history lists the last five runs — Success, Partial (some people were skipped or failed), Failed or Preview — and Full log opens every run, with each change it made.
If a sync fails, Polzy tries again later, waiting longer each time. After three failures in a row, or straight away when Microsoft refuses the credentials — an expired secret, or consent taken back — the source shows Needs attention and admins are told. Sync Now works again once the source is connected: paste a new secret under Settings and save.
When someone leaves
- Account disabled. A user whose account is disabled in Entra ID is deactivated at the next sync. Deactivated people receive no surveys and use no seat; their past answers stay.
- Deleted, or outside the filter. With Disable Removed Users on, someone who no longer appears in what Polzy reads — deleted, or no longer matching your filter — is deactivated too.
- Blocked in Polzy. Someone an admin blocked in Polzy stays blocked, whatever Entra ID says.
Nobody is deleted by a sync.
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| Invalid Tenant ID format or Invalid Client ID format | The value is not an ID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. | Copy the Directory (tenant) ID and Application (client) ID from the app's Overview. |
| Microsoft refused these credentials: … | The secret is wrong or expired — or you copied the Secret ID instead of the Value. | Create a new client secret and paste its Value under Settings. |
| Microsoft refused these credentials. Check the app registration and its admin consent. | User.Read.All is missing, or admin consent was not granted or was taken back. | Add the permission and choose Grant admin consent for your organization. |
| Guests arrive in Polzy | Your Filter Query replaced the one that leaves guests out. | Add userType eq 'Member' and to the start of your filter. |
| N people were not imported: the plan has no seats left for them. | Every member uses a seat, and the plan is full. | Narrow the filter, free seats or change plan, then choose Sync Now. |
| This organization provisions people through SCIM. Revoke its SCIM token in Settings → Security before connecting a people source. | SCIM and a people source cannot run in the same organization. | Use SCIM instead, or have the Owner revoke the SCIM token first. |
Good to know
- Members, not contacts. Everyone from Entra ID is a member: they can sign in and each uses a seat. A sync that would go over your seats imports the people who fit, stops there and tells admins — see Usage and limits.
- No instant updates. Changes arrive at the next scheduled sync, or when you choose Sync Now. For changes the moment they happen, use SCIM.
- Disconnect or remove. Under Settings, Disconnect stops syncing and keeps the settings and history, so you can reconnect later; Remove deletes the connection. Either way, the people already synced stay in Polzy and are no longer updated.
- Need a hand? The connect panel's Ask Polzy link explains where each value lives in the Microsoft Entra admin center.
Useful links
- Microsoft: Register an application — the app registration, and where its IDs are.
- Microsoft: Add an application permission and grant admin consent —
User.Read.Alland the consent button. - Microsoft: Add a client secret — creating the secret and copying its value.
- Microsoft: Find your tenant ID — if you need the tenant ID again.
- Microsoft: Use the $filter query parameter — writing a filter query.
Related articles
Signed-in members can ask Polzy or message the team from Support. How fast we reply depends on your plan.