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

注意

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

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

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

要在 playbook 中使用它,请指定:microsoft.ad.group

概要

  • 管理 Active Directory 组对象及其属性。

要求

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

  • ActiveDirectory PowerShell 模块

参数

参数

注释

attributes

字典

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

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

属性值可以是原始字符串、整数或布尔值,以便在有问题的属性上添加、删除或设置。

该值也可以是一个字典,其中 type 键设置为 bytesdate_timesecurity_descriptorraw,并且此条目的值位于 value 键下。

bytes 类型的值是一个要设置的原始字节的 base64 编码字符串。

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

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

raw 类型是要设置的 int、string 或布尔值。

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

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

默认: {}

add

字典

如果要管理的 AD 对象中尚不存在,则要添加到该对象的所有属性及其值的字典。

这用于可以包含多个值的属性,如果该属性只允许一个值,请改用 set

默认: {}

remove

字典

如果要管理的 AD 对象中存在,则要从该对象中删除的所有属性及其值的字典。

这用于可以包含多个值的属性,如果该属性只允许一个值,请改用 set

默认: {}

set

字典

要管理的 AD 对象上设置的所有属性及其值的字典。

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

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

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

默认: {}

category

字符串

组的类别。

如果创建新组,则默认情况下将使用 security

security 组可以与访问控制列表关联,而 distribution 组通常与邮件分发列表关联。

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

选择

  • "distribution"

  • "security"

description

字符串

要设置的 AD 对象的描述。

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

display_name

字符串

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

这是 displayName LDAP 属性的值。

domain_credentials

列表 / elements=dictionary

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

要为默认域服务器指定凭据,请使用不带 name 键的条目,或使用 domain_usernamedomain_password 选项。

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

更多信息请参考模块中的 AD 身份验证

默认值: []

name

字符串

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

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

可以省略一个条目中的此键,以指定在未指定服务器时要使用的默认凭据,而不是使用 domain_usernamedomain_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_usernamedomain_password 指定自定义凭据。

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

domain_username

字符串

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

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

除非使用 Kerberos 进行身份验证并进行凭据委派或 CredSSP,或者在任务中使用 become,否则 Ansible 将无法使用连接用户。

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

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

homepage

字符串

组的主页。

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

identity

字符串

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

如果未设置 name、尝试使用新 name 重命名对象,或尝试将对象移动到其他 path 中,则必须指定此项。

标识可以是表示 objectGUID 值的 GUID、userPrincipalNamesAMAccountNameobjectSiddistinguishedName 的形式。

如果省略,则通过使用 CN={{ name }},{{ path }} 格式的 distinguishedName 来选择要管理的 AD 对象。 如果未定义 path,则使用 defaultNamingContext

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

managed_by

任意

管理组的用户或组。

该值可以是 distinguishedNameobjectGUIDobjectSidsAMAccountNameuserPrincipalName 字符串,或包含 name 和可选的 server 键的字典。

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

有关 DN 查找的工作原理的更多信息,请参阅DN 查找属性

members

字典

要设置的组的成员。

该值是一个包含 3 个键的字典:addremoveset

每个子键值都是一个列表,列表中的值可以是 distinguishedNameobjectGUIDobjectSidsAMAccountNameuserPrincipalName 字符串,也可以是包含 name 和可选的 server 键的字典。

每个子键的值可以指定为字符串或包含 name 和可选的 server 键的字典。 name 是要查找的标识,而 server 是一个可选键,用于覆盖在哪个 AD 服务器上查找标识。

有关更多信息,请参阅 DN 查找属性

add

列表 / 元素=任意

将指定的主体添加为组的成员,如果未指定,则保留现有成员资格。

lookup_failure_action

字符串

控制在查找失败时要执行的操作,无法找到 DN。

fail 将导致任务失败。

ignore 将忽略该值并继续。

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

选择

  • "fail" ←(默认)

  • "ignore"

  • "warn"

remove

列表 / 元素=任意

删除指定为组成员的主体,如果未指定,则保留现有成员资格。

set

列表 / 元素=任意

仅设置指定为组成员的主体。

如果未在此列表中指定任何其他现有成员,则将从组成员资格中删除它们。

将此项设置为空列表以从组中删除所有成员。

name

字符串

要管理的 AD 对象的 name,这不是对象的 sAMAccountName,而是指定路径中对象的 LDAP cnname 条目。 使用 identitysAMAccountName 选择要管理的对象。

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

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

path

字符串

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

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

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

模块 microsoft.ad.computermicrosoft.ad.usermicrosoft.ad.group 都有它们自己在 Active Directory 域控制器上配置的默认路径。

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

protect_from_deletion

布尔值

将对象标记为防止意外删除。

这会应用拒绝删除对象的访问权限,并且在可以通过 GUI 或 Ansible 之外的任何其他工具删除对象之前,需要删除此保护。

即使 AD 对象被标记为防止删除,使用 state=absent 仍然会删除该 AD 对象。

选择

  • false

  • true

sam_account_name

字符串

要为组设置的 sAMAccountName 值。

如果省略,则在创建新组时使用 name 值。

scope

字符串

组的范围。

state=present 且组尚不存在时,这是必需的。

有关各种域组范围的更多信息,请参阅 组范围

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

选择

  • "domainlocal"

  • "global"

  • "universal"

state

字符串

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

设置为 absent 以删除 AD 对象(如果存在)。

state=present 时,必须设置选项 name

使用 absent 将递归删除 AD 对象以及任何子对象(如果它是容器)。 即使对象被标记为防止意外删除,它也会删除 AD 对象。

选择

  • "absent"

  • "present" ←(默认)

属性

属性

支持

描述

check_mode

支持:完全

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

diff_mode

支持:完全

在 diff 模式下,将返回有关已更改(或可能需要在 check_mode 中更改)的详细信息

platform

平台: windows

可以操作的目标 OS/系列

注释

注意

  • 有关从 community.windows.win_domain_group 迁移到此模块的帮助,请参阅win_group 迁移

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

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

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

  • 如果在不是域控制器的服务器上运行,则必须使用通过 CredSSP 或具有委派的 Kerberos 进行凭据委派,或者必须设置 domain_usernamedomain_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.user

管理 Active Directory 用户。

迁移指南

此模块替代了 community.windows.win_domain_group。有关详细信息,请参阅迁移指南。

community.windows.win_domain_group

创建、修改或删除域组。

示例

- name: Ensure a group exists
  microsoft.ad.group:
    identity: Cow
    scope: global

- name: Remove a group
  microsoft.ad.group:
    identity: Cow
    state: absent

- name: Create a group in a custom path
  microsoft.ad.group:
    name: Cow
    scope: global
    path: OU=groups,DC=ansible,DC=local
    state: present

- name: Remove a group in a custom path
  microsoft.ad.group:
    name: Cow
    path: OU=groups,DC=ansible,DC=local
    state: absent

- name: Create group with delete protection enabled and custom attributes
  microsoft.ad.group:
    name: Ansible Users
    scope: domainlocal
    category: security
    homepage: www.ansible.com
    attributes:
      set:
        mail: [email protected]
    protect_from_deletion: true

- name: Change the path of a group
  microsoft.ad.group:
    name: MyGroup
    scope: global
    identity: S-1-5-21-2171456218-3732823212-122182344-1189
    path: OU=groups,DC=ansible,DC=local

- name: Add managed_by user
  microsoft.ad.group:
    name: Group Name Here
    scope: global
    managed_by: Domain Admins

- name: Add group and specify the AD domain services to use for the create
  microsoft.ad.group:
    name: Test Group
    domain_username: [email protected]
    domain_password: Password01!
    domain_server: corp-DC12.corp.ansible.com
    scope: domainlocal

- name: Add members to the group, preserving existing membership
  microsoft.ad.group:
    name: Test Group
    scope: domainlocal
    members:
      add:
        - Domain Admins
        - Domain Users

- name: Remove members from the group, preserving existing membership
  microsoft.ad.group:
    name: Test Group
    scope: domainlocal
    members:
      remove:
        - Domain Admins
        - Domain Users

- name: Replace entire membership of group
  microsoft.ad.group:
    name: Test Group
    scope: domainlocal
    members:
      set:
        - Domain Admins
        - Domain Users
        - name: UserInOtherDomain
          server: OtherDomain
    domain_credentials:
      - name: OtherDomain
        username: OtherDomainUser
        password: '{{ other_domain_password }}'

返回值

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

描述

distinguished_name

字符串

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

返回: 总是

示例: "CN=MyGroup,CN=Users,,DC=domain,DC=test"

object_guid

字符串

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

如果在检查模式下创建了一个新对象,将返回一个全为 0 的 GUID。

返回: 总是

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

sid

字符串

所管理组的安全标识符 (SID)。

如果在检查模式下创建了一个新组,SID 将为 S-1-5-0000

返回: 总是

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

作者

  • Jordan Borean (@jborean93)