- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# win_domain_group – Creates, modifies or removes domain groups

New in version 2.4.

- Synopsis

- Parameters

- Notes

- See Also

- Examples

- Return Values

- Status

## Synopsis

- Creates, modifies or removes groups in Active Directory.

- For local groups, use the 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 added in 2.5 |  | 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

win_domain – Ensures the existence of a Windows domain

  The official documentation on the win_domain module.

win_domain_controller – Manage domain controller/member server state for a Windows host

  The official documentation on the win_domain_controller module.

win_domain_computer – Manage computers in Active Directory

  The official documentation on the win_domain_computer module.

win_domain_membership – Manage domain/workgroup membership for a Windows host

  The official documentation on the win_domain_membership module.

win_domain_user – Manages Windows Active Directory user accounts

  The official documentation on the win_domain_user module.

win_group – Add and remove local groups

  The official documentation on the win_group module.

win_group_membership – Manage Windows local group membership

  The official documentation on the win_group_membership module.

## 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 doesn'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: helpdesk@ansible.com
          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: yes

    - name: Add managed_by user
      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
      win_domain_group:
        name: Test Group
        domain_username: user@CORP.ANSIBLE.COM
        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': 'helpdesk@ansible.com', '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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Jordan Borean (@jborean93)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.