If you are not familiar with modules, check out Ansible - Getting Started with Modules.

The user module is similar to the useradd and usermod commands. The user module is used to create, modify, delete a users account on a managed node (e.g. target system).

If the users account does not exist, the users account will be created. If the users account already exists, the users account will be modified.

Create user account

In this example, user john.doe is created. This is similar to the useradd command.

- name: create john.doe account
  user:
    name: john.doe
    state: present

Password

When creating a user account, the users password can be defined. Let's say you try this.

- name: create john.doe account
  user:
    name: john.doe
    password: itsasecret
    state: present

The following will be returned.

[WARNING]: The input password appears not to have been hashed. The 'password' argument must be encrypted for this module to work properly.

As the warning suggests, the password must be hashed. Notice in this example that the clear text password is included, as a string since the value is wrapped in single quotes. For security reasons, a users password is almost never embedded in the playbook like this.

- name: create john.doe account
  user:
    name: john.doe
    password: "{{ 'itsasecret' | password_hash('sha512') }}"
    state: present

Instead, the ansible-vault create or ansible-vault encrypt command is used to create an encrypted file that contains the users password.

ansible-vault create locker.yml

Let's say the password in locker.yml is "itsasecret". Attempting to view the locker.yml file using the cat command will display something like this.

$ANSIBLE_VAULT;1.1;AES256
66303833643731313633343266616162613965636161313534376563383639646463376630626635
3136316663626536303061333531303234616562323637330a373633393736393863373566623261
65643764336263613730666665663763383063386137383331386136366232666637626566653032
3933393061666138650a656238386665343838613833643435623932306539633138376533613039
6531

Let's say users.yml is the playbook to create John Doe's user account. Here is how you could use the vault encrypted string in users.yml.

---
- hosts: all
  vars:
    password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          66303833643731313633343266616162613965636161313534376563383639646463376630626635
          3136316663626536303061333531303234616562323637330a373633393736393863373566623261
          65643764336263613730666665663763383063386137383331386136366232666637626566653032
          3933393061666138650a656238386665343838613833643435623932306539633138376533613039
          6531
  tasks:
    - name: create john.doe account
      user:
        name: john.doe
        password: "{{ '%s' | format(password) | regex_replace('\n', '') | password_hash('sha512') }}"
        state: present
...

When invoking users.yml to create John Doe's user account, you will either need to use the --ask-vault-pass flag to prompt you for the vault password that was used to encrypt locker.yml.

ansible-playbook users.yml --ask-vault-pass

Better yet, the password that was used to encrypt locker.yml could be appended to a file, such as .vault_password.txt.

echo "kdj$gj!mfn8$jf" > .vault_password.txt

And then update .vault_password.txt so that only the owner of the .vault_password.txt file can read and write to the .vault_password.txt file.

chmod 0600 .vault_password.txt

And now the --vault-password-file command line option can be used.

ansible-playbook users.yml --vault-password-file /usr/local/vault/.vault_password.txt

Following are additional, optional options.

• comment: almost always the users first and last name
• create_home: true or false, to create the users home directory
• home: the users home directory
• shell: something like /bin/bash or /bin/sh or /bin/fish
• uid: give the user a certain user ID number

- name: create john.doe account
  user:
    name: john.doe
    comment: John Doe
    password: "{{ 'itsasecret' | password_hash('sha512') }}"
    groups: wheel
    create_home: true
    home: /home/john.doe
    shell: /bin/bash
    uid: 1234
    expires: -1
    state: present

Delete user account

state: absent and remove:yes are used to delete/remove a users account. The remove option is used to remove the /home/john.doe directory.

- name: delete john.doe account
  user:
    name: john.doe
    state: absent
    remove: yes

Password expiration

In this example, john.doe user account will never expire, thus john.doe will never need to reset his password.

- name: john.doe password never expires
  user:
    name: john.doe
    expires: -1