microsoft.ad.object 模块 – 管理 Active Directory 对象

注意

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

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

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

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

概要

• 管理 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、string 或 boolean 值。 字符串属性值使用区分大小写的匹配方式与被管理的 AD 对象进行比较。 有关更多信息，请参阅 LDAP 属性帮助。 默认值： {}
add 字典	所有属性及其值的字典，如果它们不存在，则添加到正在管理的 AD 对象中。 这用于可以包含多个值的属性，如果属性只允许单个值，则使用 *set* 代替。 默认值： {}
remove 字典	所有属性及其值的字典，如果它们存在，则从正在管理的 AD 对象中删除。 这用于可以包含多个值的属性，如果属性只允许单个值，则使用 *set* 代替。 默认值： {}
set 字典	所有属性及其值的字典，要在正在管理的 AD 对象上设置。 如果它们与请求的不匹配，这将替换任何现有值。 属性值的顺序不进行检查，只检查请求的值是否是对象属性上的唯一值。 将其设置为 null 或空列表可清除属性的任何值。 默认值： {}
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。
密码 字符串 / 必需	连接到由name 指定的服务器时要使用的密码。
用户名 字符串 / 必需	连接到由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 交互时要使用的用户名。 如果未设置此项，则用于身份验证的用户将是连接用户。 除非身份验证是具有凭据委派或 CredSSP 的 Kerberos，或者在任务中使用了 become，否则 Ansible 将无法使用连接用户。 没有name 键的domain_credentials 子条目也可以用于指定默认域身份验证的凭据。 这可以在 play 的模块默认值 下的 group/microsoft.ad.domain 组下设置。
标识 字符串	用于查找要管理的 AD 对象的 AD 对象的标识。 如果未设置name，尝试使用新的name 重命名对象，或尝试将对象移动到不同的path 时，必须指定此项。 标识可以是表示objectGUID 值的 GUID、userPrincipalName、sAMAccountName、objectSid 或 distinguishedName 的形式。 如果省略，则使用格式 CN={{ name }},{{ path }} 通过 distinguishedName 选择要管理的 AD 对象。如果未定义path，则使用 defaultNamingContext。 使用microsoft.ad.computer 模块时，如果提供的值未导致匹配且末尾没有$，则该模块会自动将$附加到sAMAccountName 的末尾。
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，它将等于创建新对象时使用的默认值。
protect_from_deletion 布尔值	将对象标记为受保护，防止意外删除。 这将应用拒绝访问权限，防止正常删除对象，并且需要在通过 GUI 或 Ansible 之外的任何其他工具删除对象之前删除此保护。 即使对象被标记为受保护以防止意外删除，使用state=absent 仍将删除 AD 对象。 选项 false true
state 字符串	设置为present 以确保 AD 对象存在。 设置为absent 以删除存在的 AD 对象。 当state=present 时，必须设置选项name。 使用absent 将递归删除 AD 对象及其任何子对象（如果它是容器）。即使对象被标记为受保护以防止意外删除，它也将删除 AD 对象。 选项 "absent" "present" ← (默认)
type 字符串	AD 对象的对象类型。 这对应于 AD 对象的objectClass。 type 的一些示例是 user、computer、group、subnet、contact、container。 当state=present 时，这是必需的。

属性

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

备注

注意

• 这是一个通用的模块，用于创建和管理 Active Directory 中的任何对象类型。创建时，它不会验证是否为每种类型设置了所有正确的默认值。如果可以使用特定于类型的模块来管理该 AD 对象类型，建议使用该模块。

• 此模块必须在安装了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.object_info

收集 Active Directory 对象的信息。

microsoft.ad.user

管理 Active Directory 用户。

microsoft.ad.computer

管理 Active Directory 计算机对象。

microsoft.ad.group

管理 Active Directory 组对象。

示例

# Use this to get all valid types in a domain environment
# (Get-ADObject -SearchBase (Get-ADRootDSE).subschemaSubentry -Filter * -Properties objectClasses).objectClasses |
#     Select-String -Pattern "Name\s+'(\w+)'" |
#     ForEach-Object { $_.Matches.Groups[1].Value } |
#     Sort-Object

- name: Create a contact object
  microsoft.ad.object:
    name: MyContact
    description: My Contact Description
    type: contact
    state: present

- name: Rename a contact object
  microsoft.ad.object:
    identity: '{{ contact_obj.object_guid }}'
    name: RenamedContact
    type: contact
    state: present

- name: Move a contact object
  microsoft.ad.object:
    identity: '{{ contact_object.object_guid }}'
    name: MyContact
    path: OU=Contacts,DC=domain,DC=test
    type: contact
    state: present

- name: Remove a contact object in default path
  microsoft.ad.object:
    name: MyContact
    state: absent

- name: Remove a contact object in custom path
  microsoft.ad.object:
    name: MyContact
    path: OU=Contacts,DC=domain,DC=test
    state: absent

- name: Remove a contact by identity
  microsoft.ad.object:
    identity: '{{ contact_obj.object_guid }}'
    state: absent

- name: Create container object with custom attributes
  microsoft.ad.object:
    name: App
    attributes:
      set:
        wWWHomePage: https://ansible.org.cn
    type: container
    state: present

- name: Clear attribute of any value
  microsoft.ad.object:
    name: App
    attributes:
      set:
        wWWHomePage: ~
    type: container
    state: present

- name: Edit object security with Everyone Allow All access
  microsoft.ad.object:
    name: App
    attributes:
      add:
        nTSecurityDescriptor:
          type: security_descriptor
          value: O:DAG:DAD:PAI(A;CI;CCDCLCSWRPWPDTLOCRSDRCWDWO;;;WD)
    type: container
    state: present

- name: Ensure multiple values are present in attribute
  microsoft.ad.object:
    name: App
    attributes:
      add:
        extensionName:
          - value 1
          - value 2
    type: container
    state: present

- name: Ensure multiple values are not present in attribute
  microsoft.ad.object:
    name: App
    attributes:
      remove:
        extensionName:
          - value 1
          - value 3
    type: container
    state: present

返回值

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

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

作者

• Jordan Borean (@jborean93)

收藏链接

• 问题追踪器
• 代码库（源码）
• 报告问题
• 通信