microsoft.ad.ou 模块 – 管理 Active Directory 组织单元

注意

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

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

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

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

概要

• 管理 Active Directory 组织单元及其属性。

要求

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

• ActiveDirectory PowerShell 模块

参数

参数	注释
attributes 字典	要在 AD 对象上添加、删除或设置的属性。 每个属性选项的值应为一个字典，其中键是 LDAP 属性，例如 firstName、comment，值是要为该属性设置的值或值列表。 属性值可以是原始字符串、整数或布尔值，以在所讨论的属性上添加、删除或设置。 该值也可以是一个字典，其中 type 键设置为 bytes、date_time、security_descriptor 或 raw，此条目的值在 value 键下。 bytes 类型的值是原始字节的 base64 编码字符串。 date_time 类型的值是 ISO 8601 DateTime 字符串，用于设置 DateTime。DateTime 将设置为 Microsoft FILETIME 整数值，该值是自 1601-01-01 UTC 以来 100 纳秒的数量。 security_descriptor 类型的值是用于 nTSecurityDescriptor 属性的安全描述符 SDDL 字符串。 raw 类型是要设置的 int、字符串或布尔值。 字符串属性值使用区分大小写的匹配来比较被管理的 AD 对象。 有关详细信息，请参阅 LDAP 属性帮助。 默认： {}
add 字典	所有属性及其值的字典，如果它们尚不存在，则添加到正在管理的 AD 对象。 这用于可以包含多个值的属性，如果属性仅允许单个值，请改用 set。 默认： {}
remove 字典	所有属性及其值的字典，如果它们存在，则从正在管理的 AD 对象中删除。 这用于可以包含多个值的属性，如果属性仅允许单个值，请改用 set。 默认： {}
set 字典	要在正在管理的 AD 对象上设置的所有属性及其值的字典。 如果任何现有值与请求的值不匹配，这将替换它们。 不检查属性值的顺序，仅检查请求的值是否是对象属性上的唯一值。 将此项设置为 null 或空列表以清除属性的任何值。 默认： {}
city 字符串	配置用户的城市。 这是在 l LDAP 属性上设置的值。
country 字符串	配置用户的国家/地区代码。 请注意，这是一个两位数的 ISO 3166 代码。 这是在 c LDAP 属性上设置的值。
description 字符串	要设置的 AD 对象的描述。 这是在 description LDAP 属性上设置的值。
display_name 字符串	要设置的 AD 对象的显示名称。 这是 displayName LDAP 属性的值。
domain_credentials 列表 / 元素=字典	指定在使用 name 指定的服务器时应使用的凭据。 要为默认域服务器指定凭据，请使用不带 name 键的条目，或使用 domain_username 和 domain_password 选项。 可以在 play 的模块默认值下的 group/microsoft.ad.domain 组下设置此项。 有关详细信息，请参阅 模块中的 AD 身份验证。 默认： []
name 字符串	这些凭据适用的服务器的名称。 此值应与在指定要使用的自定义服务器的其他选项中使用的值相对应，例如引用位于不同 AD 服务器上的 AD 身份的选项。 可以在一个条目中省略此键，以指定在未指定服务器时要使用的默认凭据，而不是使用 domain_username 和 domain_password。
password 字符串 / 必需	连接到 name 指定的服务器时要使用的密码。
username 字符串 / 必需	连接到 name 指定的服务器时要使用的用户名。
domain_password 字符串	domain_username 的密码。 不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。 可以在 play 的模块默认值下的 group/microsoft.ad.domain 组下设置此项。
domain_server 字符串	指定要连接的 Active Directory 域服务实例。 可以是 FQDN 或 NetBIOS 名称的形式。 如果未指定，则该值基于运行 PowerShell 的计算机的默认域。 自定义凭据可以在没有 name 键的 domain_credentials 条目下指定，也可以通过 domain_username 和 domain_password 指定。 可以在 play 的模块默认值下的 group/microsoft.ad.domain 组下设置此项。
domain_username 字符串	与 AD 交互时使用的用户名。 如果未设置此项，则用于身份验证的用户将是连接用户。 除非使用 Kerberos 凭据委派或 CredSSP 进行身份验证，或者在任务中使用 become，否则 Ansible 将无法使用连接用户。 不带 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。 可以在 play 的模块默认值下的 group/microsoft.ad.domain 组下设置此项。
identity 字符串	用于查找要管理的 AD 对象的 AD 对象的标识。 如果未设置 name，尝试使用新的 name 重命名对象，或尝试将对象移动到不同的 path 中，则必须指定此项。 标识的形式可以是代表 objectGUID 值的 GUID、userPrincipalName、sAMAccountName、objectSid 或 distinguishedName。 如果省略，则要管理的 AD 对象将使用 distinguishedName 以 CN={{ name }},{{ path }} 的格式选择。如果未定义 path，则会改用 defaultNamingContext。 当使用 microsoft.ad.computer 模块时，如果提供的值未匹配，且末尾没有 $，则标识会自动将 $ 附加到 sAMAccountName 的末尾。
managed_by any	管理该对象的用户或组。 该值可以是 distinguishedName、objectGUID、objectSid、sAMAccountName 或 userPrincipalName 字符串，也可以是带有 name 和可选的 server 键的字典。 这是在 managedBy LDAP 属性上设置的值。 有关 DN 查找的工作原理的更多信息，请参阅 DN 查找属性。
name 字符串	要管理的 AD 对象的 name，这不是该对象的 sAMAccountName，而是指定路径中对象的 LDAP cn 或 name 条目。使用 identity 通过其 sAMAccountName 选择要管理的对象。 如果指定了 identity，并且该标识找到的对象的名称与此值不匹配，则该对象将被重命名。 如果未设置 identity，则必须指定此项。
path 字符串	新对象应存在的 OU 或容器的路径。 如果要创建新对象，则新对象将创建在指定的路径中。如果未指定路径，则域的 defaultNamingContext 将用作大多数对象类型的路径。 如果要管理由 identity 找到的现有对象，则找到的对象的路径将移动到此选项指定的路径。如果未指定路径，则不会移动该对象。 模块 microsoft.ad.computer、microsoft.ad.user 和 microsoft.ad.group 都有其自己在 Active Directory 域控制器上配置的默认路径。 可以将其设置为字面值 microsoft.ad.default_path，它将等于创建新对象时使用的默认值。
postal_code 字符串	配置用户的邮政编码/邮政编码。 这是在 postalcode LDAP 属性上设置的值。
protect_from_deletion boolean	将对象标记为防止意外删除。 这会应用一个拒绝删除该对象的访问权限，并且在通过 GUI 或 Ansible 之外的任何其他工具删除对象之前，需要删除此保护。 即使 AD 对象被标记为防止删除，使用 state=absent 仍会删除该对象。 Choices false true
state 字符串	设置为 present 以确保 AD 对象存在。 设置为 absent 以删除存在的 AD 对象。 当 state=present 时，必须设置选项 name。 如果 AD 对象是容器，使用 absent 将递归删除该 AD 对象及其任何子对象。即使该对象被标记为防止意外删除，它也会删除该 AD 对象。 Choices "absent" "present" ← (默认)
state_province 字符串	配置用户的省份。 这是在 state LDAP 属性上设置的值。
street 字符串	配置用户的街道地址。 这是在 street LDAP 属性上设置的值。

属性

属性	支持	描述
check_mode	支持: 完全	可以在 check_mode 中运行，并返回已更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。
diff_mode	支持: 完全	当处于 diff 模式时，将返回有关已更改的内容（或在 check_mode 中可能需要更改的内容）的详细信息
platform	平台: windows	可以对其进行操作的目标操作系统/系列

注释

注意

• 创建 OU 时，如果未指定，则 protect_from_deletion 默认为 True。

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

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

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

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

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

另请参阅

另请参阅

microsoft.ad.domain

确保 Windows 域的存在。

microsoft.ad.domain_controller

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

microsoft.ad.group

管理 Active Directory 组对象。

microsoft.ad.object_info

收集 Active Directory 对象的信息。

microsoft.ad.user

管理 Active Directory 用户。

microsoft.ad.computer

管理 Active Directory 计算机对象。

迁移指南

此模块取代了 community.windows.win_domain_ou。有关详细信息，请参阅迁移指南。

community.windows.win_domain_ou

管理 Active Directory 组织单元。

示例

- name: Ensure OU is present & protected
  microsoft.ad.ou:
    name: AnsibleFest
    state: present

- name: Ensure OU is present & protected
  microsoft.ad.ou:
    name: EUC Users
    path: DC=euc,DC=vmware,DC=lan
    state: present
    protect_from_deletion: true

- name: Ensure OU is absent
  microsoft.ad.ou:
    name: EUC Users
    path: DC=euc,DC=vmware,DC=lan
    state: absent

- name: Ensure OU is present with specific properties
  microsoft.ad.ou:
    name: WS1Users
    path: CN=EUC Users,DC=euc,DC=vmware,DC=lan
    protect_from_deletion: true
    description: EUC Business Unit
    city: Sandy Springs
    country: US
    state_province: Georgia
    street: 1155 Perimeter Center West
    postal_code: 30189

- name: Ensure OU updated with new properties
  microsoft.ad.ou:
    name: WS1Users
    path: DC=euc,DC=vmware,DC=lan
    protected: false
    managed_by: [email protected]
    attributes:
      set:
        comment: A comment for the OU

- name: Set managedBy using an identity from another DC
  microsoft.ad.ou:
    name: MyOU
    managed_by:
      name: manager-user
      server: OtherDC

返回值

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

键	描述
distinguished_name 字符串	已创建、删除或编辑的 AD 对象的 distinguishedName。 已返回: 总是 示例: "CN=TestUser,CN=Users,DC=domain,DC=test"
object_guid 字符串	已创建、删除或编辑的 AD 对象的 objectGUID。 如果在检查模式下创建了新对象，将返回一个全 0 的 GUID。 已返回: 总是 示例: "d84a141f-2b99-4f08-9da0-ed2d26864ba1"

作者

• Jordan Borean (@jborean93)

集合链接

• 问题跟踪器
• 仓库 (源代码)
• 报告问题
• 通信