1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6DOCUMENTATION = r'''
7---
8module: win_domain_user
9short_description: Manages Windows Active Directory user accounts
10description:
11     - Manages Windows Active Directory user accounts.
12options:
13  name:
14    description:
15      - Name of the user to create, remove or modify.
16    type: str
17    required: true
18  identity:
19    description:
20      - Identity parameter used to find the User in the Active Directory.
21      - This value can be in the forms C(Distinguished Name), C(objectGUID),
22        C(objectSid) or C(sAMAccountName).
23      - Default to C(name) if not set.
24    type: str
25  state:
26    description:
27      - When C(present), creates or updates the user account.
28      - When C(absent), removes the user account if it exists.
29      - When C(query), retrieves the user account details without making any changes.
30    type: str
31    choices: [ absent, present, query ]
32    default: present
33  enabled:
34    description:
35      - C(yes) will enable the user account.
36      - C(no) will disable the account.
37    type: bool
38    default: yes
39  account_locked:
40    description:
41      - C(no) will unlock the user account if locked.
42      - Note that there is not a way to lock an account as an administrator.
43      - Accounts are locked due to user actions; as an admin, you may only unlock a locked account.
44      - If you wish to administratively disable an account, set I(enabled) to C(no).
45    choices: [ no ]
46  description:
47    description:
48      - Description of the user
49    type: str
50  groups:
51    description:
52      - Adds or removes the user from this list of groups,
53        depending on the value of I(groups_action).
54      - To remove all but the Principal Group, set C(groups=<principal group name>) and
55        I(groups_action=replace).
56      - Note that users cannot be removed from their principal group (for example, "Domain Users").
57    type: list
58  groups_action:
59    description:
60      - If C(add), the user is added to each group in I(groups) where not already a member.
61      - If C(remove), the user is removed from each group in I(groups).
62      - If C(replace), the user is added as a member of each group in
63        I(groups) and removed from any other groups.
64    type: str
65    choices: [ add, remove, replace ]
66    default: replace
67  password:
68    description:
69      - Optionally set the user's password to this (plain text) value.
70      - To enable an account - I(enabled) - a password must already be
71        configured on the account, or you must provide a password here.
72    type: str
73  update_password:
74    description:
75      - C(always) will always update passwords.
76      - C(on_create) will only set the password for newly created users.
77      - C(when_changed) will only set the password when changed.
78    type: str
79    choices: [ always, on_create, when_changed ]
80    default: always
81  password_expired:
82    description:
83      - C(yes) will require the user to change their password at next login.
84      - C(no) will clear the expired password flag.
85      - This is mutually exclusive with I(password_never_expires).
86    type: bool
87  password_never_expires:
88    description:
89      - C(yes) will set the password to never expire.
90      - C(no) will allow the password to expire.
91      - This is mutually exclusive with I(password_expired).
92    type: bool
93  user_cannot_change_password:
94    description:
95      - C(yes) will prevent the user from changing their password.
96      - C(no) will allow the user to change their password.
97    type: bool
98  firstname:
99    description:
100      - Configures the user's first name (given name).
101    type: str
102  surname:
103    description:
104      - Configures the user's last name (surname).
105    type: str
106  company:
107    description:
108      - Configures the user's company name.
109    type: str
110  upn:
111    description:
112      - Configures the User Principal Name (UPN) for the account.
113      - This is not required, but is best practice to configure for modern
114        versions of Active Directory.
115      - The format is C(<username>@<domain>).
116    type: str
117  sam_account_name:
118    description:
119      - Configures the SAM Account Name (C(sAMAccountName)) for the account.
120      - This is allowed to a maximum of 20 characters due to pre-Windows 2000 restrictions.
121      - Default to the C(<username>) specified in C(upn) or C(name) if not set.
122    type: str
123    version_added: 1.7.0
124  email:
125    description:
126      - Configures the user's email address.
127      - This is a record in AD and does not do anything to configure any email
128        servers or systems.
129    type: str
130  street:
131    description:
132      - Configures the user's street address.
133    type: str
134  city:
135    description:
136      - Configures the user's city.
137    type: str
138  state_province:
139    description:
140      - Configures the user's state or province.
141    type: str
142  postal_code:
143    description:
144      - Configures the user's postal code / zip code.
145    type: str
146  country:
147    description:
148      - Configures the user's country code.
149      - Note that this is a two-character ISO 3166 code.
150    type: str
151  path:
152    description:
153      - Container or OU for the new user; if you do not specify this, the
154        user will be placed in the default container for users in the domain.
155      - Setting the path is only available when a new user is created;
156        if you specify a path on an existing user, the user's path will not
157        be updated - you must delete (e.g., C(state=absent)) the user and
158        then re-add the user with the appropriate path.
159    type: str
160  attributes:
161    description:
162      - A dict of custom LDAP attributes to set on the user.
163      - This can be used to set custom attributes that are not exposed as module
164        parameters, e.g. C(telephoneNumber).
165      - See the examples on how to format this parameter.
166    type: str
167  domain_username:
168    description:
169    - The username to use when interacting with AD.
170    - If this is not set then the user Ansible used to log in with will be
171      used instead when using CredSSP or Kerberos with credential delegation.
172    type: str
173  domain_password:
174    description:
175    - The password for I(username).
176    type: str
177  domain_server:
178    description:
179    - Specifies the Active Directory Domain Services instance to connect to.
180    - Can be in the form of an FQDN or NetBIOS name.
181    - If not specified then the value is based on the domain of the computer
182      running PowerShell.
183    type: str
184notes:
185  - Works with Windows 2012R2 and newer.
186  - If running on a server that is not a Domain Controller, credential
187    delegation through CredSSP or Kerberos with delegation must be used or the
188    I(domain_username), I(domain_password) must be set.
189  - Note that some individuals have confirmed successful operation on Windows
190    2008R2 servers with AD and AD Web Services enabled, but this has not
191    received the same degree of testing as Windows 2012R2.
192seealso:
193- module: ansible.windows.win_domain
194- module: ansible.windows.win_domain_controller
195- module: community.windows.win_domain_computer
196- module: community.windows.win_domain_group
197- module: ansible.windows.win_domain_membership
198- module: ansible.windows.win_user
199- module: community.windows.win_user_profile
200author:
201    - Nick Chandler (@nwchandler)
202'''
203
204EXAMPLES = r'''
205- name: Ensure user bob is present with address information
206  community.windows.win_domain_user:
207    name: bob
208    firstname: Bob
209    surname: Smith
210    company: BobCo
211    password: B0bP4ssw0rd
212    state: present
213    groups:
214      - Domain Admins
215    street: 123 4th St.
216    city: Sometown
217    state_province: IN
218    postal_code: 12345
219    country: US
220    attributes:
221      telephoneNumber: 555-123456
222
223- name: Ensure user bob is created and use custom credentials to create the user
224  community.windows.win_domain_user:
225    name: bob
226    firstname: Bob
227    surname: Smith
228    password: B0bP4ssw0rd
229    state: present
230    domain_username: DOMAIN\admin-account
231    domain_password: SomePas2w0rd
232    domain_server: domain@DOMAIN.COM
233
234- name: Ensure user bob is present in OU ou=test,dc=domain,dc=local
235  community.windows.win_domain_user:
236    name: bob
237    password: B0bP4ssw0rd
238    state: present
239    path: ou=test,dc=domain,dc=local
240    groups:
241      - Domain Admins
242
243- name: Ensure user bob is absent
244  community.windows.win_domain_user:
245    name: bob
246    state: absent
247'''
248
249RETURN = r'''
250account_locked:
251    description: true if the account is locked
252    returned: always
253    type: bool
254    sample: false
255changed:
256    description: true if the account changed during execution
257    returned: always
258    type: bool
259    sample: false
260city:
261    description: The user city
262    returned: always
263    type: str
264    sample: Indianapolis
265company:
266    description: The user company
267    returned: always
268    type: str
269    sample: RedHat
270country:
271    description: The user country
272    returned: always
273    type: str
274    sample: US
275description:
276    description: A description of the account
277    returned: always
278    type: str
279    sample: Server Administrator
280distinguished_name:
281    description: DN of the user account
282    returned: always
283    type: str
284    sample: CN=nick,OU=test,DC=domain,DC=local
285email:
286    description: The user email address
287    returned: always
288    type: str
289    sample: nick@domain.local
290enabled:
291    description: true if the account is enabled and false if disabled
292    returned: always
293    type: str
294    sample: true
295firstname:
296    description: The user first name
297    returned: always
298    type: str
299    sample: Nick
300groups:
301    description: AD Groups to which the account belongs
302    returned: always
303    type: list
304    sample: [ "Domain Admins", "Domain Users" ]
305msg:
306    description: Summary message of whether the user is present or absent
307    returned: always
308    type: str
309    sample: User nick is present
310name:
311    description: The username on the account
312    returned: always
313    type: str
314    sample: nick
315password_expired:
316    description: true if the account password has expired
317    returned: always
318    type: bool
319    sample: false
320password_updated:
321    description: true if the password changed during this execution
322    returned: always
323    type: bool
324    sample: true
325postal_code:
326    description: The user postal code
327    returned: always
328    type: str
329    sample: 46033
330sid:
331    description: The SID of the account
332    returned: always
333    type: str
334    sample: S-1-5-21-2752426336-228313920-2202711348-1175
335state:
336    description: The state of the user account
337    returned: always
338    type: str
339    sample: present
340state_province:
341    description: The user state or province
342    returned: always
343    type: str
344    sample: IN
345street:
346    description: The user street address
347    returned: always
348    type: str
349    sample: 123 4th St.
350surname:
351    description: The user last name
352    returned: always
353    type: str
354    sample: Doe
355upn:
356    description: The User Principal Name of the account
357    returned: always
358    type: str
359    sample: nick@domain.local
360sam_account_name:
361    description: The SAM Account Name of the account
362    returned: always
363    type: str
364    sample: nick
365    version_added: 1.7.0
366user_cannot_change_password:
367    description: true if the user is not allowed to change password
368    returned: always
369    type: str
370    sample: false
371created:
372  description: Whether a user was created
373  returned: always
374  type: bool
375  sample: true
376'''
377