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` 类型的值是要设置的 DateTime 的 ISO 8601 DateTime 字符串。DateTime 将设置为 Microsoft FILETIME 整数值，该值是自 1601-01-01 UTC 以来 100 纳秒的计数。 `security_descriptor` 类型的值是用于 `nTSecurityDescriptor` 属性的安全描述符 SDDL 字符串。 `raw` 类型是要设置的 int、字符串或布尔值。字符串属性值在被管理的 AD 对象上使用区分大小写的匹配进行比较。有关详细信息，请参阅 LDAP 属性帮助。默认值： `{}`
add 字典	一个字典，其中包含所有属性及其值，如果 AD 对象中尚未存在这些属性，则添加到 AD 对象中。这用于可以包含多个值的属性，如果该属性只允许单个值，请改用 set。默认值： `{}`
remove 字典	一个字典，其中包含所有属性及其值，如果 AD 对象中存在这些属性，则从 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。
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` 的末尾追加 `$`。
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 boolean	将对象标记为防止意外删除。这会应用一个拒绝访问权限，使其无法正常删除该对象，并且需要在通过 GUI 或 Ansible 之外的任何其他工具删除该对象之前删除保护。即使 AD 对象被标记为防止删除，使用 state=absent 仍然会删除该对象。 Choices `false` `true`
state 字符串	设置为 `present` 以确保 AD 对象存在。设置为 `absent` 以在 AD 对象存在时将其删除。当 state=present 时，必须设置选项 name。如果使用 `absent`，它将递归删除 AD 对象及其任何子对象（如果它是容器）。即使该对象被标记为防止意外删除，它也会删除 AD 对象。 Choices `"absent"` `"present"` ← (默认)
type 字符串	AD 对象的对象类型。这对应于 AD 对象的 `objectClass`。类型的一些示例是 `user`、`computer`、`group`、`subnet`、`contact`、`container`。当 state=present 时，这是必需的。

属性 

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

说明 

注意

这是一个通用模块，用于在 Active Directory 中创建和管理任何对象类型。它不会验证创建时是否为每种类型设置了所有正确的默认值。如果有可用于管理该 AD 对象类型的特定于类型的模块，建议使用该模块。
此模块必须在安装了 ActiveDirectory 模块的 Windows 目标主机上运行。
一些 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.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

返回值 

通用返回值记录在此处，以下是此模块独有的字段

Key	描述
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)

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

作者

收集链接