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选项。 这可以在剧本的模块默认值下的 有关更多信息，请参见模块中的AD身份验证。 默认值： |
|
这些凭据所属的服务器名称。 此值应与在指定要使用的自定义服务器的其他选项中使用的值相对应，例如引用位于不同AD服务器上的AD标识的选项。 此键可以在一个条目中省略，以指定在未指定服务器时要使用的默认凭据，而不是使用domain_username和domain_password。 |
|
连接到由name指定的服务器时使用的密码。 |
|
连接到由name指定的服务器时使用的用户名。 |
|
domain_username的密码。 没有name键的domain_credentials子条目也可以用来指定默认域身份验证的凭据。 这可以在剧本的模块默认值下的 |
|
指定要连接到的Active Directory域服务实例。 可以是完全限定域名 (FQDN) 或 NetBIOS 名称。 如果未指定，则该值基于运行PowerShell的计算机的默认域。 可以在没有name键的domain_credentials条目下或通过domain_username和domain_password指定自定义凭据。 这可以在剧本的模块默认值下的 |
|
与AD交互时使用的用户名。 如果未设置此项，则用于身份验证的用户将是连接用户。 除非身份验证是带有凭据委派或CredSSP的Kerberos，或者在任务上使用了become，否则Ansible将无法使用连接用户。 没有name键的domain_credentials子条目也可以用来指定默认域身份验证的凭据。 这可以在剧本的模块默认值下的 |
|
组的主页。 这是 |
|
用于查找要管理的AD对象的AD对象的标识。 如果未设置name，尝试使用新的name重命名对象，或尝试将对象移动到不同的path中，则必须指定此项。 标识可以是表示 如果省略，则要管理的AD对象将通过使用格式 使用microsoft.ad.computer模块时，如果提供的值未产生匹配且末尾没有 |
|
管理组的用户或组。 该值可以是 这是 有关DN查找的工作方式的更多信息，请参见DN查找属性。 |
|
要设置的组成员。 该值是一个包含3个键的字典：add、remove和set。 每个子键值都是一个列表，其值采用 每个子键的值可以指定为字符串，也可以指定为包含name和可选server键的字典。name是要查找的标识，server是可选键，用于覆盖在哪个AD服务器上查找标识。 有关更多信息，请参见DN查找属性。 |
|
将指定的成员添加到组中，如果未指定，则保留现有成员。 |
|
控制查找失败时要采取的操作。
选项
|
|
将指定的成员从组中移除，如果未指定，则保留现有成员。 |
|
仅将指定的成员设置为组成员。 如果在此列表中未指定，则任何其他现有成员都将从组成员中移除。 将其设置为空列表可从组中移除所有成员。 |
|
要管理的AD对象的 如果指定了identity，并且通过该标识找到的对象的名称与该值不匹配，则将重命名该对象。 如果未设置identity，则必须指定此项。 |
|
新对象应存在于其中的OU或容器的路径。 如果创建新对象，则将在指定的路径中创建新对象。如果没有指定路径，则对于大多数对象类型，将使用域的 如果通过identity管理现有对象，则找到对象的路径将移动到此选项指定的路径。如果未指定路径，则不会移动对象。 microsoft.ad.computer、microsoft.ad.user和microsoft.ad.group模块在Active Directory域控制器上配置了自己的默认路径。 这可以设置为字面值 |
|
将对象标记为受保护，防止意外删除。 这将应用禁止从正常删除对象的访问权限，并且需要删除保护才能通过GUI或Ansible之外的任何其他工具删除该对象。 使用state=absent仍然会删除AD对象，即使它被标记为受保护，防止意外删除。 选项
|
|
要为组设置的 如果省略，则在创建新组时使用name值。 |
|
组的范围。 当state=present且组尚不存在时，这是必需的。 有关各种域组范围的更多信息，请参见组范围。 这是在 选项
|
|
设置为 设置为 当state=present时，必须设置选项name。 使用 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持：完全支持 |
可以在check_mode下运行并返回更改状态预测，而无需修改目标；如果不支持，则操作将被跳过。 |
|
支持：完全支持 |
在diff模式下，将返回有关已更改内容（或可能需要在check_mode下更改的内容）的详细信息。 |
|
平台： Windows |
可以对其进行操作的目标操作系统/系列。 |
备注
注意
有关从win_group迁移到此模块的帮助，请参见community.windows.win_domain_group。
此模块必须在安装了
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.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对象的 如果在check模式下创建了新对象，则将返回一个全为0的GUID。 返回值：始终返回 示例： |
|
被管理的组的安全标识符 (SID)。 如果在check模式下创建了新组，则SID将为 返回值：始终返回 示例： |