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

Note

This plugin is part of the community.windows collection (version 1.7.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

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

Parameters

Parameter Choices/Defaults 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
    Choices:
  • distribution
  • security
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.
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
    Choices:
  • no ←
  • yes
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.
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
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.

aliases: ou, path
protect
boolean
    Choices:
  • no
  • yes
Will set the ProtectedFromAccidentalDeletion flag based on this value.
This flag stops a user from deleting or moving a group to a different path.
scope
string
    Choices:
  • domainlocal
  • global
  • universal
The scope of the group.
If state=present and the group doesn't exist then this must be set.
state
string
    Choices:
  • absent
  • present ←
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

Notes

Note

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

See Also

See also

ansible.windows.win_domain

The official documentation on the ansible.windows.win_domain module.

ansible.windows.win_domain_controller

The official documentation on the ansible.windows.win_domain_controller module.

community.windows.win_domain_computer

The official documentation on the community.windows.win_domain_computer module.

ansible.windows.win_domain_membership

The official documentation on the ansible.windows.win_domain_membership module.

community.windows.win_domain_user

The official documentation on the community.windows.win_domain_user module.

ansible.windows.win_group

The official documentation on the ansible.windows.win_group module.

ansible.windows.win_group_membership

The official documentation on the ansible.windows.win_group_membership module.

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 Returned Description
attributes
dictionary
group exists and attributes are set on the module invocation
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.

Sample:
{'mail': '[email protected]', 'wWWHomePage': 'www.ansible.com'}
canonical_name
string
group exists
The canonical name of the group.

Sample:
ansible.local/groups/Cow
category
string
group exists
The Group type value of the group, i.e. Security or Distribution.

Sample:
Security
created
boolean
always
Whether a group was created

Sample:
True
description
string
group exists
The Description of the group.

Sample:
Group Description
display_name
string
group exists
The Display name of the group.

Sample:
Users who connect through RDP
distinguished_name
string
group exists
The full Distinguished Name of the group.

Sample:
CN=Cow,OU=groups,DC=ansible,DC=local
group_scope
string
group exists
The Group scope value of the group.

Sample:
Universal
guid
string
group exists
The guid of the group.

Sample:
512a9adb-3fc0-4a26-9df0-e6ea1740cf45
managed_by
string
group exists
The full Distinguished Name of the AD object that is set on the managedBy attribute.

Sample:
CN=Domain Admins,CN=Users,DC=ansible,DC=local
name
string
group exists
The name of the group.

Sample:
Cow
protected_from_accidental_deletion
boolean
group exists
Whether the group is protected from accidental deletion.

Sample:
True
sid
string
group exists
The Security ID of the group.

Sample:
S-1-5-21-2171456218-3732823212-122182344-1189


Authors

  • Jordan Borean (@jborean93)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/windows/win_domain_group_module.html