1#!/usr/local/bin/python3.8 2# -*- coding: utf-8 -*- 3 4# Copyright: (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com> 5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) 6 7DOCUMENTATION = r''' 8--- 9module: win_domain_group_membership 10short_description: Manage Windows domain group membership 11description: 12 - Allows the addition and removal of domain users 13 and domain groups from/to a domain group. 14options: 15 name: 16 description: 17 - Name of the domain group to manage membership on. 18 type: str 19 required: yes 20 members: 21 description: 22 - A list of members to ensure are present/absent from the group. 23 - The given names must be a SamAccountName of a user, group, service account, or computer. 24 - For computers, you must add "$" after the name; for example, to add "Mycomputer" to a group, use "Mycomputer$" as the member. 25 - 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. 26 type: list 27 required: yes 28 state: 29 description: 30 - Desired state of the members in the group. 31 - When C(state) is C(pure), only the members specified will exist, 32 and all other existing members not specified are removed. 33 type: str 34 choices: [ absent, present, pure ] 35 default: present 36 domain_username: 37 description: 38 - The username to use when interacting with AD. 39 - If this is not set then the user Ansible used to log in with will be 40 used instead when using CredSSP or Kerberos with credential delegation. 41 type: str 42 domain_password: 43 description: 44 - The password for I(username). 45 type: str 46 domain_server: 47 description: 48 - Specifies the Active Directory Domain Services instance to connect to. 49 - Can be in the form of an FQDN or NetBIOS name. 50 - If not specified then the value is based on the domain of the computer 51 running PowerShell. 52 type: str 53notes: 54- This must be run on a host that has the ActiveDirectory powershell module installed. 55seealso: 56- module: community.windows.win_domain_user 57- module: community.windows.win_domain_group 58author: 59 - Marius Rieder (@jiuka) 60''' 61 62EXAMPLES = r''' 63- name: Add a domain user/group to a domain group 64 community.windows.win_domain_group_membership: 65 name: Foo 66 members: 67 - Bar 68 state: present 69 70- name: Remove a domain user/group from a domain group 71 community.windows.win_domain_group_membership: 72 name: Foo 73 members: 74 - Bar 75 state: absent 76 77- name: Ensure only a domain user/group exists in a domain group 78 community.windows.win_domain_group_membership: 79 name: Foo 80 members: 81 - Bar 82 state: pure 83 84- name: Add a computer to a domain group 85 community.windows.win_domain_group_membership: 86 name: Foo 87 members: 88 - DESKTOP$ 89 state: present 90 91- name: Add a domain user/group from another Domain in the multi-domain forest to a domain group 92 community.windows.win_domain_group_membership: 93 domain_server: DomainAAA.cloud 94 name: GroupinDomainAAA 95 members: 96 - DomainBBB.cloud\UserInDomainBBB 97 state: Present 98 99''' 100 101RETURN = r''' 102name: 103 description: The name of the target domain group. 104 returned: always 105 type: str 106 sample: Domain-Admins 107added: 108 description: A list of members added when C(state) is C(present) or 109 C(pure); this is empty if no members are added. 110 returned: success and C(state) is C(present) or C(pure) 111 type: list 112 sample: ["UserName", "GroupName"] 113removed: 114 description: A list of members removed when C(state) is C(absent) or 115 C(pure); this is empty if no members are removed. 116 returned: success and C(state) is C(absent) or C(pure) 117 type: list 118 sample: ["UserName", "GroupName"] 119members: 120 description: A list of all domain group members at completion; this is empty 121 if the group contains no members. 122 returned: success 123 type: list 124 sample: ["UserName", "GroupName"] 125''' 126