Importing People from Entra ID - edmozley/freeitsm GitHub Wiki

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:

Go to App registrations → New registration. Give it a name, leave it as single tenant, and leave the redirect address blank.
Open API permissions → Add a permission → Microsoft Graph → Application permissions.
Add User.Read.All and GroupMember.Read.All.
Press Grant admin consent. Both should show a green tick.
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

Go to System → Authentication and find your Microsoft provider. System → Integrations → Microsoft Entra ID brings you to the same place.
Press its directory sync button.
On the Connection tab, choose A separate app registration and enter the client ID and secret.
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.

You can't delete them by hand either (after 4.11.0). In Tickets → Users, Delete is greyed out for anyone an import keeps up to date, with the reason: deleting them would lose their history, and the next import would only create them again as somebody new. Remove or disable them in Entra, and they are marked as left. Once the source itself is deleted, nothing can bring them back, and they can be deleted like anybody else.

Groups in People

After 4.11.0. Once groups have been imported:

the People list has a Group filter - the members of one group, members of groups nested inside it included - remembered in your browser like Show and Company;
a Groups tab lists every group, with a page per group showing its members;
a person's page lists their groups, and a company's page shows the groups its people are in.

You only see groups from a source you can see: a source that belongs to a client company shows its groups only to analysts with access to that company, and a group's members are limited to the companies you can access - so a group page can list fewer people than Entra counts.

The run history says who joined and who left each group, one line per person, with filters for both. A group's first import writes one summary line rather than a line for every member.

⚠️ 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 cron/directory_sync.php --all

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

On the Entra page itself (after 4.11.0), a line under Run says what the scheduler will do with this source: how often and when the next import is, that imports start from open pages when only the fallback runs them, or a warning when the import is switched off or nothing will run it - with a link to Background jobs, the one place to change it. Every source is imported on the same schedule, because the import is one job. The command moved to cron/directory_sync.php; a task still running scripts/directory_sync.php keeps working.

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.