[microsoft.ad.user] Add parameter to fail, ignore or warn if the acco…

…unt performing the action does not have the permissions required to modify the AD Group (#166)

This feature adds a new sub-parameter to the Groups section similar to lookup_failure_action to aid the scenario when the account used to add or remove the user from the specified AD Groups does not have appropriate permissions to perform the action.

This is achieved through wrapping the add or remove attempts around a try/catch and handling the try/catch based on the parameters specified.

Parameters accepted are fail, ignore, and warn
Default action is: fail

changelogs/fragments/user-permissions-handling.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - >-
+    microsoft.ad.user - Added ``groups.permissions_failure_action`` to control the behaviour when failing to modify the user's groups -
+    (https://github.com/ansible-collections/microsoft.ad/issues/140).

plugins/modules/user.ps1

@@ -141,6 +141,12 @@ $setParams = @{
                         default = 'fail'
                         type = 'str'
                     }
+                    permissions_failure_action = @{
+                        choices = 'fail', 'ignore', 'warn'
+                        default = 'fail'
+                        type = 'str'
+                    }
+
                 }
             }
         }
@@ -396,7 +402,7 @@ $setParams = @{
         }
         $dnServerParams = @{}
         foreach ($actionKvp in $Module.Params.groups.GetEnumerator()) {
-            if ($null -eq $actionKvp.Value -or $actionKvp.Key -in @('lookup_failure_action', 'missing_behaviour')) {
+            if ($null -eq $actionKvp.Value -or $actionKvp.Key -in @('lookup_failure_action', 'missing_behaviour', 'permissions_failure_action')) {
                 continue
             }
 
@@ -448,10 +454,21 @@ $setParams = @{
                     $ADParams
                 }
                 if ($ADObject) {
-                    Set-ADObject -Identity $member -Add @{
-                        member = $ADObject.DistinguishedName
-                    } @lookupParams @commonParams
-
+                    try {
+                        Set-ADObject -Identity $member -Add @{
+                            member = $ADObject.DistinguishedName
+                        } @lookupParams @commonParams
+                    }
+                    catch [Microsoft.ActiveDirectory.Management.ADException] {
+                        if ($Module.Params.groups.permissions_failure_action -ne "fail") {
+                            if ($Module.Params.groups.permissions_failure_action -eq "warn") {
+                                $Module.Warn("Cannot add group '$member'. You do not have the required permissions, skipping: $($_.Exception.Message)")
+                            }
+                        }
+                        else {
+                            throw
+                        }
+                    }
                 }
                 $Module.Result.changed = $true
             }
@@ -479,6 +496,11 @@ $setParams = @{
                             }
                             $Module.Diff.after.groups = @($Module.Diff.after.groups; $member)
                         }
+                        elseif ($Module.Params.groups.permissions_failure_action -ne "fail") {
+                            if ($Module.Params.groups.permissions_failure_action -eq "warn") {
+                                $Module.Warn("Cannot remove group '$member'. You do not have the required permissions, skipping: $($_.Exception.Message)")
+                            }
+                        }
                         else {
                             throw
                         }

plugins/modules/user.yml

@@ -159,9 +159,9 @@ DOCUMENTATION:
           description:
             - Controls what happens when a group specified by C(groups) is an
               invalid group name.
-            - C(fail) is the default and will return an error any groups do not
+            - C(fail) is the default and will return an error if any groups do not
               exist.
-            - C(ignore) will ignore any groups that does not exist.
+            - C(ignore) will ignore any groups that do not exist.
             - C(warn) will display a warning for any groups that do not exist
               but will continue without failing.
           aliases:
@@ -172,6 +172,22 @@ DOCUMENTATION:
             - warn
           default: fail
           type: str
+        permissions_failure_action:
+          description:
+            - Controls what happens when a group specified by C(groups) is not
+              able to be modified by the user specified by C(domain_username)
+            - C(fail) is the default and will return an erro if any groups
+              membership is not modifiable by the user.
+            - C(ignore) will ignore any groups that cannot be modified.
+            - C(warn) will display a warning for any groups that cannot be
+              modified but will continue without failing.
+          choices:
+            - fail
+            - ignore
+            - warn
+          default: fail
+          type: str
+          version_added: 1.8.0
     password:
       description:
         - Optionally set the user's password to this (plain text) value.