Try SpotterManages Windows Active Directory user accounts
| "added in version" 2.4 of ansible.builtin"
Authors: Nick Chandler (@nwchandler)
preview | supported by community
pipInstall with pip install ansible==2.5.12
Manages Windows Active Directory user accounts.
- 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: domain@DOMAIN.COM
- 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
upn:
description:
- 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 "<username>@<domain>".
city:
description:
- Configures the user's city
name:
description:
- Name of the user to create, remove or modify.
required: true
path:
description:
- 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.
email:
description:
- Configures the user's email address. This is a record in AD and does not do anything
to configure any email servers or systems.
state:
choices:
- present
- absent
- query
default: present
description:
- When C(present), creates or updates the user account. When C(absent), removes the
user account if it exists. When C(query), retrieves the user account details without
making any changes.
groups:
description:
- Adds or removes the user from this list of groups, depending on the value of I(groups_action).
To remove all but the Principal Group, set C(groups=<principal group name>) and
I(groups_action=replace). Note that users cannot be removed from their principal
group (for example, "Domain Users").
street:
description:
- Configures the user's street address
company:
description:
- Configures the user's company name
country:
description:
- Configures the user's country code. Note that this is a two-character ISO 3166 code.
enabled:
default: 'yes'
description:
- C(yes) will enable the user account. C(no) will disable the account.
type: bool
surname:
description:
- Configures the user's last name (surname)
password:
description:
- Optionally set the user's password to this (plain text) value. In order to enable
an account - I(enabled) - a password must already be configured on the account,
or you must provide a password here.
firstname:
description:
- Configures the user's first name (given name)
attributes:
description:
- 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. C(telephoneNumber).
- See the examples on how to format this parameter.
version_added: '2.5'
version_added_collection: ansible.builtin
description:
description:
- Description of the user
postal_code:
description:
- Configures the user's postal code / zip code
domain_server:
description:
- 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.
version_added: '2.5'
version_added_collection: ansible.builtin
groups_action:
choices:
- replace
- add
- remove
default: replace
description:
- If C(replace), the user is added as a member of each group in I(groups) and removed
from any other groups. If C(add), the user is added to each group in I(groups)
where not already a member. If C(remove), the user is removed from each group in
I(groups).
account_locked:
choices:
- 'no'
description:
- C(no) will unlock the user account if locked. Note that there is not a way to lock
an account as an administrator. Accounts are locked due to user actions; as an admin,
you may only unlock a locked account. If you wish to administratively disable an
account, set 'enabled' to 'no'.
type: bool
state_province:
description:
- Configures the user's state or province
domain_password:
description:
- The password for C(username).
version_added: '2.5'
version_added_collection: ansible.builtin
domain_username:
description:
- 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.
version_added: '2.5'
version_added_collection: ansible.builtin
update_password:
choices:
- always
- on_create
default: always
description:
- C(always) will update passwords if they differ. C(on_create) will only set the
password for newly created users. Note that C(always) will always report an Ansible
status of 'changed' because we cannot determine whether the new password differs
from the old password.
password_expired:
description:
- C(yes) will require the user to change their password at next login. C(no) will
clear the expired password flag. This is mutually exclusive with I(password_never_expires).
type: bool
password_never_expires:
description:
- C(yes) will set the password to never expire. C(no) will allow the password to
expire. This is mutually exclusive with I(password_expired)
type: bool
user_cannot_change_password:
description:
- C(yes) will prevent the user from changing their password. C(no) will allow the
user to change their password.
type: bool
account_locked: description: true if the account is locked returned: always sample: false type: boolean changed: description: true if the account changed during execution returned: always sample: false type: boolean city: description: The user city returned: always sample: Indianapolis type: string company: description: The user company returned: always sample: RedHat type: string country: description: The user country returned: always sample: US type: string description: description: A description of the account returned: always sample: Server Administrator type: string distinguished_name: description: DN of the user account returned: always sample: CN=nick,OU=test,DC=domain,DC=local type: string email: description: The user email address returned: always sample: nick@domain.local type: string enabled: description: true if the account is enabled and false if disabled returned: always sample: true type: string firstname: description: The user first name returned: always sample: Nick type: string groups: description: AD Groups to which the account belongs returned: always sample: - Domain Admins - Domain Users type: list msg: description: Summary message of whether the user is present or absent returned: always sample: User nick is present type: string name: description: The username on the account returned: always sample: nick type: string password_expired: description: true if the account password has expired returned: always sample: false type: boolean password_updated: description: true if the password changed during this execution returned: always sample: true type: boolean postal_code: description: The user postal code returned: always sample: 46033 type: string sid: description: The SID of the account returned: always sample: S-1-5-21-2752426336-228313920-2202711348-1175 type: string state: description: The state of the user account returned: always sample: present type: string state_province: description: The user state or province returned: always sample: IN type: string street: description: The user street address returned: always sample: 123 4th St. type: string surname: description: The user last name returned: always sample: Doe type: string upn: description: The User Principal Name of the account returned: always sample: nick@domain.local type: string user_cannot_change_password: description: true if the user is not allowed to change password returned: always sample: false type: string