Importing People from Entra ID

Importing people from Microsoft Entra ID

If your organisation signs in with Microsoft, FreeITSM can read your people and groups from Microsoft Entra ID, so a new starter exists before they ever sign in. You can give them a laptop or raise a ticket for them straight away.

Use this page if you have Microsoft 365 or Entra ID and no LDAP directory to point FreeITSM at. For Active Directory or LDAP, see Importing people from a directory.

It only reads. FreeITSM never changes anything in Entra, and an import never creates an analyst: people arrive as self-service users, the people who raise tickets.

Before you start

You need a Microsoft Entra sign-in provider under System → Authentication, and an administrator who can grant permissions in Entra.

I recommend a separate app registration for the import, so the app people sign in with does not carry directory-wide permissions. In the Entra admin center:

1. Go to App registrations → New registration. Give it a name, leave it as single tenant, and leave the redirect address blank.
2. Open API permissions → Add a permission → Microsoft Graph → Application permissions.
3. Add User.Read.All and GroupMember.Read.All.
4. Press Grant admin consent. Both should show a green tick.
5. Open Certificates & secrets → New client secret. Copy the Value straight away, because Entra shows it only once. The Secret ID is not the secret.

Connect it

1. Go to System → Authentication and find your Microsoft provider. System → Integrations → Microsoft Entra ID brings you to the same place.
2. Press its directory sync button.
3. On the Connection tab, choose A separate app registration and enter the client ID and secret.
4. Press Test connection. It answers three questions separately: can the app sign in, can it read users, and can it read groups.

Choose who comes across

On the Importing people tab:

• Which people: everybody in the directory, or only the members of groups you choose. Members of nested groups count.
• Guests: left out unless you tick the box.
• Which groups: none, chosen groups, or all of them.

Importing everybody also brings in shared mailboxes, meeting rooms and service accounts. If you do not want those in your people list, import from a group.

Preview, then import

Press Preview. It reads your directory and changes nothing, then lists what would happen to each person. Read it before your first import: it is the only time you can see the whole effect in advance.

Preview cannot count group members, because the people do not exist yet. Their group memberships appear after the real import.

Then press Import now.

What happens to people

In Entra	In FreeITSM
A new account	A new person
Name, job title or department changed	Updated at the next import
Disabled	Marked as having left
Missing for several imports running	Marked as having left. Safety sets how many
Same email as somebody already in FreeITSM	Linked to them, or left alone, as you choose under When somebody is already here

Nobody is ever deleted. They keep their tickets, assets and history.

⚠️ Linking someone by email ends their portal password. From then on they sign in with Microsoft.

When a sign-in name or email is reused

Sooner or later, a leaver's address goes to somebody new. Their account has the same address, but it is a different Entra account.

FreeITSM will not treat them as the same person, because the new starter would inherit the leaver's record and tickets. The import shows a conflict and leaves both alone, whatever your conflict setting says. The new starter is not imported.

This is a known limit: FreeITSM has no way yet to separate the two from the screen. If you hit it, please open an issue.

Running it on a schedule

From 4.8.0, the import is one of the jobs FreeITSM's built-in scheduler runs: once FreeITSM's one scheduled task (cron/run.php, every minute) is set up - or on Docker, with nothing to set up - the people import runs once a day by itself, together with LDAP and CardDAV. Reporting → System logs → Background jobs shows it, and Edit there changes when it runs. See Scheduled tasks.

Before 4.8.0, nothing imported by itself: schedule the same command that runs LDAP and CardDAV imports, once or twice a day:

php scripts/directory_sync.php --all

Only one import of a source runs at a time. A second one stops and says so, and changes nothing.

Laptops from Intune

(4.8.0, PR #236.) Every person imported from Entra carries their Entra object id, and so does every device Intune reports. Switch on Assign assets to their primary user in Intune under Assets → Settings → Intune, and at the next Intune sync each asset nobody holds is given to its device's primary user - matched exactly by that id, never by name. An asset that already has a holder is never changed. More on the Assets page.

If something is not right

The in-app help covers the error messages: System → Authentication → Help → Entra troubleshooting. The History tab shows every run, and clicking one shows what happened to each person.

See also

• Microsoft Entra ID: everything FreeITSM does with Entra, and the order to set it up in
• Importing people from a directory (Active Directory and LDAP)
• Entra directory sync - developer guide
• Single Sign-On