[microsoft.ad.user] Add parameter to fail, ignore or warn if the account performing the action does not have the permissions required to modify the AD Group

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.