diff --git a/README.md b/README.md index befc049..09c9b09 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # EasyPIM V1.1.0 -Powershell module to manage PIM Azure Resource Role settings with simplicity in mind. -Easily manage settings at the subscription level : enter a tenant ID, a subscription ID, a role name -then the options you want to set, for example require justification on activation. +Powershell module to manage PIM Azure Resource Role settings with simplicity in mind. -With the export function you can edit your PIM settings in Excel then import your changes :wink: +Easily manage PIM Azure Resource settings **at the subscription level by default** : enter a tenant ID, a subscription ID, a role name +then the options you want to set, for example require justification on activation. +:new: If you want to manage the role at another level (Management Group, Resource Group or Resource) please use the `scope` parameter instead of the `subscriptionID`. ## Key features :boom: Support editing multiple roles at once @@ -13,21 +13,19 @@ With the export function you can edit your PIM settings in Excel then import you :boom: Import role settings from csv :boom: Backup all roles -![image](https://github.com/kayasax/EasyPIM/assets/1241767/79086c31-19fa-4321-a5ac-6767b8d7ace3) +With the export function you can now edit your PIM settings in Excel then import back your changes :wink: ## Installation This module is available in the PowerShell gallery: [https://www.powershellgallery.com/packages/EasyPIM/](https://www.powershellgallery.com/packages/EasyPIM/), install it with: ```pwsh Install-Module -Name EasyPIM -Scope CurrentUser ``` -## Changelog -V1.1.0 -* You can now use the scope paramater to get/set role policy on a management group, a resource group or a resource. -If not set we would expect subscription as the default scope and $subscriptionID will be required -ex for a management group: -`$scope="providers/Microsoft.Management/managementGroups/MG_All_Subscriptions"` + +![image](https://github.com/kayasax/EasyPIM/assets/1241767/79086c31-19fa-4321-a5ac-6767b8d7ace3) + ## Sample usage + :large_blue_diamond: Get configuration of the role "Webmaster" ```pwsh Get-PIMAzureResourcePolicy -TenantID -SubscriptionId -rolename "webmaster" @@ -49,76 +47,15 @@ Set-PIMAzureResourcePolicy -TenantID -SubscriptionId ```pwsh Set-PIMAzureResourcePolicy -TenantID -SubscriptionId -rolename "webmaster" -ActivationDuration "PT12H" ``` +More samples in the [documentation](https://github.com/kayasax/EasyPIM/wiki/Documentation) +## Requirement +* Az.Accounts module +* Permission: +The PIM API for Azure resource roles is developed on top of the Azure Resource Manager framework. You will need to give consent to Azure Resource Management but won’t need any Microsoft Graph API permission. You will also need to make sure the user or the service principal calling the API has at least the Owner or User Access Administrator role on the resource you are trying to administer. -:large_blue_diamond: Copy settings from the role Contributor to the roles webmaster and role1 -```pwsh -Copy-PIMAzureResourcePolicy -TenantID -SubscriptionId -rolename "webmaster", "role1" -copyFrom "contributor" -``` - - -:large_blue_diamond: Export role settings to CSV -```pwsh -Export-PIMAzureResourcePolicy -TenantID -SubscriptionId -rolename "webmaster","contributor" -export -exportFilename .\EXPORTS\roles.csv -``` - - -:large_blue_diamond: Import role settings from CSV -```pwsh -Import-PIMAzureResourcePolicy -TenantID -SubscriptionId -import "c:\temp\roles.csv" -``` - +## Documentation +[documentation](https://github.com/kayasax/EasyPIM/wiki/Documentation) -:large_blue_diamond: Backup (export all roles) -```pwsh -Backup-PIMAzureResourcePolicy -TenantID -SubscriptionId -``` -## Requirement -* Graph permissions: RoleManagementPolicy.ReadWrite.Directory, RoleManagement.ReadWrite.Directory -* Azure PowerShell: https://learn.microsoft.com/en-us/powershell/azure/install-azure-powershell?view=azps-11.1.0 - -## Configuration -* Enable file logging : set **$logToFile** to **$true** -* You can receive fatal error in a Teams channel: set **$TeamsNotif** to **$true** and configure your Teams Inbound WebHook URL in **$teamsWebhookURL** - -## Parameters - -|Parameter|description| -|---|---| -|`$TenantID`| Entra ID TenantID| -|`$SubscriptionId`| Subscription ID| -|`$rolename`| name of the roles to update/export ex `-rolename "webmaster","contributor"`| -|`[Switch] $show`| show current config only, no change made| -|`[Switch] $export`| export role config to csv| -|`$exportFilename`| save export to this file, if not specified it will create a new file in the EXPORTS folder with curent timestamp| -|`$import`| import settings from this csv file ex `-import c:\temp\myfile.csv`| -|`$copyFrom`| copy settings from this role name ex `-copyFrom "contributor"`| -|`[Switch] $backup`| backup all roles to csv | -|`$ActivationDuration`| Maximum activation duration (Duration ref https://en.wikipedia.org/wiki/ISO_8601#Durations)| -|`$ActivationRequirement `| Accepted values: "None" or one or more options from "Justification", "MultiFactorAuthentication", "Ticketing" ex `-ActivationRequirement "justification","Ticketing"` WARNING: options are CASE SENSITIVE!| -|`$ApprovalRequired`| Is approval required to activate a role? ($true/$false)| -|`$Approvers`| Array of approvers in the format: @(@{"Id"="XXXXXX";"Name"="John":"Type"="user/group"}, .... )| -|`$MaximumEligibilityDuration`| Maximum Eligility Duration (ref https://en.wikipedia.org/wiki/ISO_8601#Durations)| -|`$AllowPermanentEligibility`| Allow permanent eligibility? ($true/$false)| -|`$MaximumActiveAssignmentDuration`| Maximum active assignment duration (# Duration )ref https://en.wikipedia.org/wiki/ISO_8601#Durations)| -|`$AllowPermanentActiveAssignment`| Allow permanent active assignement? ($true|$false)| -|`$Notification_EligibleAssignment_Alert`| Admin Notification when eligible role is assigned, rule 9 see Notification Format| -|`$Notification_EligibleAssignment_Assignee`| End-user notification when eligible role is assigned, rule 10 see Notification Format| -|`$Notification_EligibleAssignment_Approver`| Approver notification when eligible role is assigned, rule 11 see Notification Format| -|`$Notification_ActiveAssignment_Alert`| Admin Notification when an active role is assigned, rule 12 see Notification Format| -|`$Notification_ActiveAssignment_Assignee`| End user Notification when an active role is assigned, rule 13 see Notification Format| -|`$Notification_ActiveAssignment_Approver`| Approver Notification when an active role is assigned, rule 14see Notification Format| -|`$Notification_Activation_Alert`| Admin Notification when a role is activated, rule 15 see Notification Format| -|`$Notification_Activation_Assignee`| End user Notification when a role is activated, rule 16 see Notification Format| -|`$Notification_Activation_Approver`| Approvers Notification when a role is activated, rule 17 see Notification Format| - - - -### Notification format -All Notifications accept value with the following format: -```pwsh -EasyPIM.ps1 -Notification_Activation_Alert @{"isDefaultRecipientEnabled"="true|false"; "notificationLevel"="All|Critical";"Recipients" = @("email1@domain.com","email2@domain.com")} -``` -![image](https://github.com/kayasax/EasyPIM/assets/1241767/5da187a5-a51b-48d0-ba80-dad0fc73bfaf)