From 70dc89ee4119fc7345764df081cc01fbd2173c30 Mon Sep 17 00:00:00 2001 From: tarmael Date: Fri, 15 Nov 2024 09:59:05 +1000 Subject: [PATCH 1/8] Adding new Groups flag, permissions_failure_action 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 --- plugins/modules/user.ps1 | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/plugins/modules/user.ps1 b/plugins/modules/user.ps1 index 8eef496..dfe8ad7 100644 --- a/plugins/modules/user.ps1 +++ b/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', 'permission_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 } From 89d7ff05a6a5f200cc668cabc332f99ca94f2f03 Mon Sep 17 00:00:00 2001 From: tarmael Date: Fri, 15 Nov 2024 10:04:19 +1000 Subject: [PATCH 2/8] Correcting a missed variable --- plugins/modules/user.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/user.ps1 b/plugins/modules/user.ps1 index dfe8ad7..e5b60c2 100644 --- a/plugins/modules/user.ps1 +++ b/plugins/modules/user.ps1 @@ -402,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', 'permission_failure_action')) { + if ($null -eq $actionKvp.Value -or $actionKvp.Key -in @('lookup_failure_action', 'missing_behaviour', 'permissions_failure_action')) { continue } From ce25f75a8a246ed5f604ba8acd13f9a41a95c800 Mon Sep 17 00:00:00 2001 From: tarmael Date: Fri, 15 Nov 2024 10:11:58 +1000 Subject: [PATCH 3/8] Updating docs page Minor update to the wording of lookup_failure_action as well --- plugins/modules/user.yml | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/plugins/modules/user.yml b/plugins/modules/user.yml index 10d705a..7a16e72 100644 --- a/plugins/modules/user.yml +++ b/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,21 @@ 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 error 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 password: description: - Optionally set the user's password to this (plain text) value. From ddb9b1c3903424f9006a9bc8bb0aafa9daec2d03 Mon Sep 17 00:00:00 2001 From: tarmael Date: Fri, 15 Nov 2024 14:14:35 +1000 Subject: [PATCH 4/8] Correcting docs from failing build tests --- plugins/modules/user.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/user.yml b/plugins/modules/user.yml index 7a16e72..0dc3945 100644 --- a/plugins/modules/user.yml +++ b/plugins/modules/user.yml @@ -177,7 +177,7 @@ DOCUMENTATION: - 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 error if any groups - membership is not modifiable by the user. + 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. From 17d8403a44120a777fc1376b6636fc0ca96408b1 Mon Sep 17 00:00:00 2001 From: tarmael Date: Fri, 15 Nov 2024 14:20:35 +1000 Subject: [PATCH 5/8] Update user.yml Doc fix for linting --- plugins/modules/user.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/modules/user.yml b/plugins/modules/user.yml index 0dc3945..cbea917 100644 --- a/plugins/modules/user.yml +++ b/plugins/modules/user.yml @@ -176,7 +176,7 @@ DOCUMENTATION: 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 error if any groups + - 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 From 8875f96ee5ae0b39cfab92e00dd6a86850d5a49d Mon Sep 17 00:00:00 2001 From: tarmael Date: Tue, 19 Nov 2024 14:38:13 +1000 Subject: [PATCH 6/8] Including version_added doc string per maintainer suggestion Co-authored-by: Jordan Borean --- plugins/modules/user.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/modules/user.yml b/plugins/modules/user.yml index cbea917..337195b 100644 --- a/plugins/modules/user.yml +++ b/plugins/modules/user.yml @@ -187,6 +187,7 @@ DOCUMENTATION: - warn default: fail type: str + version_added: 1.8.0 password: description: - Optionally set the user's password to this (plain text) value. From 2429dc85b5a62e6db2e6d072052b5f6edeb5a936 Mon Sep 17 00:00:00 2001 From: tarmael Date: Tue, 19 Nov 2024 14:44:41 +1000 Subject: [PATCH 7/8] Creating Changelog Fragment user-permissions-handling.yml --- changelogs/fragments/user-permissions-handling.yml | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 changelogs/fragments/user-permissions-handling.yml diff --git a/changelogs/fragments/user-permissions-handling.yml b/changelogs/fragments/user-permissions-handling.yml new file mode 100644 index 0000000..0a77ecd --- /dev/null +++ b/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 From 746f79c26350c0704875ab09e9975856392614c8 Mon Sep 17 00:00:00 2001 From: tarmael Date: Tue, 19 Nov 2024 15:00:13 +1000 Subject: [PATCH 8/8] Update user-permissions-handling.yml Conforming changelog fragment to Ansible Fragment standards --- changelogs/fragments/user-permissions-handling.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelogs/fragments/user-permissions-handling.yml b/changelogs/fragments/user-permissions-handling.yml index 0a77ecd..31d2a1c 100644 --- a/changelogs/fragments/user-permissions-handling.yml +++ b/changelogs/fragments/user-permissions-handling.yml @@ -1,4 +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 + (https://github.com/ansible-collections/microsoft.ad/issues/140).