From 3b0807ad7b283c46c21862eb826dcbb4ad04e5e2 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Thu, 18 Apr 2024 07:52:27 +0200 Subject: Merging upstream version 9.4.0+dfsg. Signed-off-by: Daniel Baumann --- .../microsoft/ad/plugins/modules/computer.py | 10 ++++++---- .../microsoft/ad/plugins/modules/domain.py | 2 ++ .../ad/plugins/modules/domain_controller.py | 1 + .../microsoft/ad/plugins/modules/group.py | 6 ++++-- .../microsoft/ad/plugins/modules/membership.ps1 | 22 ++++++++++++++++++++- .../microsoft/ad/plugins/modules/membership.py | 2 ++ .../microsoft/ad/plugins/modules/object.py | 2 ++ .../microsoft/ad/plugins/modules/object_info.ps1 | 12 ++++++++++- .../microsoft/ad/plugins/modules/object_info.py | 8 ++++++++ .../microsoft/ad/plugins/modules/offline_join.py | 2 ++ .../microsoft/ad/plugins/modules/ou.py | 2 ++ .../microsoft/ad/plugins/modules/user.ps1 | 3 ++- .../microsoft/ad/plugins/modules/user.py | 23 ++++++++++++++-------- 13 files changed, 78 insertions(+), 17 deletions(-) (limited to 'ansible_collections/microsoft/ad/plugins/modules') diff --git a/ansible_collections/microsoft/ad/plugins/modules/computer.py b/ansible_collections/microsoft/ad/plugins/modules/computer.py index 498b882ba..ab336d6b4 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/computer.py +++ b/ansible_collections/microsoft/ad/plugins/modules/computer.py @@ -184,6 +184,8 @@ notes: - See R(win_domain_computer migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_computer) for help on migrating from M(community.windows.win_domain_computer) to this module. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - microsoft.ad.ad_object - ansible.builtin.action_common_attributes @@ -223,12 +225,12 @@ EXAMPLES = r""" - name: Remove linux computer from Active Directory using a windows machine microsoft.ad.computer: - name: one_linux_server + identity: one_linux_server state: absent - name: Add SPNs to computer microsoft.ad.computer: - name: TheComputer + identity: TheComputer spn: add: - HOST/TheComputer @@ -237,7 +239,7 @@ EXAMPLES = r""" - name: Remove SPNs on the computer microsoft.ad.computer: - name: TheComputer + identity: TheComputer spn: remove: - HOST/TheComputer @@ -246,7 +248,7 @@ EXAMPLES = r""" - name: Set the principals the computer trusts for delegation from microsoft.ad.computer: - name: TheComputer + identity: TheComputer delegates: set: - CN=FileShare,OU=Computers,DC=domain,DC=test diff --git a/ansible_collections/microsoft/ad/plugins/modules/domain.py b/ansible_collections/microsoft/ad/plugins/modules/domain.py index 72d4fc21a..15578f7fd 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/domain.py +++ b/ansible_collections/microsoft/ad/plugins/modules/domain.py @@ -78,6 +78,8 @@ options: Sysvol file will be created. - If not set then the default path is C(%SYSTEMROOT%\SYSVOL). type: path +notes: +- This module must be run on a Windows target host. extends_documentation_fragment: - ansible.builtin.action_common_attributes - ansible.builtin.action_common_attributes.flow diff --git a/ansible_collections/microsoft/ad/plugins/modules/domain_controller.py b/ansible_collections/microsoft/ad/plugins/modules/domain_controller.py index 3ef2488bb..df4641741 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/domain_controller.py +++ b/ansible_collections/microsoft/ad/plugins/modules/domain_controller.py @@ -92,6 +92,7 @@ notes: - It is highly recommended to set I(reboot=true) to have Ansible manage the host reboot phase as the actions done by this module puts the host in a state where it may not be possible for Ansible to reconnect in a subsequent task without a reboot. +- This module must be run on a Windows target host. extends_documentation_fragment: - ansible.builtin.action_common_attributes - ansible.builtin.action_common_attributes.flow diff --git a/ansible_collections/microsoft/ad/plugins/modules/group.py b/ansible_collections/microsoft/ad/plugins/modules/group.py index d34e4584b..9fb28e819 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/group.py +++ b/ansible_collections/microsoft/ad/plugins/modules/group.py @@ -90,6 +90,8 @@ notes: - See R(win_group migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_group) for help on migrating from M(community.windows.win_domain_group) to this module. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - microsoft.ad.ad_object - ansible.builtin.action_common_attributes @@ -118,12 +120,12 @@ author: EXAMPLES = r""" - name: Ensure a group exists microsoft.ad.group: - name: Cow + identity: Cow scope: global - name: Remove a group microsoft.ad.group: - name: Cow + identity: Cow state: absent - name: Create a group in a custom path diff --git a/ansible_collections/microsoft/ad/plugins/modules/membership.ps1 b/ansible_collections/microsoft/ad/plugins/modules/membership.ps1 index 2b37bcdfd..d2be34e9f 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/membership.ps1 +++ b/ansible_collections/microsoft/ad/plugins/modules/membership.ps1 @@ -207,7 +207,27 @@ if ($state -eq 'domain') { $joinParams.OUPath = $domainOUPath } - Add-Computer @joinParams + try { + Add-Computer @joinParams + } + catch { + $failMsg = [string]$_ + + # The error if the domain_ou_path does not exist is a bit + # vague, we try to catch that specific error type and provide + # a more helpful hint to what is wrong. As the exception does + # not have an error code to check, we compare the Win32 error + # code message with a localized variant for + # ERROR_FILE_NOT_FOUND. .NET Framework does not end with . + # whereas .NET 5+ does so we use regex to match both patterns. + # https://github.com/ansible-collections/microsoft.ad/issues/88 + $fileNotFound = [System.ComponentModel.Win32Exception]::new(2).Message + if ($_.Exception.Message -match ".*$([Regex]::Escape($fileNotFound))\.?`$") { + $failMsg += " Check domain_ou_path is pointing to a valid OU in the target domain." + } + + $module.FailJson($failMsg, $_) + } $module.Result.changed = $true $module.Result.reboot_required = $true diff --git a/ansible_collections/microsoft/ad/plugins/modules/membership.py b/ansible_collections/microsoft/ad/plugins/modules/membership.py index f4d8521cf..87b4c85dc 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/membership.py +++ b/ansible_collections/microsoft/ad/plugins/modules/membership.py @@ -72,6 +72,8 @@ options: description: - When I(state=workgroup), this is the name of the workgroup that the Windows host should be in. type: str +notes: +- This module must be run on a Windows target host. extends_documentation_fragment: - ansible.builtin.action_common_attributes - ansible.builtin.action_common_attributes.flow diff --git a/ansible_collections/microsoft/ad/plugins/modules/object.py b/ansible_collections/microsoft/ad/plugins/modules/object.py index db7c7e5f6..c6396619a 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/object.py +++ b/ansible_collections/microsoft/ad/plugins/modules/object.py @@ -24,6 +24,8 @@ notes: Directory. It will not validate all the correct defaults are set for each type when it is created. If a type specific module is available to manage that AD object type it is recommend to use that. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - microsoft.ad.ad_object - ansible.builtin.action_common_attributes diff --git a/ansible_collections/microsoft/ad/plugins/modules/object_info.ps1 b/ansible_collections/microsoft/ad/plugins/modules/object_info.ps1 index d386417fd..4e304feeb 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/object_info.ps1 +++ b/ansible_collections/microsoft/ad/plugins/modules/object_info.ps1 @@ -46,6 +46,14 @@ $properties = $module.Params.properties $searchBase = $module.Params.search_base $searchScope = $module.Params.search_scope +# Attempt import of ActiveDirectory module +try { + Import-Module -Name ActiveDirectory +} +catch { + $module.FailJson("The ActiveDirectory module failed to load properly: $($_.Exception.Message)", $_) +} + $credential = $null if ($domainUsername) { $credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList @( @@ -223,7 +231,9 @@ try { # We run this in a custom PowerShell pipeline so that users of this module can't use any of the variables defined # above in their filter. While the cmdlet won't execute sub expressions we don't want anyone implicitly relying on # a defined variable in this module in case we ever change the name or remove it. - $ps = [PowerShell]::Create() + $iss = [InitialSessionState]::CreateDefault() + $iss.ImportPSModule("ActiveDirectory") + $ps = [PowerShell]::Create($iss) $null = $ps.AddCommand('Get-ADObject').AddParameters($commonParams).AddParameters($getParams) $null = $ps.AddCommand('Select-Object').AddParameter('Property', @('DistinguishedName', 'ObjectGUID')) diff --git a/ansible_collections/microsoft/ad/plugins/modules/object_info.py b/ansible_collections/microsoft/ad/plugins/modules/object_info.py index 0fe2f54ed..0cdcf06a7 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/object_info.py +++ b/ansible_collections/microsoft/ad/plugins/modules/object_info.py @@ -16,12 +16,16 @@ options: domain_password: description: - The password for I(domain_username). + - This can be set under the R(play's module defaults,module_defaults_groups) + under the C(group/microsoft.ad.domain) group. type: str domain_server: description: - Specified the Active Directory Domain Services instance to connect to. - Can be in the form of an FQDN or NetBIOS name. - If not specified then the value is based on the default domain of the computer running PowerShell. + - This can be set under the R(play's module defaults,module_defaults_groups) + under the C(group/microsoft.ad.domain) group. type: str domain_username: description: @@ -29,6 +33,8 @@ options: - If this is not set then the user that is used for authentication will be the connection user. - Ansible will be unable to use the connection user unless auth is Kerberos with credential delegation or CredSSP, or become is used on the task. + - This can be set under the R(play's module defaults,module_defaults_groups) + under the C(group/microsoft.ad.domain) group. type: str filter: description: @@ -88,6 +94,8 @@ notes: and C(userAccountControl_AnsibleFlags) return property is something set by the module itself as an easy way to view what those flags represent. These properties cannot be used as part of the I(filter) or I(ldap_filter) and are automatically added if those properties were requested. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - ansible.builtin.action_common_attributes attributes: diff --git a/ansible_collections/microsoft/ad/plugins/modules/offline_join.py b/ansible_collections/microsoft/ad/plugins/modules/offline_join.py index 0b07bc36f..f0c8aa54e 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/offline_join.py +++ b/ansible_collections/microsoft/ad/plugins/modules/offline_join.py @@ -85,6 +85,8 @@ notes: - Generating a new blob will reset the password of the computer object, take care that this isn't called under a computer account that has already been joined. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. seealso: - module: microsoft.ad.domain - module: microsoft.ad.membership diff --git a/ansible_collections/microsoft/ad/plugins/modules/ou.py b/ansible_collections/microsoft/ad/plugins/modules/ou.py index d7ac85007..5d1d60503 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/ou.py +++ b/ansible_collections/microsoft/ad/plugins/modules/ou.py @@ -49,6 +49,8 @@ notes: specified. - See R(win_domain_ou migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_ou) for help on migrating from M(community.windows.win_domain_ou) to this module. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - microsoft.ad.ad_object - ansible.builtin.action_common_attributes diff --git a/ansible_collections/microsoft/ad/plugins/modules/user.ps1 b/ansible_collections/microsoft/ad/plugins/modules/user.ps1 index d975272c7..267c77627 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/user.ps1 +++ b/ansible_collections/microsoft/ad/plugins/modules/user.ps1 @@ -39,6 +39,7 @@ Function Test-Credential { $failed_codes = @( 0x0000052E, # ERROR_LOGON_FAILURE 0x00000532, # ERROR_PASSWORD_EXPIRED + 0x00000701, # ERROR_ACCOUNT_EXPIRED 0x00000773, # ERROR_PASSWORD_MUST_CHANGE 0x00000533 # ERROR_ACCOUNT_DISABLED ) @@ -278,7 +279,7 @@ $setParams = @{ $SetParams.ServicePrincipalNames.Remove = $res.ToRemove } } - $module.Diff.after.kerberos_encryption_types = @($res.Value | Sort-Object) + $module.Diff.after.spn = @($res.Value | Sort-Object) } } diff --git a/ansible_collections/microsoft/ad/plugins/modules/user.py b/ansible_collections/microsoft/ad/plugins/modules/user.py index 30d1c6412..a3e7d1ecb 100644 --- a/ansible_collections/microsoft/ad/plugins/modules/user.py +++ b/ansible_collections/microsoft/ad/plugins/modules/user.py @@ -104,6 +104,10 @@ options: - To clear all group memberships, use I(set) with an empty list. - Note that users cannot be removed from their principal group (for example, "Domain Users"). Attempting to do so will display a warning. + - Each subkey is set to a list of groups objects to add, remove or + set as the membership of this AD user respectively. A group can be in + the form of a C(distinguishedName), C(objectGUID), C(objectSid), or + C(sAMAccountName). - See R(Setting list option values,ansible_collections.microsoft.ad.docsite.guide_list_values) for more information on how to add/remove/set list options. type: dict @@ -221,7 +225,8 @@ options: - C(always) will always update passwords. - C(on_create) will only set the password for newly created users. - C(when_changed) will only set the password when changed. - - Using C(when_changed) will not work if the account is not enabled. + - Using C(when_changed) will not work if the account is not enabled or is + expired. choices: - always - on_create @@ -244,6 +249,8 @@ options: notes: - See R(win_domain_user migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_user) for help on migrating from M(community.windows.win_domain_user) to this module. +- This module must be run on a Windows target host with the C(ActiveDirectory) + module installed. extends_documentation_fragment: - microsoft.ad.ad_object - ansible.builtin.action_common_attributes @@ -272,7 +279,7 @@ author: EXAMPLES = r""" - name: Ensure user bob is present with address information microsoft.ad.user: - name: bob + identity: bob firstname: Bob surname: Smith company: BobCo @@ -292,7 +299,7 @@ EXAMPLES = r""" - name: Ensure user bob is created and use custom credentials to create the user microsoft.ad.user: - name: bob + identity: bob firstname: Bob surname: Smith password: B0bP4ssw0rd @@ -303,7 +310,7 @@ EXAMPLES = r""" - name: Ensure user bob is present in OU ou=test,dc=domain,dc=local microsoft.ad.user: - name: bob + identity: bob password: B0bP4ssw0rd state: present path: ou=test,dc=domain,dc=local @@ -314,12 +321,12 @@ EXAMPLES = r""" - name: Ensure user bob is absent microsoft.ad.user: - name: bob + identity: bob state: absent - name: Ensure user has only these spn's defined microsoft.ad.user: - name: liz.kenyon + identity: liz.kenyon spn: set: - MSSQLSvc/us99db-svr95:1433 @@ -327,14 +334,14 @@ EXAMPLES = r""" - name: Ensure user has spn added microsoft.ad.user: - name: liz.kenyon + identity: liz.kenyon spn: add: - MSSQLSvc/us99db-svr95:2433 - name: Ensure user is created with delegates and spn's defined microsoft.ad.user: - name: shmemmmy + identity: shmemmmy password: The3rubberducki33! state: present groups: -- cgit v1.2.3