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 # default / home tenant Connect-OPIM -TenantId 'contoso.onmicrosoft.com' # specific tenant Connect-OPIM -IncludeARM # also acquire Azure ARM token Disconnect-OPIM # clear all cached tokens 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 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 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 --------------------- All Graph API error handling removes the raw HttpRequestMessage from the $Error collection immediately after catching, preventing the bearer token (in the Authorization header) from being exposed through $Error inspection. 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 |