Omnicit.PIM

Author(s)

• Omnicit (originally by Justin Grote @justinwgrote)

Tags

PIM Azure EntraID Identity Privileged Windows MacOS Linux

Functions

Connect-OPIM Disable-OPIMAzureRole Disable-OPIMDirectoryRole Disable-OPIMEntraIDGroup Disable-OPIMMyRole Disconnect-OPIM Enable-OPIMAzureRole Enable-OPIMDirectoryRole Enable-OPIMEntraIDGroup Enable-OPIMMyRole Get-OPIMAzureRole Get-OPIMConfiguration Get-OPIMDirectoryRole Get-OPIMEntraIDGroup Install-OPIMConfiguration Remove-OPIMConfiguration Set-OPIMConfiguration Wait-OPIMDirectoryRole

PSEditions

Core

Dependencies

• • Az.Resources (>= 9.0.3)
  • Microsoft.Graph.Authentication (>= 2.36.0)

Release Notes

## [0.6.0] - 2026-10-09

Roles and groups can be named by display name, as `Enable-OPIMEntraIDGroup 'Finance Team' -AccessType Owner` (a group name alone means membership), and completion offers the bare name when unique. A name or `-Identity` matching several is refused with the candidates (`AmbiguousName`) and nothing changes; `-Scope` (a role, where the command has it), `-AccessType` (a group) or the tab-completed form picks one. A name matching nothing is `EligibleRoleNotFound` (`ActiveRoleNotFound` when deactivating, saying if the role is only eligible or active under another name); neither stops the command or the next name. `Get-OPIMAzureRole -RoleName` and `-Identity` work below the root scope without extra rights, `-All -Scope` returns only that scope's roles, and a `-Scope` ending in a slash is refused.

A failed or denied request is an error (`ActivationRequestFailed`), and one awaiting approval or provisioning returns with a warning. `-Wait` stops after `-TimeoutSeconds` (default 300, `ActivationWaitTimedOut`); `Wait-OPIMDirectoryRole` checks requests in turn (`-ThrottleLimit` is ignored) and writes an expired one as `ActivationAlreadyExpired`. An active role or group is not requested again, `-Activated` lists activations only, `-Hours` is 1-24, `-NotBefore` works for Azure, and a time without an offset is local. Lists read every page; an unreadable list is its own error, not "not found", and a directory role whose administrative unit is unreadable is listed, with a warning, instead of ending the list. An ownership held as a group's only owner cannot be deactivated and does not end: activate ownership only of a group with another owner.

`pim` and `unpim` act on a directory role only at the scope its tenant map entry names (`roleDefinitionId|directoryScopeId`). An old entry, the role id alone, means `/` only and activates nothing for a role eligible only below it: pipe the alias's directory roles to `Set-OPIMConfiguration` again. An active Azure role from `-Activated` is stored with its eligibility and its own scope; one activated at another scope than its eligibility is refused (`LinkedEligibilityNotFound`) or matches nothing. A 0.5.x module reading a 0.6.0 map acts on no directory role, or Azure role from `-Activated`, whose entry names a scope. `unpim` refuses an entry matching several (`AmbiguousName`). The map's default path is `$HOME/.config/Omnicit.PIM/TenantMap.psd1` everywhere (unchanged on Windows), an apostrophe no longer breaks it, and `Set-OPIMConfiguration` keeps the tenant of an old string-form alias. `Install-OPIMConfiguration` without `-TenantId` takes its tenant only from the module's own sign-in, or refuses (`TenantIdNotResolvable`).

`-DeviceCode` on `Connect-OPIM`, `pim` and `unpim` signs in with a code entered on any device, for Azure too with `-IncludeARM`; the session keeps the mode until `Disconnect-OPIM`.

A session stays on its tenant: a command naming none keeps it, a token for another is refused (`TenantMismatch`), and Azure signs in to it, reuses a sign-in only for the same account and asks for no subscription. Nothing is sent under a Graph session another `Connect-MgGraph` started (`GraphSessionChanged`): run `Disconnect-OPIM`, which also disconnects that session, and sign in again. A command whose sign-in was refused sends nothing more (`SignInRefused`), and after a failed Azure sign-in (`AzureConnectFailed`) nothing goes to Azure under an earlier one. `pim` and `unpim` stop if the Graph sign-in fails and skip only Azure if the Azure one does, unless the error preference is `Stop`. Errors from a failed Graph request or Azure role command no longer carry your sign-in token.

Messages and help are ASCII (`--` and `->` mean a dash or arrow), and `Get-Help about_Omnicit.PIM` lists every command by area.