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