Ansible User Modules
Introduction
When managing systems at scale, one of the most common administrative tasks is user management. Creating users, assigning them to groups, managing their access, and removing accounts are essential operations for system administrators. Ansible, a powerful automation tool, offers dedicated modules specifically designed for user management that make these tasks efficient and consistent across your infrastructure.
In this guide, we'll explore the primary Ansible modules for user management:
user
- For creating, modifying, and removing user accountsgroup
- For managing user groupsauthorized_key
- For deploying SSH public keys
These modules enable you to implement secure, consistent user management across all your systems through automation.
The user
Module
The user
module is the primary module for managing user accounts on remote systems. It handles creating new users, updating existing users, and removing user accounts.
Basic Syntax
- name: Create a user
user:
name: username
state: present
Key Parameters
The user
module supports many parameters to define user properties:
Parameter | Description |
---|---|
name | Username for the account (required) |
state | Whether the account should exist or not (present or absent ) |
comment | User's full name or description |
uid | User ID number |
group | Primary group for the user |
groups | List of supplementary groups |
append | Whether to add groups to user's existing groups (yes/no) |
shell | User's login shell |
home | Home directory path |
password | Encrypted password string |
system | Create a system account (yes/no) |
create_home | Whether to create the user's home directory (yes/no) |
remove | Remove home directory when deleting user (yes/no) |
update_password | When to update passwords (always or on_create ) |
Practical Examples
Creating a Basic User
- name: Add user john
user:
name: john
comment: "John Smith"
shell: /bin/bash
groups: admins,developers
append: yes
This task creates a user named "john" with the full name "John Smith," assigns /bin/bash
as the login shell, and adds the user to both the "admins" and "developers" groups without removing any existing group assignments.
Creating a System User
- name: Add application user
user:
name: app_user
system: yes
shell: /bin/false
home: /opt/application
create_home: yes
This example creates a system user account for running an application. System users typically have UIDs in a lower range and are not meant for login.
Setting a Password
- name: Add user with password
user:
name: secure_user
password: "{{ encrypted_password }}"
Important: Never store passwords in plaintext. The password
parameter expects an already encrypted string. You can generate this using:
- name: Generate encrypted password
command: openssl passwd -salt somestring -1 "{{ user_password }}"
delegate_to: localhost
register: encrypted_pass
no_log: yes # Prevents password from being shown in logs
Removing a User
- name: Remove user
user:
name: former_employee
state: absent
remove: yes # Removes home directory
Managing Multiple Users
- name: Manage multiple users
user:
name: "{{ item.name }}"
state: present
groups: "{{ item.groups | default(omit) }}"
shell: "{{ item.shell | default('/bin/bash') }}"
loop:
- name: alice
groups: developers,testers
- name: bob
groups: developers
shell: /bin/zsh
- name: charlie
The group
Module
The group
module manages user groups on remote systems. While the user
module can create groups implicitly, the group
module offers more control over group properties.
Basic Syntax
- name: Create a group
group:
name: groupname
state: present
Key Parameters
Parameter | Description |
---|---|
name | Group name (required) |
state | Whether the group should exist (present or absent ) |
gid | Group ID |
system | Create a system group (yes/no) |
Practical Examples
Creating a Basic Group
- name: Create developers group
group:
name: developers
state: present
Creating a System Group with Specific GID
- name: Create app group
group:
name: appgroup
gid: 800
system: yes
Managing Multiple Groups
- name: Set up project groups
group:
name: "{{ item }}"
state: present
loop:
- developers
- testers
- operations
- security
The authorized_key
Module
The authorized_key
module manages SSH authorized keys for user authentication, allowing you to control SSH access across your infrastructure.
Basic Syntax
- name: Add SSH key for user
authorized_key:
user: username
key: ssh-rsa AAAA...
state: present
Key Parameters
Parameter | Description |
---|---|
user | Username to add key to (required) |
key | SSH public key string or URL (required) |
path | Custom location for the authorized_keys file |
manage_dir | Whether to create the .ssh directory if missing |
state | Whether key should be present or absent |
exclusive | Remove all other keys from the authorized_keys file |
Practical Examples
Adding SSH Key from a String
- name: Add deploy key
authorized_key:
user: deployer
state: present
key: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... [email protected]"
Adding SSH Key from a File
- name: Add admin keys
authorized_key:
user: "{{ item }}"
state: present
key: "{{ lookup('file', '/path/to/public_keys/admin.pub') }}"
loop:
- admin
- ops
Exclusive Key Access
- name: Ensure only authorized keys are present
authorized_key:
user: secure_user
state: present
exclusive: yes
key: "{{ lookup('file', '/path/to/public_keys/secure_key.pub') }}"
This removes all other keys, ensuring only the specified key provides access.
Real-World Example: User Onboarding Playbook
Let's create a complete playbook for onboarding new team members:
---
# onboard_user.yml
- name: Onboard new team member
hosts: all
become: yes
vars_prompt:
- name: username
prompt: Enter username
private: no
- name: fullname
prompt: Enter full name
private: no
- name: team
prompt: Enter team (dev, ops, or security)
private: no
tasks:
- name: Ensure team groups exist
group:
name: "{{ item }}"
state: present
loop:
- developers
- operations
- security
- shared
- name: Set groups based on team
set_fact:
user_groups:
dev: "developers,shared"
ops: "operations,shared"
security: "security,shared"
- name: Create user account
user:
name: "{{ username }}"
comment: "{{ fullname }}"
groups: "{{ user_groups[team] }}"
shell: /bin/bash
generate_ssh_key: yes
ssh_key_bits: 4096
register: user_info
- name: Add authorized SSH key
authorized_key:
user: "{{ username }}"
key: "{{ lookup('file', 'files/ssh_keys/{{ username }}.pub') }}"
state: present
when: username in lookup('fileglob', 'files/ssh_keys/*.pub') | map('basename') | map('splitext') | map('first') | list
- name: Apply sudo privileges for ops team
copy:
dest: "/etc/sudoers.d/{{ username }}"
content: "{{ username }} ALL=(ALL) ALL"
validate: /usr/sbin/visudo -cf %s
when: team == "ops"
- name: Send welcome email
delegate_to: localhost
mail:
host: smtp.example.com
port: 25
to: "{{ fullname }} <{{ username }}@example.com>"
subject: "Welcome to the team!"
body: |
Hi {{ fullname }},
Your account has been created on our systems.
Username: {{ username }}
Your SSH key is available at: {{ user_info.ssh_key_file }}
Welcome aboard!
The IT Team
To use this playbook:
- Create a
files/ssh_keys
directory with public keys named after the users - Run the playbook:
ansible-playbook onboard_user.yml
- Enter the prompted information
Understanding User Management Workflow
The following diagram illustrates how Ansible user modules interact with the system:
Advanced Concepts
Idempotency in User Management
Ansible modules are designed to be idempotent, meaning they only make changes if necessary. For example, if you run a task to create a user that already exists, Ansible will not create a duplicate or error—it will simply verify the user exists and move on.
Managing User Passwords Securely
For secure password management, consider using Ansible Vault to encrypt sensitive variables:
# Encrypt the password
ansible-vault encrypt_string 'secretpassword' --name 'user_password'
Then in your playbook:
- name: Create user with vault-encrypted password
user:
name: secure_user
password: "{{ user_password | password_hash('sha512') }}"
Temporary Access with expires
Parameter
You can set an expiration date for user accounts:
- name: Create temporary contractor account
user:
name: contractor
expires: "{{ (ansible_date_time.date | to_datetime('%Y-%m-%d') + datetime.timedelta(days=30)).strftime('%Y-%m-%d') }}"
Summary
Ansible's user modules provide powerful tools for managing users and access control across your infrastructure:
- The
user
module handles creating, modifying, and removing user accounts - The
group
module manages user groups - The
authorized_key
module controls SSH key-based authentication
With these modules, you can automate user management, ensure consistency, and implement security best practices across all your systems.
Exercises
- Create a playbook that adds three users (dev, admin, guest) with appropriate groups and permissions
- Modify your playbook to make it work for both Linux and BSD systems (hint: check the Ansible documentation for OS-specific parameters)
- Create a "user offboarding" playbook that safely removes a user account while archiving their home directory
- Extend the onboarding example to include additional security measures such as password complexity requirements and account expiration
Additional Resources
If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)