/ home / ansible / ansible.windows / 2.3.0 / module / win_group_membership

ansible.windows.win_group_membership (2.3.0) — module

Manage Windows local group membership

Authors: Andrew Saraceni (@andrewsaraceni)

Install collection

Install with ansible-galaxy collection install ansible.windows:==2.3.0

Add to requirements.yml

  collections:
    - name: ansible.windows
      version: 2.3.0

Description

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

Usage examples

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Scanned by Steampunk Spotter

- 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

Inputs

    
name:
    description:
    - Name of the local group to manage membership on.
    required: true
    type: str

state:
    choices:
    - absent
    - present
    - pure
    default: present
    description:
    - Desired state of the members in the group.
    - When C(state) is C(pure), only the members specified will exist, and all other existing
      members not specified are removed.
    type: str

members:
    description:
    - 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.
    elements: str
    required: true
    type: list

Outputs

added:
  description: A list of members added when C(state) is C(present) or C(pure); this
    is empty if no members are added.
  returned: success and C(state) is C(present)
  sample:
  - SERVERNAME\NewLocalAdmin
  - DOMAIN\TestUser
  type: list
members:
  description: 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
  type: list
name:
  description: The name of the target local group.
  returned: always
  sample: Administrators
  type: str
removed:
  description: A list of members removed when C(state) is C(absent) or C(pure); this
    is empty if no members are removed.
  returned: success and C(state) is C(absent)
  sample:
  - DOMAIN\TestGroup
  - NT AUTHORITY\SYSTEM
  type: list

Install collection

Add to requirements.yml

Description

Usage examples

Inputs

Outputs

See also