win_domain_user – Manages Windows Active Directory user accounts
win_domain_user – Manages Windows Active Directory user accounts
New in version 2.4.
Synopsis
- Manages Windows Active Directory user accounts.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
account_locked - |
|
|
attributes - added in 2.5 |
A dict of custom LDAP attributes to set on the user. This can be used to set custom attributes that are not exposed as module parameters, e.g. See the examples on how to format this parameter. | |
city - |
Configures the user's city. | |
company - |
Configures the user's company name. | |
country - |
Configures the user's country code. Note that this is a two-character ISO 3166 code. | |
description - |
Description of the user | |
domain_password - added in 2.5 |
The password for username. | |
domain_server - added in 2.5 |
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 - added in 2.5 |
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. | |
- |
Configures the user's email address. This is a record in AD and does not do anything to configure any email servers or systems. | |
enabled boolean |
|
|
firstname - |
Configures the user's first name (given name). | |
groups list |
Adds or removes the user from this list of groups, depending on the value of groups_action. To remove all but the Principal Group, set | |
groups_action - |
|
If If If |
name - / required |
Name of the user to create, remove or modify. | |
password - |
Optionally set the user's password to this (plain text) value. In order to enable an account - enabled - a password must already be configured on the account, or you must provide a password here. | |
password_expired boolean |
|
This is mutually exclusive with password_never_expires. |
password_never_expires boolean |
|
This is mutually exclusive with password_expired. |
path - |
Container or OU for the new user; if you do not specify this, the user will be placed in the default container for users in the domain. Setting the path is only available when a new user is created; if you specify a path on an existing user, the user's path will not be updated - you must delete (e.g., state=absent) the user and then re-add the user with the appropriate path. | |
postal_code - |
Configures the user's postal code / zip code. | |
state - |
|
When |
state_province - |
Configures the user's state or province. | |
street - |
Configures the user's street address. | |
surname - |
Configures the user's last name (surname). | |
update_password - |
|
Note that |
upn - |
Configures the User Principal Name (UPN) for the account. This is not required, but is best practice to configure for modern versions of Active Directory. The format is | |
user_cannot_change_password boolean |
|
|
Notes
Note
- Works with Windows 2012R2 and newer.
- If running on a server that is not a Domain Controller, credential delegation through CredSSP or Kerberos with delegation must be used or the domain_username, domain_password must be set.
- Note that some individuals have confirmed successful operation on Windows 2008R2 servers with AD and AD Web Services enabled, but this has not received the same degree of testing as Windows 2012R2.
Examples
- name: Ensure user bob is present with address information
win_domain_user:
name: bob
firstname: Bob
surname: Smith
company: BobCo
password: B0bP4ssw0rd
state: present
groups:
- Domain Admins
street: 123 4th St.
city: Sometown
state_province: IN
postal_code: 12345
country: US
attributes:
telephoneNumber: 555-123456
- name: Ensure user bob is created and use custom credentials to create the user
win_domain_user:
name: bob
firstname: Bob
surname: Smith
password: B0bP4ssw0rd
state: present
domain_username: DOMAIN\admin-account
domain_password: SomePas2w0rd
domain_server: [email protected]
- name: Ensure user bob is present in OU ou=test,dc=domain,dc=local
win_domain_user:
name: bob
password: B0bP4ssw0rd
state: present
path: ou=test,dc=domain,dc=local
groups:
- Domain Admins
- name: Ensure user bob is absent
win_domain_user:
name: bob
state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
account_locked boolean |
always |
true if the account is locked
|
changed boolean |
always |
true if the account changed during execution
|
city string |
always |
The user city
Sample: Indianapolis |
company string |
always |
The user company
Sample: RedHat |
country string |
always |
The user country
Sample: US |
description string |
always |
A description of the account
Sample: Server Administrator |
distinguished_name string |
always |
DN of the user account
Sample: CN=nick,OU=test,DC=domain,DC=local |
string |
always |
The user email address
Sample: |
enabled string |
always |
true if the account is enabled and false if disabled
Sample: True |
firstname string |
always |
The user first name
Sample: Nick |
groups list |
always |
AD Groups to which the account belongs
Sample: ['Domain Admins', 'Domain Users'] |
msg string |
always |
Summary message of whether the user is present or absent
Sample: User nick is present |
name string |
always |
The username on the account
Sample: nick |
password_expired boolean |
always |
true if the account password has expired
|
password_updated boolean |
always |
true if the password changed during this execution
Sample: True |
postal_code string |
always |
The user postal code
Sample: 46033 |
sid string |
always |
The SID of the account
Sample: S-1-5-21-2752426336-228313920-2202711348-1175 |
state string |
always |
The state of the user account
Sample: present |
state_province string |
always |
The user state or province
Sample: IN |
street string |
always |
The user street address
Sample: 123 4th St. |
surname string |
always |
The user last name
Sample: Doe |
upn string |
always |
The User Principal Name of the account
Sample: |
user_cannot_change_password string |
always |
true if the user is not allowed to change password
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Nick Chandler (@nwchandler)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/win_domain_user_module.html