microsoft.ad.computer 模块 – 管理 Active Directory 计算机对象

注意

此模块是 microsoft.ad 集合（版本 1.7.1）的一部分。

如果您正在使用 ansible 包，您可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install microsoft.ad。您需要进一步的要求才能使用此模块，请参阅 要求 了解详细信息。

要在 playbook 中使用它，请指定：microsoft.ad.computer。

概要

  • 管理 Active Directory 计算机对象及其属性。

要求

执行此模块的主机需要以下要求。

  • ActiveDirectory PowerShell 模块

参数

参数

注释

属性

字典

要在 AD 对象上添加、删除或设置的属性。

每个属性选项的值应该是一个字典，其中键是 LDAP 属性，例如 firstName、comment，值是要为该属性设置的值或值列表。

属性值可以是原始字符串、整数或布尔值，以便在相关属性上添加、删除或设置。

该值也可以是一个字典，其中 type 键设置为 bytes、date_time、security_descriptor 或 raw，并且此条目的值在 value 键下。

bytes 类型的值是原始字节的 base64 编码字符串，用于设置。

date_time 类型的值是要设置的 DateTime 的 ISO 8601 DateTime 字符串。DateTime 将设置为 Microsoft FILETIME 整数值，它是自 1601-01-01 UTC 以来 100 纳秒的计数。

security_descriptor 类型的值是用于 nTSecurityDescriptor 属性的安全描述符 SDDL 字符串。

raw 类型是要设置的 int、字符串或布尔值。

字符串属性值使用区分大小写的匹配来比较被管理的 AD 对象。

有关详细信息，请参阅 LDAP 属性帮助。

默认： {}

添加

字典

所有属性及其值的字典，如果它们尚未存在，则添加到被管理的 AD 对象。

这用于可以包含多个值的属性，如果该属性仅允许单个值，请改用 set。

默认： {}

删除

字典

所有属性及其值的字典，如果它们存在，则从被管理的 AD 对象中删除。

这用于可以包含多个值的属性，如果该属性仅允许单个值，请改用 set。

默认： {}

设置

字典

所有属性及其值的字典，以设置到被管理的 AD 对象上。

如果它们与请求的值不匹配，则这将替换任何现有值。

不检查属性值的顺序，仅检查请求的值是否是对象属性上唯一的值。

将此设置为 null 或空列表以清除该属性的任何值。

默认： {}

委托

别名：principals_allowed_to_delegate

字典

当前 AD 对象可以信任以进行委派的主体对象，以便添加、删除或设置。

每个子键值都是 distinguishedName、objectGUID、objectSid、sAMAccountName 或 userPrincipalName 字符串形式的值列表或带有 name 和可选 server 键的字典。

这是在 msDS-AllowedToActOnBehalfOfOtherIdentity LDAP 属性上设置的值。

这是一个高度敏感的属性，因为它允许指定的主体在与被管理的 AD 计算机对象进行身份验证时模拟任何帐户。

要清除所有主体，请使用带空列表的 set。

有关 DN 查找如何工作的更多信息，请参阅 DN 查找属性。

有关如何添加/删除/设置列表选项的更多信息，请参阅 设置列表选项值。

add

list / elements=any

添加指定的主体作为允许委派的主体。

除非由 remove 指定或不在 set 中，否则任何未由 add 指定的现有主体将保持不变。

lookup_failure_action

string

控制在查找失败时采取的操作，以查找 DN。

fail 将导致任务失败。

ignore 将忽略该值并继续。

warn 将忽略该值并显示警告。

选择

  • "fail" ← (默认)

  • "ignore"

  • "warn"

remove

list / elements=any

删除指定的主体作为允许委派的主体。

除非定义了 set，否则任何未由 remove 指定的现有主体将保持不变。

set

list / elements=any

将指定的主体设置为允许委派的主体。

如果未在此列表中指定，这将删除任何现有的主体。

指定一个空列表以删除所有允许委派的主体。

description

string

要设置的 AD 对象的描述。

这是在 description LDAP 属性上设置的值。

display_name

string

要设置的 AD 对象的显示名称。

这是 displayName LDAP 属性的值。

dns_hostname

string

指定计算机的完全限定域名 (FQDN)。

这是在 dNSHostName LDAP 属性上设置的值。

do_not_append_dollar_to_sam

boolean

在 microsoft.ad 1.7.0 中添加

不要自动将 $ 附加到 sam_account_name 值。

这仅在显式设置 sam_account_name 时适用，并且可以用于创建不带 $ 后缀的计算机帐户。

选择

  • false ← (默认)

  • true

domain_credentials

list / elements=dictionary

指定在使用 name 指定的服务器时应使用的凭据。

要指定默认域服务器的凭据，请使用不带 name 键的条目，或使用 domain_username 和 domain_password 选项。

可以在 play 的模块默认值 下的 group/microsoft.ad.domain 组中设置此值。

有关更多信息，请参阅 模块中的 AD 身份验证。

默认: []

name

string

这些凭据所针对的服务器的名称。

此值应与在指定要使用的自定义服务器的其他选项中使用的值相对应，例如引用位于不同 AD 服务器上的 AD 标识的选项。

可以在一个条目中省略此键，以指定在未指定服务器时要使用的默认凭据，而不是使用 domain_username 和 domain_password。

password

string / required

连接到由 name 指定的服务器时要使用的密码。

username

string / required

连接到由 name 指定的服务器时要使用的用户名。

domain_password

string

domain_username 的密码。

不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。

可以在 play 的模块默认值 下的 group/microsoft.ad.domain 组中设置此值。

domain_server

string

指定要连接的 Active Directory 域服务实例。

可以是 FQDN 或 NetBIOS 名称的形式。

如果未指定，则该值基于运行 PowerShell 的计算机的默认域。

可以在不带 name 键的 domain_credentials 条目下或通过 domain_username 和 domain_password 指定自定义凭据。

可以在 play 的模块默认值 下的 group/microsoft.ad.domain 组中设置此值。

domain_username

string

与 AD 交互时要使用的用户名。

如果未设置此项，则用于身份验证的用户将为连接用户。

除非身份验证是具有凭据委派或 CredSSP 的 Kerberos，或者在任务上使用了 become，否则 Ansible 将无法使用连接用户。

不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。

可以在 play 的模块默认值 下的 group/microsoft.ad.domain 组中设置此值。

enabled

boolean

yes 将启用计算机。

no 将禁用计算机。

选择

  • false

  • true

identity

string

用于查找要管理的 AD 对象的 AD 对象的标识。

如果未设置 name，尝试使用新 name 重命名对象或尝试将对象移动到不同的 path 中时，必须指定此项。

标识可以是表示 objectGUID 值的 GUID，userPrincipalName，sAMAccountName，objectSid 或 distinguishedName 的形式。

如果省略，则要管理的 AD 对象将使用 distinguishedName（格式为 CN={{ name }},{{ path }}）选择。如果未定义 path，则改用 defaultNamingContext。

当使用 microsoft.ad.computer 模块时，如果提供的值没有导致匹配并且末尾没有 $，则标识将自动在 sAMAccountName 的末尾附加 $。

kerberos_encryption_types

字典

指定 AD 计算机帐户支持的 Kerberos 加密类型。

这是在 msDS-SupportedEncryptionTypes LDAP 属性上设置的值。

避免使用 rc4 或 des，因为它们是较旧且不安全的加密协议。

要清除所有加密类型，请使用带空列表的 set。

有关如何添加/删除/设置列表选项的更多信息，请参阅 设置列表选项值。

添加

list / elements=string

要添加到现有集的加密类型。

除非由 remove 指定或不在 set 中，否则任何未由 add 指定的现有加密类型将保持不变。

选择

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

删除

list / elements=string

要从现有集中删除的加密类型。

除非定义了 set，否则任何未由 remove 指定的现有加密类型将保持不变。

选择

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

设置

list / elements=string

要设置为 AD 计算机允许的唯一加密类型的加密类型。

如果未在此列表中指定，这将删除任何现有的加密类型。

指定一个空列表以删除所有加密类型。

选择

  • "aes128"

  • "aes256"

  • "des"

  • "rc4"

location

string

设置计算机帐户的位置。

这是在 location LDAP 属性上设置的值。

managed_by

any

管理该对象的用户或组。

该值可以是 distinguishedName、objectGUID、objectSid、sAMAccountName 或 userPrincipalName 字符串的形式，也可以是带有 name 和可选 server 键的字典。

这是在 managedBy LDAP 属性上设置的值。

有关 DN 查找如何工作的更多信息，请参阅 DN 查找属性。

name

string

要管理的 AD 对象的 name，这不是对象的 sAMAccountName，而是指定路径中对象的 LDAP cn 或 name 条目。使用 identity 通过其 sAMAccountName 选择要管理的对象。

如果指定了 identity，并且该标识找到的对象的名称与此值不匹配，则将重命名该对象。

如果未设置 identity，则必须指定此项。

path

string

新对象应存在的 OU 或容器的路径。

如果创建新对象，则将在指定路径中创建新对象。如果未指定路径，则域的 defaultNamingContext 将用作大多数对象类型的路径。

如果管理由 identity 找到的现有对象，则找到的对象的路径将移动到此选项指定的路径。如果未指定路径，则不会移动该对象。

模块 microsoft.ad.computer、microsoft.ad.user 和 microsoft.ad.group 具有在其 Active Directory 域控制器上配置的自己的默认路径。

可以将其设置为文字值 microsoft.ad.default_path，该值将等于创建新对象时使用的默认值。

protect_from_deletion

boolean

将对象标记为受保护，防止意外删除。

这会应用拒绝访问权限，阻止正常删除对象。在通过 GUI 或 Ansible 之外的任何其他工具删除对象之前，需要移除保护。

即使 AD 对象被标记为受保护不能删除，使用 state=absent 仍然会删除该对象。

选择

  • false

  • true

sam_account_name

string

计算机帐户要设置的 sAMAccountName 值。

如果省略，创建新帐户时将使用 name 值。

它最多可以有 256 个字符，建议使用 15 个字符以兼容较旧的操作系统。

如果省略，当创建计算机时，该值与 name$ 相同。

请注意，所有计算机的 sAMAccountName 值通常都以 $ 结尾。

默认情况下，如果省略 $，它将被添加到末尾。如果 do_not_append_dollar_to_sam=True，则将使用提供的值，而不会在末尾添加 $。

spn

别名: spns

字典

指定要添加、删除或设置的帐户的服务主体名称 (SPN)。

这是在 servicePrincipalName LDAP 属性上设置的值。

要清除所有服务主体名称，请使用带有空列表的 set。

有关如何添加/删除/设置列表选项的更多信息，请参阅 设置列表选项值。

add

list / elements=string

要添加到 servicePrincipalName 的 SPN。

remove

list / elements=string

要从 servicePrincipalName 中删除的 SPN。

set

list / elements=string

要设置为 servicePrincipalName 中唯一值的 SPN。

如果未在指定列表中，这将清除任何现有的 SPN。

设置为一个空列表可以清除 AD 对象上的所有 SPN。

state

string

设置为 present 以确保 AD 对象存在。

设置为 absent 以删除存在的 AD 对象。

当 state=present 时，必须设置选项 name。

使用 absent 将递归删除 AD 对象及其任何子对象（如果它是一个容器）。即使该对象被标记为受保护不能意外删除，它也会删除该 AD 对象。

选择

  • "absent"

  • "present" ← (默认)

trusted_for_delegation

boolean

指定是否信任某个帐户进行 Kerberos 委派。

这也称为非约束 Kerberos 委派。

这将在 userAccountControl LDAP 属性中设置 ADS_UF_TRUSTED_FOR_DELEGATION 标志。

选择

  • false

  • true

upn

string

配置帐户的用户主体名称 (UPN)。

格式为 <username>@<domain>。

这是在 userPrincipalName LDAP 属性上设置的值。

属性

属性

支持

描述

check_mode

支持: 完全

可以在 check_mode 中运行，并返回更改状态预测，而无需修改目标。如果不支持，将跳过该操作。

diff_mode

支持: 完全

当处于 diff 模式时，将返回已更改（或可能需要在 check_mode 中更改）的详细信息

platform

平台: windows

可以操作的目标操作系统/系列

说明

注意

  • 有关从 community.windows.win_domain_computer 迁移到此模块的帮助，请参阅 win_domain_computer 迁移。

  • 此模块必须在安装了 ActiveDirectory 模块的 Windows 目标主机上运行。

  • 当使用 sAMAccountName 值通过 identity 进行匹配时，该值应以 $ 结尾。如果提供的值不以 $ 结尾，则模块仍将尝试使用提供的值查找计算机帐户，然后再尝试使用附加 $ 到末尾的后备查找。此后备行为是在此集合的 1.7.0 版本中添加的。

  • 某些 LDAP 属性只能设置一个值，而其他属性可以有多个值。某些属性也是只读的，无法更改。建议查看属性的架构元数据，其中 System-Only 是只读值，而 Is-Single-Value 是只有 1 个值的属性。

  • 尝试为 Is-Single-Value 属性设置多个值会导致未定义的行为。

  • 如果在不是域控制器的服务器上运行，则必须使用通过 CredSSP 或 Kerberos 的凭据委派，或必须设置 domain_username 和 domain_password。

另请参阅

另请参阅

microsoft.ad.domain

确保 Windows 域的存在。

microsoft.ad.domain_controller

管理 Windows 主机的域控制器/成员服务器状态。

microsoft.ad.membership

管理 Windows 主机的域/工作组隶属关系。

microsoft.ad.object_info

收集 Active Directory 对象的信息。

microsoft.ad.object

管理 Active Directory 对象。

microsoft.ad.offline_join

获取脱机域加入 BLOB。

microsoft.ad.group

管理 Active Directory 组对象。

迁移指南

此模块替换 community.windows.win_domain_computer。有关详细信息，请参阅迁移指南。

community.windows.win_domain_computer

管理 Active Directory 中的计算机。

示例

- name: Add linux computer to Active Directory OU using a windows machine
  microsoft.ad.computer:
    name: one_linux_server
    sam_account_name: linux_server$
    dns_hostname: one_linux_server.my_org.local
    path: OU=servers,DC=my_org,DC=local
    description: Example of linux server
    enabled: true
    state: present

- name: Remove linux computer from Active Directory using a windows machine
  microsoft.ad.computer:
    identity: one_linux_server$
    state: absent

- name: Add SPNs to computer
  microsoft.ad.computer:
    identity: TheComputer$
    spn:
      add:
        - HOST/TheComputer
        - HOST/TheComputer.domain.test
        - HOST/TheComputer.domain.test:1234

- name: Remove SPNs on the computer
  microsoft.ad.computer:
    identity: TheComputer$
    spn:
      remove:
        - HOST/TheComputer
        - HOST/TheComputer.domain.test
        - HOST/TheComputer.domain.test:1234

- name: Set the principals the computer trusts for delegation from
  microsoft.ad.computer:
    identity: TheComputer$
    delegates:
      set:
        - CN=FileShare,OU=Computers,DC=domain,DC=test
        - OtherServer$  # Lookup by sAMAaccountName

- name: Add computer with sAMAccountName without $ suffix
  microsoft.ad.computer:
    identity: TheComputer
    sam_account_name: TheComputer
    do_not_append_dollar_to_sam: true

返回值

常见的返回值已在此处记录： 此处，以下是此模块特有的字段

键

描述

distinguished_name

string

已创建、删除或编辑的 AD 对象的 distinguishedName。

返回: 始终

示例: "CN=MyComputer,CN=Computers,DC=domain,DC=test"

object_guid

string

已创建、删除或编辑的 AD 对象的 objectGUID。

如果在 check 模式下创建了一个新对象，则将返回 GUID 0。

返回: 始终

示例: "d84a141f-2b99-4f08-9da0-ed2d26864ba1"

sid

string

托管的帐户的安全标识符 (SID)。

如果在 check 模式下创建了一台新计算机，则 SID 将为 S-1-5-0000。

返回: 始终

示例: "S-1-5-21-4151808797-3430561092-2843464588-1104"

作者

  • Jordan Borean (@jborean93)