You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.windows.win_domain_group module – Creates, modifies or removes domain groups

Note

This module is part of the community.windows collection (version 1.10.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_domain_group.

Synopsis
Parameters
Notes
See Also
Examples
Return Values

Synopsis 

Creates, modifies or removes groups in Active Directory.
For local groups, use the ansible.windows.win_group module instead.

Parameters 

Parameter	Comments
attributes dictionary	A dict of custom LDAP attributes to set on the group. This can be used to set custom attributes that are not exposed as module parameters, e.g. `mail`. See the examples on how to format this parameter.
category string	The category of the group, this is the value to assign to the LDAP `groupType` attribute. If a new group is created then `security` will be used by default. Choices: distribution security
description string	The value to be assigned to the LDAP `description` attribute.
display_name string	The value to assign to the LDAP `displayName` attribute.
domain_password string	The password for `username`.
domain_server string	Specifies the Active Directory Domain Services instance to connect to. Can be in the form of an FQDN or NetBIOS name. If not specified then the value is based on the domain of the computer running PowerShell.
domain_username string	The username to use when interacting with AD. If this is not set then the user Ansible used to log in with will be used instead.
ignore_protection boolean	Will ignore the `ProtectedFromAccidentalDeletion` flag when deleting or moving a group. The module will fail if one of these actions need to occur and this value is set to `no`. Choices: no ← (default) yes
managed_by string	The value to be assigned to the LDAP `managedBy` attribute. This value can be in the forms `Distinguished Name`, `objectGUID`, `objectSid` or `sAMAccountName`, see examples for more details.
name string / required	The name of the group to create, modify or remove. This value can be in the forms `Distinguished Name`, `objectGUID`, `objectSid` or `sAMAccountName`, see examples for more details.
organizational_unit aliases: ou, path string	The full LDAP path to create or move the group to. This should be the path to the parent object to create or move the group to. See examples for details of how this path is formed.
protect boolean	Will set the `ProtectedFromAccidentalDeletion` flag based on this value. This flag stops a user from deleting or moving a group to a different path. Choices: no yes
scope string	The scope of the group. If `state=present` and the group doesn’t exist then this must be set. Choices: domainlocal global universal
state string	If `state=present` this module will ensure the group is created and is configured accordingly. If `state=absent` this module will delete the group if it exists Choices: absent present ← (default)

Notes 

Note

This must be run on a host that has the ActiveDirectory powershell module installed.

Examples 

- name: Ensure the group Cow exists using sAMAccountName
  community.windows.win_domain_group:
    name: Cow
    scope: global
    path: OU=groups,DC=ansible,DC=local

- name: Ensure the group Cow doesn't exist using the Distinguished Name
  community.windows.win_domain_group:
    name: CN=Cow,OU=groups,DC=ansible,DC=local
    state: absent

- name: Delete group ignoring the protection flag
  community.windows.win_domain_group:
    name: Cow
    state: absent
    ignore_protection: yes

- name: Create group with delete protection enabled and custom attributes
  community.windows.win_domain_group:
    name: Ansible Users
    scope: domainlocal
    category: security
    attributes:
      mail: [email protected]
      wWWHomePage: www.ansible.com
    ignore_protection: yes

- name: Change the OU of a group using the SID and ignore the protection flag
  community.windows.win_domain_group:
    name: S-1-5-21-2171456218-3732823212-122182344-1189
    scope: global
    organizational_unit: OU=groups,DC=ansible,DC=local
    ignore_protection: yes

- name: Add managed_by user
  community.windows.win_domain_group:
    name: Group Name Here
    managed_by: Domain Admins

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

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
attributes dictionary	Custom attributes that were set by the module. This does not show all the custom attributes rather just the ones that were set by the module. Returned: group exists and attributes are set on the module invocation Sample: {“mail”: “helpdesk@ansible.com”, “wWWHomePage”: “www.ansible.com”}
canonical_name string	The canonical name of the group. Returned: group exists Sample: “ansible.local/groups/Cow”
category string	The Group type value of the group, i.e. Security or Distribution. Returned: group exists Sample: “Security”
created boolean	Whether a group was created Returned: always Sample: true
description string	The Description of the group. Returned: group exists Sample: “Group Description”
display_name string	The Display name of the group. Returned: group exists Sample: “Users who connect through RDP”
distinguished_name string	The full Distinguished Name of the group. Returned: group exists Sample: “CN=Cow,OU=groups,DC=ansible,DC=local”
group_scope string	The Group scope value of the group. Returned: group exists Sample: “Universal”
guid string	The guid of the group. Returned: group exists Sample: “512a9adb-3fc0-4a26-9df0-e6ea1740cf45”
managed_by string	The full Distinguished Name of the AD object that is set on the managedBy attribute. Returned: group exists Sample: “CN=Domain Admins,CN=Users,DC=ansible,DC=local”
name string	The name of the group. Returned: group exists Sample: “Cow”
protected_from_accidental_deletion boolean	Whether the group is protected from accidental deletion. Returned: group exists Sample: true
sid string	The Security ID of the group. Returned: group exists Sample: “S-1-5-21-2171456218-3732823212-122182344-1189”

Authors

Jordan Borean (@jborean93)

Collection links

Issue Tracker Repository (Sources)

community.windows.win_domain_group module – Creates, modifies or removes domain groups

Synopsis

Parameters

Notes

See Also

Examples

Return Values