win_group_membership – Manage Windows local group membership

New in version 2.4.

Synopsis

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

Parameters

Parameter	Choices/Defaults	Comments
members list / required		A list of members to ensure are present/absent from the group. Accepts local users as .\username, and SERVERNAME\username. Accepts domain users and groups as DOMAIN\username and username@DOMAIN. Accepts service users as NT AUTHORITY\username. 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	Choices: absent present ← pure	Desired state of the members in the group. pure was added in Ansible 2.8. When state is pure, only the members specified will exist, and all other existing members not specified are removed.

See Also

See also

win_domain_group – Creates, modifies or removes domain groups

The official documentation on the win_domain_group module.

win_domain_membership – Manage domain/workgroup membership for a Windows host

The official documentation on the win_domain_membership module.

win_group – Add and remove local groups

The official documentation on the win_group module.

Examples

- name: Add a local and domain user to a local group
  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
  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
  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	Returned	Description
added list	success and state is present	A list of members added when state is present or pure; this is empty if no members are added. Sample: ['SERVERNAME\\NewLocalAdmin', 'DOMAIN\\TestUser']
members list	success	A list of all local group members at completion; this is empty if the group contains no members. Sample: ['DOMAIN\\TestUser', 'SERVERNAME\\NewLocalAdmin']
name string	always	The name of the target local group. Sample: Administrators
removed list	success and state is absent	A list of members removed when state is absent or pure; this is empty if no members are removed. Sample: ['DOMAIN\\TestGroup', 'NT AUTHORITY\\SYSTEM']

Status

• This module is not guaranteed to have a backwards compatible interface. [preview]
• This module is maintained by the Ansible Community. [community]

Authors

• Andrew Saraceni (@andrewsaraceni)

Hint

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