PIM Manager documentation · Verified against PIM Manager 3.0.23.3 on Nov 3, 2026
Lessons learned
Privileged access on Microsoft Entra has traps that no documentation warns you about. These are problems we met in real tenants, why each one is hard, and the rule PIM Manager follows because of it. Each rule is also a technique you can use in your own scripts.
1. A refused nesting can look like success
The problem. A role group is nested into a role-assignable permission group as an Active member. Microsoft Entra refuses it (“Nesting is currently not supported”). If the refusal is skipped on every run, the job reports OK and nothing shows as failed.
The rule. The wizards write a nesting into a role-assignable group as Eligible. A refusal is a classified failure under Jobs > Engine logs & errors, with a fix, not a silent skip. Whether a group is role-assignable is decided from the design when the group is created, because the flag cannot be changed later.
For your own scripts. Treat “Nesting is currently not supported” as a hard failure. Nest into a role-assignable group only through an eligibility schedule request.
2. A filtered read can drop rows without an error
The problem. Reading “which groups is this role group eligible in” with a filter on the principal can return an incomplete list, with no error and no paging gap. For a desired-state engine a missing row means “create it again”, and a removal of an unseen row reads as “already gone”.
The rule. The filtered read only narrows. Every desired item it did not return, and every removal, is confirmed with a read of that group’s complete list. A read that fails is an error, not “no members”.
For your own scripts. Ahead of any delete or “missing, so create”, read the group itself and follow every next-page link. Log the count you expected next to the count you got.
3. “Remove what is not defined” can remove everyone
The problem. The classic desired-state rule removes whatever is not in the desired set. A fresh install, a failed import or a wiped database makes the desired set empty, and the rule then reads as “remove every admin”.
The rule. When the database defines nothing, or cannot be counted, the engine touches nothing. A scope whose definitions are gone is not pruned until a person releases that one plan. Removal only reaches objects PIM Manager manages, and removals, disables and deletes per run are capped (see Guards).
For your own scripts. Refuse to run on empty or unreadable input. Keep a list of what you created and remove only from it. Cap deletes per run, and stop when the cap is hit.
4. A threshold is not an approval
The problem. A policy change set can rewrite hundreds of role and group policies in one run, and one weakening, such as approval switched off on Global Administrator, is a silent breach. A threshold lets small harmful changes through, and an approval of “the run” covers a change set nobody saw. Untouched default policies of newly imported groups can also count toward a threshold and hold the whole change set.
The rule. Every policy change set waits for a SuperAdmin. The approval records the plan’s hash, covers only that exact set, and is valid for 24 hours. A different plan waits for its own approval. The SuperAdmin who saved the choices may approve them too, so a second person is your procedure, not a product rule (see How to approve a held policy change).
For your own scripts. Export the policies, diff them rule by rule, hash the diff, and apply only when the approved hash still matches.
5. “Not found” one second after you created it
The problem. Microsoft Entra is eventually consistent. A group created a moment ago often answers “not found” when you assign it a role. Failing on that fails half a run; retrying every “not found” hides a real missing object.
The rule. A failed call is retried only when the answer is a real “not found” and it names an object this run created a short time ago, with short back-offs and a time budget. When the budget is used, the item waits for the next run as not visible yet, not as an unexplained error.
For your own scripts. Keep the ids you created in this run. Retry a “not found” only for those, back off, and give up into “next run”. Do not retry a 403.
6. “The duration is greater than the maximum allowed”, every time
The problem. A role’s PIM policy caps activation, for example at 8 hours. An activation tool remembers the last duration, which is longer, and every later activation of that role fails with the same error. The error does not say what the maximum is, and the Entra portal silently shortens the same request, so it looks like a permission problem.
The rule. The PIM Activator tries the requested duration once. On that error it reads the role’s policy, shortens the request to the maximum, retries once and tells the admin. If the maximum cannot be read, it says so with the duration it tried.
For your own scripts. Read the policy’s expiration rule and clamp the duration to it. Do not carry a duration from one role to another.
7. Offboarding must not reach groups you do not own
The problem. Disabling an account is not offboarding: sessions live on, and eligible memberships wait for a re-enable. Removing the account from every group it is in fixes that, but also strips memberships in groups other teams own.
The rule. By default, the auto-disable date disables the account and nothing more. With Automatic offboarding on (off by default), the engine also revokes the account’s sessions and removes memberships and eligibilities, only in groups PIM Manager defines. Memberships elsewhere are reported, not removed. Each step is saved, so an interrupted offboarding resumes. Offboarding does not delete the account. See How to offboard an admin.
8. A job that does nothing can report success
The problem. A scheduled job points at an area name the engine does not know. It does nothing, and it reports success, for months.
The rule. An area the engine does not recognize fails the job loudly on its first run. A run that applies nothing because nothing is defined says so in plain words and is not reported as a failure.
For your own scripts. Validate every input name against the list of names you handle, and throw on anything else.
Verified against PIM Manager 3.0.23.3 on Nov 3, 2026Download PDF