PimActivate.psm1
|
$script:ArmUrl = 'https://management.azure.com' function Test-PimConnection { if (-not (Get-AzContext)) { return $false } try { # Throws when the cached sign-in has expired (e.g. Conditional Access sign-in frequency) $null = Get-AzAccessToken -ResourceUrl $script:ArmUrl -AsSecureString -ErrorAction Stop -WarningAction SilentlyContinue $true } catch { $false } } function Get-PimPrincipalId { $context = Get-AzContext if (-not $context) { throw 'Not signed in to Azure. Run Connect-PimAuthContext (pim-login).' } # HomeAccountId is "<objectId>.<tenantId>" for the signed-in user $homeAccountId = $context.Account.ExtendedProperties['HomeAccountId'] if ($homeAccountId) { return ($homeAccountId -split '\.')[0] } $response = Invoke-AzRestMethod -Uri 'https://graph.microsoft.com/v1.0/me?$select=id' -ResourceId 'https://graph.microsoft.com/' -Method GET if ($response.StatusCode -ne 200) { throw "Could not look up the signed-in user ($($response.StatusCode)): $($response.Content)" } ($response.Content | ConvertFrom-Json).id } function Get-PimEligibility { param( [Parameter(Mandatory)] [string] $Name ) $uri = $script:ArmUrl + '/providers/Microsoft.Authorization/roleEligibilityScheduleInstances?api-version=2020-10-01&$filter=asTarget()' $eligibilities = while ($uri) { $response = Invoke-AzRestMethod -Uri $uri -Method GET if ($response.StatusCode -ne 200) { throw "Listing eligible roles failed ($($response.StatusCode)): $($response.Content)" } $page = $response.Content | ConvertFrom-Json $page.value $uri = $page.nextLink } $eligibilities | Where-Object { $_.properties.expandedProperties.scope.displayName -like "*$Name*" } | Sort-Object { $_.properties.expandedProperties.scope.displayName }, { $_.properties.scope } } function ConvertFrom-PimSelection { param( [Parameter(Mandatory)] [string] $Selection, [Parameter(Mandatory)] [int] $Count ) if ($Selection -eq 'a') { return 1..$Count } $indexes = foreach ($part in ($Selection -split '[,\s]+' | Where-Object { $_ })) { if ($part -match '^(\d+)-(\d+)$') { [int]$Matches[1]..[int]$Matches[2] } elseif ($part -match '^\d+$') { [int]$part } else { Write-Warning "Ignoring '$part'" } } # Drop out-of-range numbers; index -1 would silently pick the last item $indexes | Select-Object -Unique | Where-Object { $_ -ge 1 -and $_ -le $Count } } function Invoke-PimActivation { param( [Parameter(Mandatory)] $Eligibility, [Parameter(Mandatory)] [string] $PrincipalId, [Parameter(Mandatory)] [int] $Hours, [Parameter(Mandatory)] [string] $Justification ) $properties = $Eligibility.properties $status = $null $authContext = $null $body = @{ properties = @{ principalId = $PrincipalId roleDefinitionId = $properties.roleDefinitionId requestType = 'SelfActivate' linkedRoleEligibilityScheduleId = $properties.roleEligibilityScheduleId justification = $Justification scheduleInfo = @{ expiration = @{ type = 'AfterDuration'; duration = "PT$($Hours)H" } } } } | ConvertTo-Json -Depth 5 $uri = "$script:ArmUrl$($properties.scope)/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/$((New-Guid).Guid)?api-version=2020-10-01" $response = Invoke-AzRestMethod -Uri $uri -Method PUT -Payload $body if ($response.StatusCode -in 200, 201) { $status = ($response.Content | ConvertFrom-Json).properties.status } else { $message = $response.Content if ($message -match 'RoleAssignmentExists') { $status = 'AlreadyActive' } # The error carries the required context as URL-encoded claims JSON, e.g. "value":"c1" elseif ($message -match 'AcrsValidationFailed' -and $message -match 'value(?:"|%22)\s*(?::|%3A)\s*(?:"|%22)(c\d+)') { $status = 'NeedsAuthContext' $authContext = $Matches[1] } else { $status = 'Failed' Write-Error "$($properties.expandedProperties.scope.displayName): $message" } } $Eligibility | Select-Object -Property @( @{ Name = 'Resource'; Expression = { $_.properties.expandedProperties.scope.displayName } } @{ Name = 'ResourceGroup'; Expression = { ($_.properties.scope -split '/')[4] } } @{ Name = 'Role'; Expression = { $_.properties.expandedProperties.roleDefinition.displayName } } @{ Name = 'Status'; Expression = { $status } } @{ Name = 'AuthContext'; Expression = { $authContext } } @{ Name = 'Eligibility'; Expression = { $Eligibility } } ) } function Enable-PimRole { <# .SYNOPSIS Activates eligible Azure PIM roles, picked from a numbered list by resource name. .DESCRIPTION Lists every Azure PIM role you are eligible for whose resource name contains -Name (not case-sensitive), across all subscriptions. The resource can be a subscription, resource group or single resource. Nothing is activated until you pick from the list. Without -Name, all your eligible roles are listed. If a role requires a Conditional Access authentication context (e.g. c1), it signs you in again with MFA and retries. Requires the Az.Accounts module. Signs in automatically if the Azure sign-in is missing or expired. .PARAMETER Name Lists every eligible role whose resource name contains this text (not case-sensitive). Wildcards are allowed. Default: all eligible roles. .PARAMETER Hours Activation duration in hours (1-24). Default: 8. Values above the role's PIM policy maximum fail. .PARAMETER Justification Justification recorded on the activation. Default: 'Ops work'. .PARAMETER Select Pick roles without the prompt, e.g. '1,3,5-7' or 'a' for all. .EXAMPLE pim prod Lists every eligible role with "prod" anywhere in the resource name, e.g. rg-prod-web and sub-prod, and prompts for which to activate. Uses the defaults: 8 hours, justification 'Ops work'. .EXAMPLE pim prod -Hours 1 -Justification "Ticket 1234" .EXAMPLE pim rg-web -Select a -WhatIf Shows which roles would be activated without activating them. .NOTES Alias: pim #> [CmdletBinding(SupportsShouldProcess)] [Alias('pim')] param( [Parameter(Position = 0)] [string] $Name = '*', [ValidateRange(1, 24)] [int] $Hours = 8, [ValidateNotNullOrEmpty()] [string] $Justification = 'Ops work', [ValidatePattern('^(a|[\d,\s-]+)$')] [string[]] $Select ) if (-not (Test-PimConnection)) { Write-Host 'Azure sign-in missing or expired, opening sign-in...' Connect-PimAuthContext } $principalId = Get-PimPrincipalId $items = @(Get-PimEligibility -Name $Name) if ($items.Count -eq 0) { Write-Warning "No eligible assignments match '$Name'." return } Write-Host ('{0,3} {1,-34} {2,-40} {3}' -f '#', 'Resource', 'Role', 'Resource group') for ($i = 0; $i -lt $items.Count; $i++) { $properties = $items[$i].properties Write-Host ('{0,3} {1,-34} {2,-40} {3}' -f ($i + 1), $properties.expandedProperties.scope.displayName, $properties.expandedProperties.roleDefinition.displayName, ($properties.scope -split '/')[4]) } # Separate variable: assigning to $Select would re-run its ValidatePattern and reject an empty answer $selection = $Select -join ',' if (-not $selection) { $selection = Read-Host "`nSelect (e.g. 1,3,5-7 or 'a' for all, Enter to cancel)" if (-not $selection) { return } } $picked = ConvertFrom-PimSelection -Selection $selection -Count $items.Count | ForEach-Object { $items[$_ - 1] } $activation = @{ PrincipalId = $principalId; Hours = $Hours; Justification = $Justification } $operation = "Activate for $Hours hour(s)" $results = @(foreach ($eligibility in $picked) { $p = $eligibility.properties $target = '{0} ({1}, {2})' -f $p.expandedProperties.scope.displayName, $p.expandedProperties.roleDefinition.displayName, ($p.scope -split '/')[4] # Constrained Language Mode blocks $PSCmdlet.ShouldProcess(), so honor -WhatIf/-Confirm via their preference variables if ($WhatIfPreference) { Write-Host "What if: Performing the operation `"$operation`" on target `"$target`"." continue } if ($ConfirmPreference -eq 'Low' -and (Read-Host "$operation on $target? [y/N]") -notmatch '^y') { continue } Invoke-PimActivation -Eligibility $eligibility @activation }) $needContext = @($results | Where-Object Status -EQ 'NeedsAuthContext') if ($needContext.Count) { $context = $needContext[0].AuthContext Write-Host "`n$($needContext.Count) role(s) need auth context '$context'. Signing in again, complete MFA..." Connect-PimAuthContext -Context $context $retried = foreach ($result in $needContext) { Invoke-PimActivation -Eligibility $result.Eligibility @activation } $results = @($results | Where-Object Status -NE 'NeedsAuthContext') + @($retried) } $results | Select-Object -Property Status, Resource, ResourceGroup, Role } function Connect-PimAuthContext { <# .SYNOPSIS Signs in to Azure (Connect-AzAccount), optionally satisfying a Conditional Access authentication context. .PARAMETER Context Authentication context ID required by the PIM policy, e.g. c1. Omit for a plain sign-in. .EXAMPLE pim-login -Context c1 .NOTES Alias: pim-login #> [CmdletBinding()] [Alias('pim-login')] param( [ValidatePattern('^c\d+$')] [string] $Context ) # Sign-in must happen even when the caller used -WhatIf/-Confirm $connect = @{ ErrorAction = 'Stop'; WhatIf = $false; Confirm = $false } if ($Context) { $claims = '{"access_token":{"acrs":{"essential":true,"value":"' + $Context + '"}}}' if ($ExecutionContext.SessionState.LanguageMode -eq 'FullLanguage') { $encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($claims)) } else { # Constrained Language Mode blocks [Convert]; certutil can still encode $inFile = New-TemporaryFile $outFile = "$($inFile.FullName).b64" try { Set-Content -Path $inFile.FullName -Value $claims -NoNewline -Encoding ascii certutil -f -encode $inFile.FullName $outFile | Out-Null $encoded = (Get-Content -Path $outFile | Where-Object { $_ -notmatch '^-----' }) -join '' } finally { Remove-Item -Path $inFile.FullName, $outFile -ErrorAction SilentlyContinue } } $connect.ClaimsChallenge = $encoded } $current = Get-AzContext if ($current) { $connect.Tenant = $current.Tenant.Id # Passing the current subscription skips the interactive subscription picker if ($current.Subscription) { $connect.Subscription = $current.Subscription.Id } } # Browser sign-in instead of the Windows account picker (WAM), and no subscription prompt; this session only $null = Update-AzConfig -EnableLoginByWam $false -LoginExperienceV2 Off -Scope Process -WhatIf:$false -WarningAction SilentlyContinue $null = Connect-AzAccount @connect -WarningAction SilentlyContinue -InformationAction SilentlyContinue } Export-ModuleMember -Function Enable-PimRole, Connect-PimAuthContext -Alias pim, pim-login |