New Commandlets : Add-PnPFlowOwner & Remove-PnPFlowOwner

CHANGELOG.md

@@ -20,7 +20,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `SiteOwnerManageLegacyServicePrincipalEnabled` parameter to `Set-PnPTenant` cmdlet. With this parameter site owners will not be able to register/update apps unless the tenant admin explicitly allows it. [#3318](https://github.com/pnp/powershell/pull/3318)
 - Added `-EnableAutoExpirationVersionTrim`, `-ExpireVersionsAfterDays`, `-MajorVersions`, `-MinorVersions`, `-InheritTenantVersionPolicySettings`, `-StartApplyVersionPolicySettingToExistingDocLibs` and `-CancelApplyVersionPolicySettingToExistingDocLibs` to `Set-PnPSite` to allow for time based version expiration on the site level [#3373](https://github.com/pnp/powershell/pull/3373)
 - Added `-ReduceTempTokenLifetimeEnabled`, `-ReduceTempTokenLifetimeValue`, `-ViewersCanCommentOnMediaDisabled`, `-AllowGuestUserShareToUsersNotInSiteCollection`, `-ConditionalAccessPolicyErrorHelpLink`, `-CustomizedExternalSharingServiceUrl`, `-IncludeAtAGlanceInShareEmails` and `-MassDeleteNotificationDisabled` to `Set-PnPTenant` [#3348](https://github.com/pnp/powershell/pull/3348)
-
+- Added `Add-PnPFlowOwner` and `Remove-PnPFlowOwner` cmdlets which allow granting or removing permissions to a Power Automate flow [#3343](https://github.com/pnp/powershell/pull/3343)
+
 ### Fixed
 
 - Fixed `Add-PnPContentTypeToList` cmdlet to better handle piped lists. [#3244](https://github.com/pnp/powershell/pull/3244)

documentation/Add-PnPFlowOwner.md

@@ -0,0 +1,133 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Add-PnPFlowOwner.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Add-PnPFlowOwner
+---
+
+# Add-PnPFlowOwner
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Azure: management.azure.com
+
+Assigns/updates permissions to a Power Automate flow
+
+## SYNTAX
+
+```powershell
+Add-PnPFlowOwner -Environment <PowerAutomateEnvironmentPipeBind> -Identity <PowerPlatformPipeBind> -User <String> -Role <FlowAccessRole> [-AsAdmin] [-Verbose]
+```
+
+## DESCRIPTION
+This cmdlet assigns/updates permissions for a user to a Power Automate flow.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Add-PnPFlowOwner -Environment (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User [email protected] -Role CanEdit
+```
+Assigns the specified user with 'CanEdit' access level to the specified flow
+
+### Example 2
+```powershell
+Add-PnPFlowOwner -Environment (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User 6844c04a-8ee7-40ad-af66-28f6e948cd04 -Role CanView
+```
+Assigns the specified user with 'CanView' access level to the specified flow
+
+### Example 3
+```powershell
+Add-PnPFlowOwner -Environment (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User 6844c04a-8ee7-40ad-af66-28f6e948cd04 -Role CanViewWithShare
+```
+Assigns the specified user with 'CanViewWithShare' access level to the specified flow
+
+### Example 4
+```powershell
+Add-PnPFlowOwner -Environment (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User [email protected] -AsAdmin -Role CanEdit
+```
+Assigns the specified user with 'CanEdit' access level to the specified flow as admin
+
+## PARAMETERS
+
+### -Environment
+The Power Platform environment that hosts the Power Automate Flow to add the permissions to.
+
+```yaml
+Type: PowerAutomateEnvironmentPipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+The Name, Id or instance of the Power Automate Flow to add the permissions to.
+
+```yaml
+Type: PowerPlatformPipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -User
+The user principal name or Id of the user to assign permissions to the Power Automate Flow.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Role
+The type of permissions to assign to the user on the Power Automate Flow. Valid values: CanView, CanViewWithShare, CanEdit.
+
+```yaml
+Type: FlowUseFlowAccessRolerRoleName
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: CanView
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AsAdmin
+If specified, the permission will be set as an admin. If not specified only the flows to which the current user already has access can be modified.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+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/Remove-PnPFlowOwner.md

@@ -0,0 +1,133 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Remove-PnPFlowOwner.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Remove-PnPFlowOwner
+---
+
+# Remove-PnPFlowOwner
+
+## SYNOPSIS
+
+**Required Permissions**
+
+* Azure: management.azure.com
+
+Removes owner permissions to a Power Automate flow
+
+
+## SYNTAX
+
+```powershell
+Remove-PnPFlowOwner -Environment <PowerAutomateEnvironmentPipeBind> -Identity <PowerPlatformPipeBind> -User <String> [-AsAdmin] [-Force] [-Verbose]
+```
+
+## DESCRIPTION
+This cmdlet removes owner permissions for a user from a Power Automate flow.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Remove-PnPFlowOwner (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User [email protected]
+```
+Removes the specified user from the specified Power Automate flow
+
+### Example 2
+```powershell
+Remove-PnPFlowOwner (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User 6844c04a-8ee7-40ad-af66-28f6e948cd04
+```
+Removes the specified user from the specified Power Automate flow
+
+### Example 3
+```powershell
+Remove-PnPFlowOwner (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User [email protected] -AsAdmin
+```
+Removes the specified user from the specified Power Automate flow as an admin
+
+### Example 4
+```powershell
+Remove-PnPFlowOwner (Get-PnPPowerPlatformEnvironment -IsDefault) -Identity f07c34a9-a586-4e58-91fb-e7ea19741b61 -User [email protected] -AsAdmin -Force
+```
+Removes the specified user from the specified Power Automate Flow as admin, without asking for confirmation
+
+## PARAMETERS
+
+### -Environment
+The Power Platform environment that hosts the Power Automate Flow to remove the permissions from.
+
+```yaml
+Type: PowerAutomateEnvironmentPipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Identity
+The Name, Id or instance of the Power Automate Flow to add the permissions to.
+
+```yaml
+Type: PowerPlatformPipeBind
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -User
+The user principal name or Id of the user to remove its permissions from the Power Automate Flow.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -AsAdmin
+If specified, the permission will be removed as an admin. If not specified only the flows to which the current user already has access can be modified.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Force
+Providing the Force parameter will skip the confirmation question.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/Enums/FlowAccessRole.cs

@@ -0,0 +1,23 @@
+namespace PnP.PowerShell.Commands.Enums
+{
+    /// <summary>
+    /// Possible permissions for accessing a Power Automate flow
+    /// </summary>
+    public enum FlowAccessRole
+    {
+        /// <summary>
+        /// View only access level on the flow
+        /// </summary>
+        CanView,
+
+        /// <summary>
+        /// View with share access level on the flow
+        /// </summary>
+        CanViewWithShare,
+
+        /// <summary>
+        /// Edit access level on the flow
+        /// </summary>
+        CanEdit
+    }
+}

src/Commands/PowerPlatform/PowerAutomate/AddFlowOwner.cs

@@ -0,0 +1,88 @@
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Utilities.REST;
+using System;
+using System.Management.Automation;
+using System.Net;
+
+namespace PnP.PowerShell.Commands.PowerPlatform.PowerAutomate
+{
+    [Cmdlet(VerbsCommon.Add, "PnPFlowOwner")]
+    public class AddFlowOwner : PnPAzureManagementApiCmdlet
+    {
+        [Parameter(Mandatory = true)]
+        public PowerPlatformEnvironmentPipeBind Environment;
+
+        [Parameter(Mandatory = true)]
+        public PowerAutomateFlowPipeBind Identity;
+
+        [Parameter(Mandatory = true)]
+        public string User;
+
+        [Parameter(Mandatory = true)]
+        public Enums.FlowAccessRole Role = Enums.FlowAccessRole.CanView;
+
+        [Parameter(Mandatory = false)]
+        public SwitchParameter AsAdmin;
+
+        protected override void ExecuteCmdlet()
+        {
+            var environmentName = Environment.GetName();
+            if (string.IsNullOrEmpty(environmentName))
+            {
+                throw new PSArgumentException("Environment not found.", nameof(Environment));
+            }
+
+            var flowName = Identity.GetName();
+            if (string.IsNullOrEmpty(flowName))
+            {
+                throw new PSArgumentException("Flow not found.", nameof(Identity));
+            }
+
+            WriteVerbose("Acquiring access token for Microsoft Graph to look up user");
+
+            var graphAccessToken = TokenHandler.GetAccessToken(this, $"https://{Connection.GraphEndPoint}/.default", Connection);
+
+            WriteVerbose("Microsoft Graph access token acquired");
+
+            Model.AzureAD.User user;
+            if (Guid.TryParse(User, out Guid identityGuid))
+            {
+                WriteVerbose("Looking up user through Microsoft Graph by user id {identityGuid}");
+                user = Utilities.AzureAdUtility.GetUser(graphAccessToken, identityGuid);
+            }
+            else
+            {
+                WriteVerbose($"Looking up user through Microsoft Graph by user principal name {User}");
+                user = Utilities.AzureAdUtility.GetUser(graphAccessToken, WebUtility.UrlEncode(User));
+            }
+
+            if (user == null)
+            {
+                throw new PSArgumentException("User not found.", nameof(User));
+            }
+
+            var payload = new
+            {
+                put = new[]
+                {
+                    new
+                    {
+                        properties = new
+                        {
+                            principal = new
+                            {
+                                id = user.Id.Value,
+                                type = "User"
+                            },
+                            roleName = Role.ToString()
+                        }
+                    }
+                }
+            };
+
+            WriteVerbose($"Assigning user {Role} permissions to flow {flowName} in environment {environmentName}");
+            RestHelper.PostAsync(Connection.HttpClient, $"https://management.azure.com/providers/Microsoft.ProcessSimple{(AsAdmin ? "/scopes/admin" : "")}/environments/{environmentName}/flows/{flowName}/modifyPermissions?api-version=2016-11-01", AccessToken, payload).GetAwaiter().GetResult();
+        }
+    }
+}