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 类型的值是 DateTime 的 ISO 8601 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选项。 这可以在剧本的模块默认值下的group/microsoft.ad.domain组中设置。 有关更多信息，请参见模块中的AD身份验证。 默认值： []
name 字符串	这些凭据所针对的服务器名称。 此值应与用于指定要使用的自定义服务器的其他选项中使用的值相对应，例如引用位于不同AD服务器上的AD身份的选项。 此键可以在一个条目中省略，以便在未指定服务器时指定要使用的默认凭据，而不是使用domain_username和domain_password。
password 字符串 / 必需	连接到由name指定的服务器时要使用的密码。
username 字符串 / 必需	连接到由name指定的服务器时要使用的用户名。
domain_password 字符串	domain_username的密码。 没有name键的domain_credentials子条目也可用于指定默认域身份验证的凭据。 这可以在剧本的模块默认值下的group/microsoft.ad.domain组中设置。
domain_server 字符串	指定要连接到的Active Directory域服务实例。 可以是FQDN或NetBIOS名称的形式。 如果未指定，则该值基于运行PowerShell的计算机的默认域。 自定义凭据可以在没有name键的domain_credentials条目下指定，或者通过domain_username和domain_password指定。 这可以在剧本的模块默认值下的group/microsoft.ad.domain组中设置。
domain_username 字符串	与AD交互时要使用的用户名。 如果未设置此项，则用于身份验证的用户将是连接用户。 除非身份验证是带有凭据委派或CredSSP的Kerberos，或者在任务中使用了become，否则Ansible将无法使用连接用户。 没有name键的domain_credentials子条目也可用于指定默认域身份验证的凭据。 这可以在剧本的模块默认值下的group/microsoft.ad.domain组中设置。
identity 字符串	用于查找要管理的AD对象的AD对象的标识。 如果未设置name，尝试使用新的name重命名对象，或尝试将对象移动到不同的path中，则必须指定此项。 标识可以是表示objectGUID值、userPrincipalName、sAMAccountName、objectSid或distinguishedName的GUID的形式。 如果省略，则使用格式CN={{ name }},{{ path }}通过distinguishedName选择要管理的AD对象。如果未定义path，则使用defaultNamingContext。 使用microsoft.ad.computer模块时，如果提供的 value 未产生匹配且末尾没有$，则标识将自动在sAMAccountName的末尾附加$。
managed_by 任何	管理对象的用户名或组名。 该值可以是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 布尔值	将对象标记为受保护，防止意外删除。 这将应用拒绝访问权限，阻止正常删除对象，并且需要先删除保护才能通过GUI或Ansible以外的任何其他工具删除对象。 使用state=absent仍然会删除AD对象，即使它被标记为受保护，防止意外删除。 选项 false true
state 字符串	设置为present以确保AD对象存在。 设置为absent以删除AD对象（如果存在）。 当state=present时，必须设置选项name。 使用absent将递归删除AD对象及其任何子对象（如果它是容器）。即使对象被标记为受保护，防止意外删除，它也会删除AD对象。 选项 "absent" "present" ← (默认值)
state_province 字符串	配置用户的州/省份。 这是在state LDAP属性上设置的值。
street 字符串	配置用户的街道地址。 这是在street LDAP属性上设置的值。

属性

属性	支持	描述
check_mode	支持：完全支持	可以在check_mode下运行并返回更改状态预测，而无需修改目标，如果不支持，则操作将被跳过。
diff_mode	支持：完全支持	在差异模式下，将返回有关更改内容（或在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)

资源链接

• 问题追踪器
• 代码仓库
• 报告问题
• 通信