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 组对象及其属性。
要求
在执行此模块的主机上需要以下要求。
ActiveDirectoryPowerShell 模块
参数
参数 |
注释 |
|---|---|
要在 AD 对象上添加、删除或设置的属性。 每个属性选项的值都应该是一个字典，其中键是 LDAP 属性，例如 属性值可以是原始字符串、整数或布尔值，以便在有问题的属性上添加、删除或设置。 该值也可以是一个字典，其中 type 键设置为
字符串属性值使用对正在管理的 AD 对象进行区分大小写的匹配来比较。 有关详细信息，请参阅 LDAP 属性帮助。 默认： |
|
如果要管理的 AD 对象中尚不存在，则要添加到该对象的所有属性及其值的字典。 这用于可以包含多个值的属性，如果该属性只允许一个值，请改用 set。 默认： |
|
如果要管理的 AD 对象中存在，则要从该对象中删除的所有属性及其值的字典。 这用于可以包含多个值的属性，如果该属性只允许一个值，请改用 set。 默认： |
|
要管理的 AD 对象上设置的所有属性及其值的字典。 如果现有值与请求的值不匹配，则这将替换任何现有值。 仅检查属性值的顺序，仅检查请求的值是否是对象属性上的唯一值。 将此设置为 null 或空列表以清除该属性的任何值。 默认： |
|
组的类别。 如果创建新组，则默认情况下将使用
这是在 选择
|
|
要设置的 AD 对象的描述。 这是在 |
|
要设置的 AD 对象的显示名称。 这是 |
|
指定在使用 name 指定的服务器时应使用的凭据。 要为默认域服务器指定凭据，请使用不带 name 键的条目，或使用 domain_username 和 domain_password 选项。 这可以在 play 的模块默认值 中的 更多信息请参考模块中的 AD 身份验证。 默认值： |
|
此凭据所针对的服务器的名称。 此值应与指定要使用的自定义服务器的其他选项中使用的值相对应，例如引用位于不同 AD 服务器上的 AD 身份的选项。 可以省略一个条目中的此键，以指定在未指定服务器时要使用的默认凭据，而不是使用 domain_username 和 domain_password。 |
|
连接到由 name 指定的服务器时要使用的密码。 |
|
连接到由 name 指定的服务器时要使用的用户名。 |
|
domain_username 的密码。 没有 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。 这可以在 play 的模块默认值 中的 |
|
指定要连接的 Active Directory 域服务实例。 可以是 FQDN 或 NetBIOS 名称的形式。 如果未指定，则该值基于运行 PowerShell 的计算机的默认域。 可以在没有 name 键的 domain_credentials 条目下或通过 domain_username 和 domain_password 指定自定义凭据。 这可以在 play 的模块默认值 中的 |
|
与 AD 交互时要使用的用户名。 如果未设置此项，则用于身份验证的用户将是连接用户。 除非使用 Kerberos 进行身份验证并进行凭据委派或 CredSSP，或者在任务中使用 become，否则 Ansible 将无法使用连接用户。 没有 name 键的 domain_credentials 子条目也可用于指定默认域身份验证的凭据。 这可以在 play 的模块默认值 中的 |
|
组的主页。 这是在 |
|
用于查找要管理的 AD 对象的 AD 对象的标识。 如果未设置 name、尝试使用新 name 重命名对象，或尝试将对象移动到其他 path 中，则必须指定此项。 标识可以是表示 如果省略，则通过使用 当使用 microsoft.ad.computer 模块时，如果提供的值未导致匹配并且末尾没有 |
|
管理组的用户或组。 该值可以是 这是在 有关 DN 查找的工作原理的更多信息，请参阅DN 查找属性。 |
|
要设置的组的成员。 该值是一个包含 3 个键的字典：add、remove 和 set。 每个子键值都是一个列表，列表中的值可以是 每个子键的值可以指定为字符串或包含 name 和可选的 server 键的字典。 name 是要查找的标识，而 server 是一个可选键，用于覆盖在哪个 AD 服务器上查找标识。 有关更多信息，请参阅 DN 查找属性。 |
|
将指定的主体添加为组的成员，如果未指定，则保留现有成员资格。 |
|
控制在查找失败时要执行的操作，无法找到 DN。
选择
|
|
删除指定为组成员的主体，如果未指定，则保留现有成员资格。 |
|
仅设置指定为组成员的主体。 如果未在此列表中指定任何其他现有成员，则将从组成员资格中删除它们。 将此项设置为空列表以从组中删除所有成员。 |
|
要管理的 AD 对象的 如果指定了 identity，并且该标识找到的对象的名称与此值不匹配，则将重命名该对象。 如果未设置 identity，则必须指定此项。 |
|
新对象应存在的 OU 或容器的路径。 如果创建新对象，则将在指定的路径中创建新对象。 如果未指定路径，则将使用域的 如果管理由 identity 找到的现有对象，则找到的对象的路径将移动到此选项指定的路径。 如果未指定路径，则不会移动对象。 模块 microsoft.ad.computer、microsoft.ad.user 和 microsoft.ad.group 都有它们自己在 Active Directory 域控制器上配置的默认路径。 可以将其设置为字面值 |
|
将对象标记为防止意外删除。 这会应用拒绝删除对象的访问权限，并且在可以通过 GUI 或 Ansible 之外的任何其他工具删除对象之前，需要删除此保护。 即使 AD 对象被标记为防止删除，使用 state=absent 仍然会删除该 AD 对象。 选择
|
|
要为组设置的 如果省略，则在创建新组时使用 name 值。 |
|
组的范围。 当 state=present 且组尚不存在时，这是必需的。 有关各种域组范围的更多信息，请参阅 组范围。 这是在 选择
|
|
设置为 设置为 当 state=present 时，必须设置选项 name。 使用 选择
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持：完全 |
可以在 check_mode 中运行并返回已更改状态预测，而无需修改目标，如果不支持，则会跳过该操作。 |
|
支持：完全 |
在 diff 模式下，将返回有关已更改（或可能需要在 check_mode 中更改）的详细信息 |
|
平台： windows |
可以操作的目标 OS/系列 |
注释
注意
有关从 community.windows.win_domain_group 迁移到此模块的帮助，请参阅win_group 迁移。
必须在安装了
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.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 }}'
返回值
常见的返回值记录在此处 此处，以下是此模块特有的字段
键 |
描述 |
|---|---|
已创建、删除或编辑的 AD 对象的 返回: 总是 示例: |
|
已创建、删除或编辑的 AD 对象的 如果在检查模式下创建了一个新对象，将返回一个全为 0 的 GUID。 返回: 总是 示例: |
|
所管理组的安全标识符 (SID)。 如果在检查模式下创建了一个新组，SID 将为 返回: 总是 示例: |