Adding cmdlets which allow PIM activation

CHANGELOG.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 ### Added
 
 - Added `Reset-PnPDocumentID` cmdlet to request resetting the document ID for a document [#4238](https://github.com/pnp/powershell/pull/4238)
+- Added `Get-PnPPriviledgedIdentityManagementEligibleAssignment`, `Get-PnPPriviledgedIdentityManagementRole` and `Enable-PnPPriviledgedIdentityManagement` cmdlets to allow scripting of enabling Privileged Identity Management roles for a user [#4039](https://github.com/pnp/powershell/pull/4039)
 
 ### Changed
 
@@ -92,6 +93,7 @@ Fixed app registration on Windows
 ## [2.8.0]
 
 ### Added
+
 - Added in depth verbose logging to all cmdlets which is revealed by adding `-Verbose` to the cmdlet execution [#4023](https://github.com/pnp/powershell/pull/4023)
 - Added `-CoreDefaultShareLinkScope` and `-CoreDefaultShareLinkRole` parameters to `Set-PnPTenant` cmdlet. [#4067](https://github.com/pnp/powershell/pull/4067)
 - Added `-Identity` parameter to the `Get-PnPFileSharingLink` cmdlet allowing for the retrieval of sharing links based on the file's unique identifier, file instance, listitem instance, or server relative path and supporting retrieval of sharing links for multiple files, such as all in a document library [#4093](https://github.com/pnp/powershell/pull/4093)
@@ -102,12 +104,14 @@ Fixed app registration on Windows
 - Added `-Folder` parameter to `Add-PnPDocumentSet` cmdlet to allow creation of document sets in a specific folder instead of the list root folder. [#4029](https://github.com/pnp/powershell/pull/4029)
 
 ### Fixed
+
 - `Get-PnPTeamsChannel` and `Get-PnPTeamsPrimaryChannel` returning `unknownFutureValue` as MembershipType instead of `shared` [#4054](https://github.com/pnp/powershell/pull/4054)
 - Fixed using a AzureADUserPipeBind with `New-PnPAzureADUserTemporaryAccessPass`, `Get-PnPAvailableSensitivityLabel` and `Set-PnPSearchExternalItem` to not work when passing in the User ID GUID [#4123](https://github.com/pnp/powershell/pull/4123)
 - Fixed issue with `Get-PnPWebHeader` cmdlet not working properly in Group connected SharePoint sites. [#4147](https://github.com/pnp/powershell/pull/4147)
 - Fixed issue with `Get-PnPTeamsChannelFilesFolder` cmdlet to work properly for channels having data more than 2 GB. [#4127](https://github.com/pnp/powershell/pull/4127)
 
 ### Changed
+
 - Fixed `Update-PnPTeamsUser` cmdlet to throw a better error message when after a user is removed from a Team but is still in the connected M365 group, for the few seconds that the 2 are out of sync. [#4068](https://github.com/pnp/powershell/pull/4068)
 - Changed `-FileUrl` on `Get-PnPFileSharingLink` to become obsolete. Please switch to using `-Identity` instead, passing in the same value [#4093](https://github.com/pnp/powershell/pull/4093)
 

documentation/Enable-PnPPriviledgedIdentityManagement.md

@@ -0,0 +1,183 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Enable-PnPPriviledgedIdentityManagement.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Enable-PnPPriviledgedIdentityManagement
+---
+
+# Enable-PnPPriviledgedIdentityManagement
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Microsoft Graph: RoleAssignmentSchedule.ReadWrite.Directory
+
+Temporarily enables a Privileged Identity Management role for a user
+
+## SYNTAX
+
+### By Role Name And Principal 
+
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role <PriviledgedIdentityManagementRolePipeBind> [-PrincipalId <Guid>] [-Justification <string>] [-StartAt <DateTime>] [-ExpireInHours <short>] [-Connection <PnPConnection>] 
+```
+
+### By Role Name And User
+
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role <PriviledgedIdentityManagementRolePipeBind> -User <AzureADUserPipeBind> [-Justification <string>] [-StartAt <DateTime>] [-ExpireInHours <short>] [-Connection <PnPConnection>] 
+```
+
+### By Eligible Role Assignment
+
+```powershell
+Enable-PnPPriviledgedIdentityManagement -EligibleAssignment <PriviledgedIdentityManagementRolePipeBind> [-Justification <string>] [-StartAt <DateTime>] [-ExpireInHours <short>] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+Temporarily enables a Privileged Identity Management role for the provided allowing the user to perform actions that require the role. The role will be enabled starting at the specified date and time and will expire after the specified number of hours. The reason for the elevation of rights can be provided as justification.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role "Global Administrator"
+```
+
+Enables the global administrator role for the current user through Privileged Identity Management starting immediately and expiring in 1 hour
+
+### Example 2
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role "Global Administrator" -Justification "Just because"
+```
+
+Enables the global administrator role for the current user through Privileged Identity Management starting immediately and expiring in 1 hour, adding the justification provided to be logged as the reason for the elevation of rights
+
+### Example 3
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role "Global Administrator" -Justification "Just because" -StartAt (Get-Date).AddHours(2) -ExpireInHours 2
+```
+
+Enables the global administrator role for the current user through Privileged Identity Management starting in 2 hours from now and expiring 2 hours thereafter, adding the justification provided to be logged as the reason for the elevation of rights
+
+### Example 4
+```powershell
+Enable-PnPPriviledgedIdentityManagement -Role "Global Administrator" -User "someone@contoso.onmicrosoft.com"
+```
+
+Enables the global administrator role for the provided user through Privileged Identity Management starting immediately and expiring in 1 hour
+
+## PARAMETERS
+
+### -Connection
+Optional connection to be used by the cmdlet.
+Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ExpireInHours
+Indication of after how many hours the elevation should expire. If omitted, the default value is 1 hour.
+
+```yaml
+Type: short
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: 1
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Justification
+Text to be logged as the reason for the elevation of rights. If omitted, the default value is "Elevated by PnP PowerShell".
+
+```yaml
+Type: string
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: "Elevated by PnP PowerShell"
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -PrincipalId
+The Id of of the principal to elevate. If omitted, the default value is the current user, if the connection has been made using a delegated identity. With an application identity, this parameter is required.
+
+```yaml
+Type: Guid
+Parameter Sets: By Role Name And Principal
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Role
+The Id, name or instance of a role to elevate the current user to. Use `Get-PnPPriviledgedIdentityManagementRole` to retrieve the available roles.
+
+```yaml
+Type: PriviledgedIdentityManagementRolePipeBind
+Parameter Sets: By Role Name And Principal, By Role Name And User
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -StartAt
+Date and time at which to start the elevation. If omitted, the default value is the current date and time, meaning the activation will happen immediately.
+
+```yaml
+Type: DateTime
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: Get-Date
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -User
+The Id, username or instance of a user which needs to be elevated
+
+```yaml
+Type: AzureADUserPipeBind
+Parameter Sets: By Role Name And User
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Get-PnPPriviledgedIdentityManagementEligibleAssignment.md

@@ -0,0 +1,80 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPPriviledgedIdentityManagementEligibleAssignment.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPPriviledgedIdentityManagementEligibleAssignment
+---
+
+# Get-PnPPriviledgedIdentityManagementEligibleAssignment
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Microsoft Graph: RoleAssignmentSchedule.Read.Directory
+
+Retrieve the available Privileged Identity Management eligibility assignment roles that exist within the tenant
+
+## SYNTAX
+
+```powershell
+Get-PnPPriviledgedIdentityManagementEligibleAssignment [-Identity <PriviledgedIdentityManagementRoleEligibilitySchedulePipeBind>] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+Retrieve the available Privileged Identity Management eligibility assignment roles that exist within the tenant. These are the configured users with the configured roles they can be elevated to.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Get-PnPPriviledgedIdentityManagementEligibleAssignment
+```
+
+Retrieves the available Privileged Identity Management eligibility assignment roles 
+
+### Example 2
+```powershell
+Get-PnPPriviledgedIdentityManagementEligibleAssignment -Identity 62e90394-69f5-4237-9190-012177145e10
+```
+
+Retrieves the Privileged Identity Management eligibility assignment role with the provided id
+
+## PARAMETERS
+
+### -Connection
+Optional connection to be used by the cmdlet.
+Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+The name, id or instance of a Priviledged Identity Management eligibility assignment role to retrieve the details of
+
+```yaml
+Type: PriviledgedIdentityManagementRoleEligibilitySchedulePipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Get-PnPPriviledgedIdentityManagementRole.md

@@ -0,0 +1,87 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPPriviledgedIdentityManagementRole.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPPriviledgedIdentityManagementRole
+---
+
+# Get-PnPPriviledgedIdentityManagementRole
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Microsoft Graph: RoleManagement.Read.Directory
+
+Retrieve the available Privileged Identity Management roles that exist within the tenant
+
+## SYNTAX
+
+```powershell
+Get-PnPPriviledgedIdentityManagementRole [-Identity <PriviledgedIdentityManagementRolePipeBind>] [-Connection <PnPConnection>] 
+```
+
+## DESCRIPTION
+Retrieve the available Privileged Identity Management roles that exist within the tenant. These are the roles to which elevation can take place.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Get-PnPPriviledgedIdentityManagementRole
+```
+
+Retrieves the available Privileged Identity Management roles
+
+### Example 2
+```powershell
+Get-PnPPriviledgedIdentityManagementRole -Identity "Global Administrator"
+```
+
+Retrieves the Privileged Identity Management with the provided name
+
+### Example 3
+```powershell
+Get-PnPPriviledgedIdentityManagementRole -Identity 62e90394-69f5-4237-9190-012177145e10
+```
+
+Retrieves the Privileged Identity Management role with the provided id
+
+## PARAMETERS
+
+### -Connection
+Optional connection to be used by the cmdlet.
+Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+The name, id or instance of a Priviledged Identity Management role to retrieve the details of
+
+```yaml
+Type: PriviledgedIdentityManagementRolePipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)