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