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
- / required
Name of the local group to manage membership on.
state
-
    Choices:
  • absent
  • present ←
Desired state of the members in the group.

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

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; 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; this is empty if no members are removed.

Sample:
['DOMAIN\\TestGroup', 'NT AUTHORITY\\SYSTEM']


Status

Authors

  • Andrew Saraceni (@andrewsaraceni)

Hint

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