win_domain_group - creates, modifies or removes domain groups

New in version 2.4.

Synopsis

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

Options

parameter required default choices comments
attributes
 no
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
 no
  • 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
 no
The value to be assigned to the LDAP description attribute.
display_name
 no
The value to assign to the LDAP displayName attribute.
domain_password
 no
The password for username.
domain_username
 no
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
 no no
  • yes
  • no
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
 no
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
 yes
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
 no
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
 no
  • yes
  • no
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
 no
  • domainlocal
  • global
  • universal
The scope of the group.
If state=present and the group doesn't exist then this must be set.
state
 no present
  • 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

Examples

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

- name: ensure the group Cow does't exist using the Distinguished Name
  win_domain_group:
    name: CN=Cow,OU=groups,DC=ansible,DC=local
    state: absent

- name: delete group ignoring the protection flag
  win_domain_group:
    name: Cow
    state: absent
    ignore_protection: yes

- name: create group with delete protection enabled and custom attributes
  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
  win_domain_group:
    name: S-1-5-21-2171456218-3732823212-122182344-1189
    scope: global
    organizational_unit: OU=groups,DC=ansible,DC=local
    ignore_protection: True

- name: add managed_by user
  win_domain_group:
    name: Group Name Here
    managed_by: Domain Admins

Return Values

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

name description returned type sample
attributes
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.
 group exists and attributes are set on the module invocation dict {'mail': '[email protected]', 'wWWHomePage': 'www.ansible.com'}
canonical_name
The canonical name of the group.
 group exists string ansible.local/groups/Cow
category
The Group type value of the group, i.e. Security or Distribution.
 group exists string Security
description
The Description of the group.
 group exists string Group Description
display_name
The Display name of the group.
 group exists string Users who connect through RDP
distinguished_name
The full Distinguished Name of the group.
 group exists string CN=Cow,OU=groups,DC=ansible,DC=local
group_scope
The Group scope value of the group.
 group exists string Universal
guid
The guid of the group.
 group exists string 512a9adb-3fc0-4a26-9df0-e6ea1740cf45
managed_by
The full Distinguished Name of the AD object that is set on the managedBy attribute.
 group exists string CN=Domain Admins,CN=Users,DC=ansible,DC=local
name
The name of the group.
 group exists string Cow
protected_from_accidental_deletion
Whether the group is protected from accidental deletion.
 group exists bool True
sid
The Security ID of the group.
 group exists string S-1-5-21-2171456218-3732823212-122182344-1189

Notes

Note

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

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

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