W3cubDocs

/Ansible

community.windows.win_domain_group_membership – Manage Windows domain group membership

Note

This plugin is part of the community.windows collection (version 1.7.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 community.windows.

To use it in a playbook, specify: community.windows.win_domain_group_membership.

Synopsis
Parameters
Notes
See Also
Examples
Return Values

Synopsis

Allows the addition and removal of domain users and domain groups from/to a domain group.

Parameters

Parameter	Choices/Defaults	Comments
domain_password string		The password for username.
domain_server string		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 when using CredSSP or Kerberos with credential delegation.
members list / elements=string / required		A list of members to ensure are present/absent from the group. The given names must be a SamAccountName of a user, group, service account, or computer. For computers, you must add "$" after the name; for example, to add "Mycomputer" to a group, use "Mycomputer$" as the member. If the member object is part of another domain in a multi-domain forest, you must add the domain and "\" in front of the name.
name string / required		Name of the domain group to manage membership on.
state string	Choices: absent present ← pure	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.

Notes

Note

This must be run on a host that has the ActiveDirectory powershell module installed.

Examples

- name: Add a domain user/group to a domain group
  community.windows.win_domain_group_membership:
    name: Foo
    members:
      - Bar
    state: present

- name: Remove a domain user/group from a domain group
  community.windows.win_domain_group_membership:
    name: Foo
    members:
      - Bar
    state: absent

- name: Ensure only a domain user/group exists in a domain group
  community.windows.win_domain_group_membership:
    name: Foo
    members:
      - Bar
    state: pure

- name: Add a computer to a domain group
  community.windows.win_domain_group_membership:
    name: Foo
    members:
      - DESKTOP$
    state: present

- name: Add a domain user/group from another Domain in the multi-domain forest to a domain group
  community.windows.win_domain_group_membership:
    domain_server: DomainAAA.cloud
    name: GroupinDomainAAA
    members:
      - DomainBBB.cloud\UserInDomainBBB
    state: Present

Return Values

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

Key	Returned	Description
added list / elements=string	success and `state` is `present` or `pure`	A list of members added when `state` is `present` or `pure`; this is empty if no members are added. Sample: ['UserName', 'GroupName']
members list / elements=string	success	A list of all domain group members at completion; this is empty if the group contains no members. Sample: ['UserName', 'GroupName']
name string	always	The name of the target domain group. Sample: Domain-Admins
removed list / elements=string	success and `state` is `absent` or `pure`	A list of members removed when `state` is `absent` or `pure`; this is empty if no members are removed. Sample: ['UserName', 'GroupName']

Authors

Marius Rieder (@jiuka)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/windows/win_domain_group_membership_module.html