a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
community.general/lib/ansible/modules/windows/win_domain_user.py

366 lines
11 KiB
Python
Raw Blame History

#!/usr/bin/python
# -*- coding: utf-8 -*-
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
# this is a windows documentation stub. actual code lives in the .ps1
# file of the same name
ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['preview'],
'supported_by': 'community'}
DOCUMENTATION = r'''
---
module: win_domain_user
version_added: '2.4'
short_description: Manages Windows Active Directory user accounts
description:
- Manages Windows Active Directory user accounts.
options:
name:
description:
- Name of the user to create, remove or modify.
type: str
required: true
state:
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.
type: str
choices: [ absent, present, query ]
default: present
enabled:
description:
- C(yes) will enable the user account.
- C(no) will disable the account.
type: bool
default: yes
account_locked:
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 I(enabled) to C(no).
choices: [ no ]
description:
description:
- Description of the user
type: str
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").
type: list
groups_action:
description:
- 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).
- If C(replace), the user is added as a member of each group in
I(groups) and removed from any other groups.
type: str
choices: [ add, remove, replace ]
default: replace
password:
description:
- Optionally set the user's password to this (plain text) value.
- To enable an account - I(enabled) - a password must already be
configured on the account, or you must provide a password here.
type: str
update_password:
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.
type: str
choices: [ always, on_create ]
default: always
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
firstname:
description:
- Configures the user's first name (given name).
type: str
surname:
description:
- Configures the user's last name (surname).
type: str
company:
description:
- Configures the user's company name.
type: str
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 C(<username>@<domain>).
type: str
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.
type: str
street:
description:
- Configures the user's street address.
type: str
city:
description:
- Configures the user's city.
type: str
state_province:
description:
- Configures the user's state or province.
type: str
postal_code:
description:
- Configures the user's postal code / zip code.
type: str
country:
description:
- Configures the user's country code.
- Note that this is a two-character ISO 3166 code.
type: str
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., C(state=absent)) the user and
then re-add the user with the appropriate path.
type: str
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.
type: str
version_added: '2.5'
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.
type: str
version_added: '2.5'
domain_password:
description:
- The password for I(username).
type: str
version_added: '2.5'
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.
type: str
version_added: '2.5'
notes:
- 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
I(domain_username), I(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.
seealso:
- module: win_domain
- module: win_domain_controller
- module: win_domain_computer
- module: win_domain_group
- module: win_domain_membership
- module: win_user
- module: win_user_profile
author:
- Nick Chandler (@nwchandler)
'''
EXAMPLES = r'''
- 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
'''
RETURN = r'''
account_locked:
description: true if the account is locked
returned: always
type: bool
sample: false
changed:
description: true if the account changed during execution
returned: always
type: bool
sample: false
city:
description: The user city
returned: always
type: str
sample: Indianapolis
company:
description: The user company
returned: always
type: str
sample: RedHat
country:
description: The user country
returned: always
type: str
sample: US
description:
description: A description of the account
returned: always
type: str
sample: Server Administrator
distinguished_name:
description: DN of the user account
returned: always
type: str
sample: CN=nick,OU=test,DC=domain,DC=local
email:
description: The user email address
returned: always
type: str
sample: nick@domain.local
enabled:
description: true if the account is enabled and false if disabled
returned: always
type: str
sample: true
firstname:
description: The user first name
returned: always
type: str
sample: Nick
groups:
description: AD Groups to which the account belongs
returned: always
type: list
sample: [ "Domain Admins", "Domain Users" ]
msg:
description: Summary message of whether the user is present or absent
returned: always
type: str
sample: User nick is present
name:
description: The username on the account
returned: always
type: str
sample: nick
password_expired:
description: true if the account password has expired
returned: always
type: bool
sample: false
password_updated:
description: true if the password changed during this execution
returned: always
type: bool
sample: true
postal_code:
description: The user postal code
returned: always
type: str
sample: 46033
sid:
description: The SID of the account
returned: always
type: str
sample: S-1-5-21-2752426336-228313920-2202711348-1175
state:
description: The state of the user account
returned: always
type: str
sample: present
state_province:
description: The user state or province
returned: always
type: str
sample: IN
street:
description: The user street address
returned: always
type: str
sample: 123 4th St.
surname:
description: The user last name
returned: always
type: str
sample: Doe
upn:
description: The User Principal Name of the account
returned: always
type: str
sample: nick@domain.local
user_cannot_change_password:
description: true if the user is not allowed to change password
returned: always
type: str
sample: false
'''
Reference in New Issue View Git Blame Copy Permalink