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.

ansible.windows.win_group_membership module – Manage Windows local group membership

Note

This module is part of the ansible.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 ansible.windows.

To use it in a playbook, specify: ansible.windows.win_group_membership.

Synopsis

• Allows the addition and removal of local, service and domain users, and domain groups from a local group.

Parameters

Parameter	Comments
members list / elements=string / required	A list of members to ensure are present/absent from the group. Accepts local users as .username, and SERVERNAMEusername. Accepts domain users and groups as DOMAINusername and username@DOMAIN. Accepts service users as NT AUTHORITYusername. Accepts all local, domain and service user types as username, favoring domain lookups when in a domain.
name string / required	Name of the local group to manage membership on.
state string	Desired state of the members in the group. When state is pure, only the members specified will exist, and all other existing members not specified are removed. Choices: absent present ← (default) pure

See Also

See also

community.windows.win_domain_group

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

ansible.windows.win_domain_membership

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

ansible.windows.win_group

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

Examples

- name: Add a local and domain user to a local group
  ansible.windows.win_group_membership:
    name: Remote Desktop Users
    members:
      - NewLocalAdmin
      - DOMAIN\TestUser
    state: present

- name: Remove a domain group and service user from a local group
  ansible.windows.win_group_membership:
    name: Backup Operators
    members:
      - DOMAIN\TestGroup
      - NT AUTHORITY\SYSTEM
    state: absent

- name: Ensure only a domain user exists in a local group
  ansible.windows.win_group_membership:
    name: Remote Desktop Users
    members:
      - DOMAIN\TestUser
    state: pure

Return Values

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

Key	Description
added list / elements=string	A list of members added when state is present or pure; this is empty if no members are added. Returned: success and state is present Sample: [“SERVERNAME\\NewLocalAdmin”, “DOMAIN\\TestUser”]
members list / elements=string	A list of all local group members at completion; this is empty if the group contains no members. Returned: success Sample: [“DOMAIN\\TestUser”, “SERVERNAME\\NewLocalAdmin”]
name string	The name of the target local group. Returned: always Sample: “Administrators”
removed list / elements=string	A list of members removed when state is absent or pure; this is empty if no members are removed. Returned: success and state is absent Sample: [“DOMAIN\\TestGroup”, “NT AUTHORITY\\SYSTEM”]

Authors

• Andrew Saraceni (@andrewsaraceni)

Collection links

Issue Tracker Repository (Sources)