en-US/about_Omnicit.PIM.help.txt
|
TOPIC about_Omnicit.PIM SHORT DESCRIPTION Entra ID Privileged Identity Management (PIM) Self Activation Commands for Directory Roles, Azure Resources, and Entra ID Groups. LONG DESCRIPTION Omnicit.PIM is a PowerShell 7.2+ (Core-only) module for self-service activation and deactivation of PIM roles and group memberships across three surfaces: Surface Noun Example cmdlet ------- ---- -------------- Directory Roles DirectoryRole Enable-OPIMDirectoryRole Azure RBAC Roles AzureRole Enable-OPIMAzureRole Entra ID Groups EntraIDGroup Enable-OPIMEntraIDGroup All cmdlets use the canonical prefix OPIM and short PIM aliases are available for convenience (e.g. Enable-PIMRole, pim). DEPENDENCIES The module requires: - Microsoft.Graph.Authentication (>= 2.36.0) for all Graph API calls - Az.Resources (>= 9.0.3) for Azure RBAC PIM operations No other Microsoft.Graph.* SDK modules are needed; all Graph calls use Invoke-MgGraphRequest directly. CONNECTION AND AUTHENTICATION All Get-/Enable-/Disable-OPIM* cmdlets authenticate automatically on first use via a MSAL-based browser prompt (system browser, no WAM). Call Connect-OPIM to pre-authenticate or to target a specific tenant before running other cmdlets. The token is cached for the session -- subsequent calls are idempotent. Call Disconnect-OPIM to clear all cached tokens. Connect-OPIM # home tenant at the first sign-in Connect-OPIM -TenantId 'contoso.onmicrosoft.com' # specific tenant Connect-OPIM -IncludeARM # also sign in to Azure Disconnect-OPIM # clear all cached tokens A session stays on the tenant it signed in to: a command that names no tenant keeps it, and a token issued for another tenant is refused with TenantMismatch. To work in another tenant, run Connect-OPIM -TenantId with it. If another Connect-MgGraph in the same process replaces the module's Microsoft Graph session, the role, group and sign-in commands refuse their calls with GraphSessionChanged instead of switching the session back: run Disconnect-OPIM, which also disconnects that session, and sign in again. The configuration commands are the exception, by design: Install-OPIMConfiguration and Set-OPIMConfiguration read whatever Graph session is active. A command whose sign-in at its start was refused sends nothing more (SignInRefused); a sign-in refused while a failed request is retried fails only that request. Azure signs in to the same tenant, reuses an earlier Azure sign-in only for the same account, and asks for no subscription; after a failed Azure sign-in (AzureConnectFailed) nothing is sent to Azure under an earlier one. Enable-OPIMMyRole and Disable-OPIMMyRole stop when the Microsoft Graph sign-in fails; when only the Azure sign-in fails they write the error and skip the Azure roles, unless the error preference is Stop, which ends the command. On a machine without a browser, sign in with a device code. The command shows a code and the address to open; enter the code there on any device. The message is written to the Information stream with the tag OPIMDeviceCode. With -IncludeARM, Azure shows a second code, written by Connect-AzAccount itself (Az.Accounts 5.5.3: an information record; an older Az.Accounts: a warning). The mode is remembered for the session: the refresh stays silent while it can, and any later sign-in that needs a prompt uses a device code until Disconnect-OPIM. Enable-OPIMMyRole and Disable-OPIMMyRole take -DeviceCode too. Connect-OPIM -TenantId 'contoso.onmicrosoft.com' -DeviceCode A script reads both messages as they arrive by merging the two streams into a pipeline. Capturing the output in a variable (for example, $x = Connect-OPIM -DeviceCode 6>&1) shows nothing until the flow ends, which can take 15 minutes. Connect-OPIM -DeviceCode -IncludeARM 6>&1 3>&1 | ForEach-Object { $PSItem.ToString() } The following Microsoft Graph scopes are requested automatically. These are listed for reference (least-privilege review, custom app registration scenarios): RoleEligibilitySchedule.ReadWrite.Directory RoleAssignmentSchedule.ReadWrite.Directory PrivilegedEligibilitySchedule.ReadWrite.AzureADGroup PrivilegedAssignmentSchedule.ReadWrite.AzureADGroup AdministrativeUnit.Read.All User.Read Azure RBAC cmdlets (Get-/Enable-/Disable-OPIMAzureRole) also require an Azure Resource Manager connection, acquired automatically on first use or when -IncludeARM is passed to Connect-OPIM. CONFIGURATION (TENANTMAP) The *-OPIMConfiguration cmdlets manage a TenantMap.psd1 file that maps short tenant aliases to Azure Tenant IDs and optional default role lists. Install-OPIMConfiguration Create a new alias Get-OPIMConfiguration Read current configuration Set-OPIMConfiguration Update an existing alias Remove-OPIMConfiguration Delete an alias The TenantMap is stored at: $env:USERPROFILE\.config\Omnicit.PIM\TenantMap.psd1 ENABLE-OPIMMYROLE (alias: pim) The all-in-one activation command. Connects to Microsoft Graph (and Azure if configured) and activates eligible roles for a named tenant alias: pim -TenantAlias contoso -Hours 4 -Justification 'Incident response' Use -AllEligible, -AllEligibleDirectoryRoles, -AllEligibleEntraIDGroups, or -AllEligibleAzureRoles to bypass the TenantMap filter and activate all eligible roles in the selected categories. DEFAULT ACTIVATION DURATION The default activation period is 1 hour. Override with -Hours or -Until, or set persistently via: $PSDefaultParameterValues['Enable-OPIM*:Hours'] = 4 WHATIF / CONFIRM SUPPORT All Enable-* and Disable-* commands support -WhatIf and -Confirm: Get-OPIMDirectoryRole | Enable-OPIMDirectoryRole -WhatIf COMMAND COHORTS The cohorts below are for orientation only: they group the cmdlets by the surface they work on. Use Get-Command -Module Omnicit.PIM to list every exported command. Directory roles Get-OPIMDirectoryRole, Enable-OPIMDirectoryRole, Disable-OPIMDirectoryRole, Wait-OPIMDirectoryRole Groups Get-OPIMEntraIDGroup, Enable-OPIMEntraIDGroup, Disable-OPIMEntraIDGroup Azure roles Get-OPIMAzureRole, Enable-OPIMAzureRole, Disable-OPIMAzureRole Sign-in and configuration Connect-OPIM, Disconnect-OPIM Install-OPIMConfiguration, Get-OPIMConfiguration, Set-OPIMConfiguration, Remove-OPIMConfiguration Enable-OPIMMyRole (alias pim) and Disable-OPIMMyRole (alias unpim) call Connect-OPIM first, then work from the tenant map for a -TenantAlias. EXAMPLES PS C:\> Get-OPIMDirectoryRole Lists all eligible directory roles for the current user. PS C:\> Get-OPIMDirectoryRole | Enable-OPIMDirectoryRole -Hours 4 -Justification 'Incident response' Activates all eligible directory roles for 4 hours. PS C:\> Get-OPIMDirectoryRole | Where-Object { $_.roleDefinition.displayName -eq 'Global Administrator' } | Enable-OPIMDirectoryRole -Wait Activates the Global Administrator directory role and waits until it is fully provisioned. PS C:\> Get-OPIMAzureRole -Activated | Disable-OPIMAzureRole Deactivates all active Azure RBAC roles. PS C:\> pim -TenantAlias contoso -Hours 8 -Justification 'Daily operations' Activates all stored roles for the 'contoso' tenant alias. NOTE: Thank you to all those who contributed to this module, by writing code, sharing opinions, and providing feedback. Originally created by Justin Grote (@justinwgrote). Overhauled and maintained by Omnicit. TROUBLESHOOTING NOTE: Look out on the Github repository for issues and new releases. RoleAssignmentRequestAcrsValidationFailed / ACRS claims challenge ----------------------------------------------------------------- If an Enable-OPIM* command fails with the error code 'RoleAssignmentRequestAcrsValidationFailed', the Microsoft Graph token does not satisfy the step-up authentication requirement (ACRS claim 'c1') enforced by a Conditional Access policy for PIM operations. The module automatically attempts to acquire a new token with the required claims via MSAL interactive authentication (opens a browser window). If this succeeds the request is retried transparently. If the automatic recovery fails, the error message directs you to open a new PowerShell session and reconnect: # In a fresh PowerShell window: Connect-OPIM Enable-OPIMDirectoryRole -RoleName '...' If the issue persists, the tenant may require a custom app registration for claims-challenge support. Bearer token security --------------------- When a Microsoft Graph request or an Azure role command fails, the module clears the Authorization header, which carries the bearer token, on the request the error record points at, and removes the raw record from $Error, the moment it catches the failure. A Graph error reaches you as a new record that does not chain the original exception. SEE ALSO - https://github.com/Omnicit/Omnicit.PIM KEYWORDS PIM, Privileged Identity Management, Entra ID, Azure AD, RBAC, Graph, Directory Roles, Azure Roles, PIM Groups, Self-Activation |