[FEATURE REQUEST] Optional Entra user sync before asset sync

[warst]

Problem or use case

When Intune2Snipe syncs devices from Intune into Snipe-IT, the assigned user does not always already exist in Snipe-IT.

In a clean or newly reset Snipe-IT database, this means the assets can be created, but the user assignment side is limited unless the users have already been imported or manually created first.

For my use case, I wanted Intune2Snipe to be able to prepare the relevant Snipe-IT users before the normal asset sync runs, so that devices can then be associated to the correct user when the UPN matches.

Proposed solution

Add an optional user sync pre-pass that runs before the existing asset sync.

The feature would be disabled by default and controlled by environment variables. When enabled, it would sync users from a defined Entra group, rather than trying to pull every user from the tenant.

The idea is that the module can:

• create missing Snipe-IT users from Entra ID
• update existing Snipe-IT users where required
• optionally create related lookup values such as company, department and location
• preserve a link back to the Entra user object so the same user can be matched reliably on future syncs
• allow the normal asset sync to continue afterwards

I have been testing this as a standalone bolt-on module rather than by changing the main application logic directly. The intention is that the existing sync continues to work as normal if the user sync feature is not enabled. It is currently working great but would like some other environments and workflows to test it in.

I have also tested the scenario where the asset needs to follow the matched user’s company so that Snipe-IT allows the checkout/assignment to complete successfully.

Alternatives considered

I considered manually importing users into Snipe-IT first, but that adds another process to maintain and makes clean database rebuilds more awkward.

I also considered using a single static company for all synced assets, but that does not work as well if users can belong to different companies or business entities.

Another option would be to leave Intune2Snipe exactly as it is and expect Snipe-IT users to already exist before sync, but that feels like a missed opportunity because Intune/Entra already has most of the user information needed.

My preferred approach is an optional, scoped, pre-sync user reconciliation step that can be tested independently and enabled only where required.

Primary area

Microsoft Graph / Intune

[brngates98]

Implemented this as an optional, disabled-by-default pre-sync pass in da95aad:

• ENTRA_USER_SYNC_ENABLED / ENTRA_USER_SYNC_GROUP_IDS — before the normal asset sync, lists members of the given Entra ID group(s) (cast to microsoft.graph.user) and creates/updates matching Snipe-IT users. Matching is by email, falling back to a stored Entra object id (kept in the Snipe employee_num field) so a later UPN/email rename doesn't orphan the link on future runs.
• ENTRA_USER_SYNC_CREATE_COMPANY / ENTRA_USER_SYNC_CREATE_DEPARTMENT / ENTRA_USER_SYNC_CREATE_LOCATION (default true) — optionally create/link Snipe-IT company, department, and location from the Entra user's companyName / department / officeLocation.
• SNIPEIT_COMPANY_FROM_USER — makes a synced asset's company_id follow its checked-out user's Snipe-IT company (falling back to SNIPEIT_COMPANY_ID if the user has none), so checkout/assignment succeeds across companies in multi-company installs — covers the scenario you mentioned testing.
• When the feature is off (the default), behavior is unchanged — existing installs are unaffected.

Docs: see Configuration — Entra ID user pre-sync and How it works.

@warst would you be able to test this against your environment/workflow before I cut a release? In particular I'd appreciate a check on:

• Whether the create/update field mapping matches what you had working in your bolt-on module (name/email/username/jobtitle/phone + company/department/location)
• The employee_num-as-link-back approach vs. whatever you used
• The company-follows-user checkout behavior with SNIPEIT_COMPANY_FROM_USER=true

Once confirmed I'll fold this into the next release notes. Thanks for the detailed writeup — it made this straightforward to scope.

[warst]

Thanks for getting this implemented so quickly.

I’ll pull the latest build and test it properly against my workflow.

At a high level, this looks very close to what I had working in my bolt-on module:

• optional/disabled-by-default user pre-sync
• scoped to defined Entra group(s)
• create/update users before the asset sync
• create/link company, department and location
• asset company follows the checked-out user company
• normal behaviour unchanged when the feature is disabled

One difference I noticed is the use of employee_num to store the Entra object ID.

In my version, I stored the Entra object ID as a marker in the Snipe user notes field instead, mainly because employee_num may already be used by some organisations for an actual HR/payroll employee number, or they may want to use it for that later.

For our environment, I can test with employee_num, but I think it may be worth considering whether that should be configurable, or whether notes/custom field storage would be safer as the default.

Something like:

ENTRA_USER_SYNC_LINK_FIELD=employee_num

or possibly supporting notes/custom field as an alternative would avoid taking over a standard Snipe user field that some companies may already rely on.

I’ll test the current implementation against:

• clean Snipe-IT database
• existing users already present
• user create/update mappings
• company/department/location creation
• SNIPEIT_COMPANY_FROM_USER=true
• checkout status behaviour
• repeat runs to make sure it is idempotent
• email/UPN rename behaviour if I can safely simulate it

I’ll report back with anything I find.

[brngates98]

Thanks for the thorough test plan, and good catch on employee_num — that's a fair concern.

I dug into the "notes/custom field" alternative you mentioned: Snipe-IT custom fields are asset-only today (extending them to users is an open, unimplemented feature request against Snipe-IT itself), so notes is really the only other place to put the marker — there's no third option available.

Here's how I'd like to proceed: keep employee_num as the default link field, but add:

ENTRA_USER_SYNC_LINK_FIELD=employee_num   # or: notes

Reasoning for keeping employee_num as the default rather than switching wholesale to notes:

• employee_num has a dedicated exact-match query param (GET /users?employee_num=), consistent with how the rest of this app does user lookups (exact filters, not fuzzy search=).
• notes has no dedicated filter — matching against it means fuzzy search= plus parsing client-side, which is more fragile (a false match if an admin's own note happens to contain something GUID-shaped, for example).
• Most installs don't already use employee_num for payroll data, so it stays the lower-friction default — but for yours (and anyone else in the same boat), setting ENTRA_USER_SYNC_LINK_FIELD=notes avoids the collision entirely.

When set to notes, the sync will embed the marker as a recognizable prefixed line (e.g. Entra Object ID: <guid>) and preserve whatever else is already in the notes field rather than overwriting it.

I'll hold off implementing this until your test pass finishes, in case anything else you find is worth batching into the same follow-up commit — feel free to just note ENTRA_USER_SYNC_LINK_FIELD=notes as a requirement in your results and I'll wire it in along with anything else. Appreciate you putting this through its paces before we cut a release.

[warst]

I have run a test against a clean/reset Snipe-IT database using the latest main branch with the new Entra user pre-sync enabled.

Overall, it looks like it is working well from my side.

Anonymised summary of the run:

[INFO] Authenticated with Microsoft Graph
[INFO] Found 128 Entra user(s) from 1 group(s)
[INFO] Entra user pre-sync: processing 128 user(s)

[INFO] Updated Snipe-IT user 1: user001@example.com
[INFO] Updated Snipe-IT user 2: user002@example.com
[INFO] Created Snipe-IT user 3: user003@example.com
...
[INFO] Created Snipe-IT user 128: user128@example.com

[INFO] Entra user pre-sync: 126 created, 2 updated

[INFO] Loaded 105 Windows Autopilot device(s) by serial
[INFO] Found 171 Intune devices matching platform 'all'
[INFO] Using category_id=23, default_status_id=2, checkout_mode=user, primary_user=False, custom_fields=0, autopilot=105, lifecycle_reconcile=True

[INFO] Created asset 1: ASSET-0001
[INFO] Checked out asset 1 to user user001@example.com
[INFO] Created asset 2: ASSET-0002
[INFO] Checked out asset 2 to user user002@example.com
...
[INFO] Created asset 170: ASSET-0170
[INFO] Checked out asset 170 to user userXXX@example.com

[WARNING] No Snipe-IT user found with matching email or username for service-device-001@example.com
[WARNING] No Snipe-IT user found with matching email or username for service-device-002@example.com
[WARNING] No Snipe-IT user found with matching email or username for service-device-003@example.com

[ERROR] Failed to create asset: {'asset_tag': ['The asset tag must be unique.']}

[INFO] Summary: 170 created, 1 create failed

The key things I wanted to confirm did work:

• users were created before the asset sync started
• existing users were updated rather than duplicated
• assets were created after the user pre-sync
• assets were checked out to the matched users
• SNIPEIT_COMPANY_FROM_USER=true appears to have resolved the company mismatch issue I was seeing previously
• the device/service-style accounts that do not exist as Snipe users were skipped/warned rather than causing the run to fail

The only error in this test was:

Failed to create asset: {'asset_tag': ['The asset tag must be unique.']}

That looks unrelated to the user pre-sync and more likely to be existing asset tag behaviour/test database state.

A few things I would still like to confirm before calling it fully tested:

1. How does the pre-sync handle a user rename or UPN/email change?

In the bolt-on version I tested, the intention was that the Entra object ID remains the durable link so that a later email/UPN rename updates the existing Snipe user rather than creating a new one. I know your current implementation falls back to the stored Entra object ID in employee_num, but I would like to confirm the order of operations on future runs.

For example:

Existing Snipe user:
old.name@example.com
employee_num = Entra object ID

Entra later changes to:
new.name@example.com

Expected result:
same Snipe user is updated to new.name@example.com
no duplicate user is created

2. Do normal contact/detail changes update cleanly on repeat runs?

For example:

job title
phone number
mobile number
department
company
office/location
first name / surname
username / email

3. What happens if a user is removed from the configured Entra sync group?

I do not think I saw this covered in my test yet. In my bolt-on version I was considering this as a managed-scope problem: if the user is marked as synced/managed and later drops out of scope, there should ideally be an optional way to disable/deactivate them in Snipe rather than leaving them active forever.

I would not necessarily want deletion, but an optional deactivate behaviour may be useful.

4. What happens with disabled Entra users?

Similar point really. If an Entra user is disabled but still in the group, should Snipe mark them inactive, leave them unchanged, or should that be controlled by a separate variable?

5. For the link field, I still think I would need the notes option for our environment.

I agree employee_num is cleaner technically because it has an exact lookup, but for us I would not want to reserve that field permanently for the Entra object ID. So I would still want to test with:

ENTRA_USER_SYNC_LINK_FIELD=notes

once available.

So far, though, the main clean database test looks successful. The pre-sync created the users, the asset sync ran afterwards, and the company-follows-user behaviour appears to have fixed the checkout issue I was originally testing around.

[brngates98]

Thanks for the detailed test run — really useful, and glad SNIPEIT_COMPANY_FROM_USER cleared up the checkout mismatch you were chasing.

Going through your 5 points:

1. Rename / UPN change handling — while checking this I actually found a real bug: the Entra-object-id fallback lookup (find_entra_user_row) was querying Snipe's fuzzy /users?search= instead of the dedicated exact /users?employee_num= filter. So the rename-safety guarantee wasn't reliably backed by an indexed exact match the way I'd described it. Fixed in 9c8dc51, now pushed to main. Confirmed flow after the fix, for your example:

old.name@example.com (employee_num = Entra object ID) in Snipe
Entra renames to new.name@example.com
→ email lookup misses (Snipe still has the old address)
→ falls back to exact employee_num match on the stored Entra object ID → finds the same row
→ update_user() sets email/username to the new address on that row
→ no duplicate created

2. Normal detail updates on repeat runs — yes, every field in the payload (jobtitle, phone, first/last name, username/email, company/department/location ids) is included on every update_user() call, so changes flow through each run. Two things worth flagging while I'm looking at this closely:

• phone is populated from Graph's mobilePhone only — Snipe's separate mobile field isn't touched. If you want both populated I can add businessPhones/mobilePhone split mapping.
• Company/department/location are only sent when Entra has a non-empty value for that user this run — if Entra's field goes blank, the existing Snipe value is left alone rather than cleared (partial PATCH). Flagging in case you'd rather blanks in Entra clear the Snipe value instead — let me know which behavior you want as the default.

3. User drops out of the synced Entra group — not handled today. The pre-sync only processes whoever is currently in the group each run; there's no reconciliation for "was synced, now out of scope," unlike device lifecycle reconciliation (which uses SYNC_STATE_FILE to detect serials that disappeared from Intune). Agreed an optional deactivate — not delete — makes sense, mirroring that existing pattern. I'd want to scope this as a separate follow-up rather than bolt it on now; happy to open a tracking issue for it if you want the design discussed before I build it.

4. Disabled Entra users — this one's already handled, no extra variable needed: _build_entra_user_payload sets activated = 1 if user["accountEnabled"] else 0 on every create/update, so a disabled-but-still-in-group Entra user gets deactivated in Snipe automatically on the next run.

5. notes link field — agreed, still on the plan. I'll implement ENTRA_USER_SYNC_LINK_FIELD=employee_num|notes (default employee_num) next, with the notes marker written as a prefixed line that preserves existing note content. I'll ping you here once it's up so you can test with notes in your environment.

On the asset-tag-uniqueness error — agreed that's unrelated to the user pre-sync, looks like pre-existing test DB state colliding on a generated tag rather than anything this feature touches.

I'll get the link-field option built next; will follow up here when it's ready to test. Thanks again for the rigor on this — the rename bug in particular would've been a quiet correctness gap if you hadn't pushed on it.

[brngates98]

One amendment to point 4 above, before anyone builds against it: I described the activated behavior as unconditional, but that's actually not safe as a default.

Some orgs manage Snipe-IT user activation through a completely separate process from Entra's accountEnabled — Snipe-IT's own native SCIM provisioning (which also targets Entra) being one case, but also just operational workflows that aren't tied to directory state at all (e.g. a user only gets activated once they've digitally signed for their assigned gear). If this pre-sync unconditionally flips activated back to match Entra on every run, it would fight with either of those.

Revised plan:

• On create: still seed activated from Entra's accountEnabled — reasonable initial state, nothing to fight with since the user doesn't exist yet.
• On update: leave activated alone by default. Add ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true as an explicit opt-in for orgs that do want this tool to keep deactivating/reactivating Snipe users in lockstep with Entra's disabled state on every run.

@warst — does that default (off, opt-in) match what you'd want, or would your environment prefer it on by default? I'll fold this into the same follow-up as ENTRA_USER_SYNC_LINK_FIELD.

[warst]

Thanks — that explanation makes sense.

To answer your specific question first: yes, I think default off / opt-in is the right default for the project.

For my own environment, I would probably enable it because I am treating Entra as the source of truth for the Snipe user profile, but I agree it should not be on by default for everyone.

So I would expect to run with something like:

ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true

But I think the default should remain:

ENTRA_USER_SYNC_DEACTIVATE_DISABLED=false

That avoids the pre-sync unexpectedly fighting organisations that manage Snipe user activation through SCIM, manual workflows, or some separate onboarding/offboarding process.

It might also help if I explain how I was using it in my test environment, because my use case is probably slightly different to an organisation using Snipe users as a proper login/identity workflow.

For me, Entra was effectively the source of truth for the Snipe user profile.

I was not planning to configure SCIM at this stage, and I had not really gone down the route of having end users log into Snipe yet. I was using Snipe more as an IT team asset/inventory database: Intune devices, non-Intune issued kit, monitors, docking stations, barcode scanners, software licences, renewal dates, and generally understanding what assets were issued to each user.

So in my bolt-on version, the intended behaviour was:

If Entra has a value, write/update it in Snipe.
If Entra changes a value, update Snipe.
If Entra removes a value, remove/clear it from the Snipe user profile.

That applied to things like job title, phone/mobile, company, department and office/location.

I completely understand why that should not be the hard-coded default though. If another organisation uses Snipe user fields manually, or uses Snipe activation as part of a separate process, the sync should not unexpectedly fight that.

Rather than overloading it with lots of individual variables, would it make sense to think of this as two modes?

For example:

ENTRA_USER_SYNC_MODE=conservative

and:

ENTRA_USER_SYNC_MODE=source_of_truth

Where conservative would be the safer default:

Create missing users
Update fields where Entra has a value
Do not clear Snipe fields just because Entra is blank
Do not change existing Snipe user activation unless explicitly enabled

And source_of_truth would be closer to what I was testing:

Create missing users
Update Snipe from Entra
Clear Snipe fields when Entra values are blank/removed
Optionally keep activation aligned with Entra accountEnabled
Eventually allow synced/marked users removed from scope to be deactivated, not deleted

I do not want to over-complicate the feature, but I also think there are two valid workflows here:

Snipe user records are operational and partly managed inside Snipe

versus:

Snipe user records are inventory records hydrated from Entra

For my environment, I would expect to use something like:

ENTRA_USER_SYNC_LINK_FIELD=notes
ENTRA_USER_SYNC_MODE=source_of_truth

or, if you prefer to keep it as individual switches rather than modes:

ENTRA_USER_SYNC_LINK_FIELD=notes
ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true
ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS=true

I still think notes is the right link field for us, because I do not want to reserve employee_num for the Entra object ID.

On the phone mapping, I would also prefer the split mapping if possible:

Graph businessPhones -> Snipe phone
Graph mobilePhone -> Snipe mobile

A couple of other checks from my bolt-on version:

Do users without first name / last name get skipped?
If a synced user is later removed from the configured Entra group, I would only ever want optional deactivation, never deletion.

So from my side, I think the safe default should remain conservative, but it would be useful to have a source-of-truth style option for environments like mine where Entra is expected to drive the Snipe user profile.

[brngates98]

Really helpful context on your environment — Snipe as an IT-team inventory/asset database rather than an end-user login system explains why "Entra as source of truth for the profile" is the right shape for you, and why a different org might want the opposite.

On modes vs. individual switches: I'd rather not introduce an ENTRA_USER_SYNC_MODE concept. Every other optional behavior in this codebase is an individual, granular env var — SNIPEIT_SKIP_CHECKOUT_ON_CREATE, SNIPEIT_SKIP_RESTORE_DELETED, SNIPEIT_SKIP_LIFECYCLE_RECONCILIATION, SNIPEIT_SKIP_AUTOPILOT, SNIPEIT_SKIP_STATUS_AUTO_CREATE, and so on — there's no precedent anywhere else for one variable bundling several unrelated behaviors, and adding that abstraction just for this feature would make it the odd one out and harder to document/reason about (what exactly does "conservative" turn off, without reading the code?). The good news is individual flags get you the same outcome — your source_of_truth list is just "turn these three flags on":

ENTRA_USER_SYNC_LINK_FIELD=notes
ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true
ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS=true

...and conservative/default is simply all three left at their defaults (employee_num, false, false). If this list of toggles grows a lot more in the future we can reconsider a preset, but three flags doesn't justify a new abstraction layer yet.

So, confirmed plan for the next batch:

• ENTRA_USER_SYNC_LINK_FIELD=employee_num|notes (default employee_num)
• ENTRA_USER_SYNC_DEACTIVATE_DISABLED (default false) — on update, only touch activated when this is true; still seeded from accountEnabled on create either way
• ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS (default false) — when true, a blank Entra value clears the corresponding Snipe field (jobtitle, phone, mobile, company/department/location) instead of leaving the existing value alone
• Phone split: Graph businessPhones[0] → Snipe phone, mobilePhone → Snipe mobile (currently only mobilePhone is mapped, and only into phone)

On your other two checks:

• No first/last name — not skipped today. first_name falls back to display name, then UPN, then the Entra object id if all else is missing, so a user is never dropped for lacking a name; last_name defaults to an empty string if Entra has no surname. So this won't silently exclude anyone.
• Removed from Entra group → deactivate, never delete — agreed, and still scoping this as a separate follow-up rather than folding it into this batch, since it needs its own persisted-state design (something like the existing SYNC_STATE_FILE pattern, but for group membership across runs) that's worth discussing on its own rather than rushing into this change. I'll open a tracking issue for it once this batch lands so we can hash out the design there.

I'll get ENTRA_USER_SYNC_LINK_FIELD, ENTRA_USER_SYNC_DEACTIVATE_DISABLED, ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS, and the phone split built next and will ping you here to test against your environment once it's up.

[warst]

That all makes sense to me.

I agree with keeping it consistent with the rest of the project if the existing pattern is individual env vars rather than grouped modes. The three switches you have listed give me the same end result I was aiming for anyway.

For my environment I would expect to test with:

ENTRA_USER_SYNC_LINK_FIELD=notes
ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true
ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS=true

That should give me the “Entra as source of truth” behaviour I was after, while still keeping the safer defaults for other installs.

The phone split also sounds right to me:

Graph businessPhones[0] -> Snipe phone
Graph mobilePhone -> Snipe mobile

On the no first/last name point, I am fine with your approach for now. My group is already scoped to human users, so I should not be pulling in service accounts/rooms/shared devices anyway. If that became a problem later, I think it would be more of a group hygiene/configuration issue on my side than something the sync needs to over-handle.

Agree on keeping “removed from Entra group = deactivate, never delete” as a separate follow-up. That feels like its own lifecycle/reconciliation feature rather than something to rush into this batch.

Once the next batch is pushed, I will test against my clean Snipe database again with the notes link field and the source-of-truth style settings above.

The main things I will check are:

Clean create from empty Snipe database
Repeat run / no duplicates
Existing notes preserved with the Entra marker added
Blank Entra values clear Snipe fields when ENTRA_USER_SYNC_CLEAR_EMPTY_FIELDS=true
Disabled Entra users deactivate when ENTRA_USER_SYNC_DEACTIVATE_DISABLED=true
Business phone and mobile map to the correct Snipe fields
Asset company still follows checked-out user company

Sounds good from my side.