User Management

When to use it

To give a colleague or a deployment tool its own account on your servers, to control who can use sudo, and to take access away when someone leaves. Each run does one action on the users you name, so every run's record says exactly what was done to whom. Run it on many servers at once to keep accounts the same across a fleet.

Choosing the options

Action

• List users — every login account (root, and accounts with a UID of 1000 or above) with its sudo access, status, shell, SSH key count and groups. Needs no other option.
• Create users — creates each account with a home directory and no password. People sign in with an SSH key, so add one under SSH public keys in the same run. Groups and sudo can be given in the same run.
• Grant sudo or groups — gives existing users the sudo access and groups you choose.
• Revoke sudo or groups — removes the groups you name, and with Sudo set to Remove sudo, the sudo access this playbook or the sudo and wheel groups gave.
• Add SSH keys — adds public keys to existing users' ~/.ssh/authorized_keys. Keys already there are not duplicated.
• Lock users — refuses password and SSH key logins without deleting anything. Use it the moment someone should lose access.
• Unlock users — reverses a lock.
• Remove users — deletes accounts. Refused while the user has processes running.

Users — the account names, one per line or separated by commas: lowercase letters, digits, - and _, starting with a letter or _, such as alice or deploy.

Sudo

• No change — leaves sudo as it is.
• Sudo, asking for the user's password — adds the user to the sudo group on Ubuntu and Debian, or wheel on the RHEL family. The user needs a password for sudo to ask for; the run says when they have none, and it can be set on the server, for alice with passwd alice.
• Sudo without a password — writes a file named after the user, such as /etc/sudoers.d/iap-alice, with NOPASSWD: ALL, checked with visudo before it is installed. Right for accounts that only sign in with SSH keys, and for deployment tools.
• Remove sudo — with Revoke, takes sudo away.

Groups — extra groups, such as docker, www-data or nginx. Added for Create and Grant, removed for Revoke.

Create missing groups — off, a group that does not exist stops the run, which catches typing mistakes. Turn it on to create new groups such as developers.

SSH public keys — one key per line, each the whole line from a .pub file, starting with ssh-ed25519, ssh-rsa, ecdsa-sha2- or sk-. Only public keys: never paste a private key. Options such as command= in front of a key are refused.

Login shell — for Create. Bash for people. No login for accounts that only run services or transfer files.

Delete the home directory — for Remove. Off keeps the user's home directory, such as /home/alice, so you can check or archive the files first.

What it never touches

• root, the account the platform signs in with, and system accounts (below UID 1000, and nobody) are never created, changed, locked or removed. Locking the platform's own account would cut the platform off from the server with no way back.
• /etc/sudoers itself is never edited. The only sudo rules this playbook writes are its own files in /etc/sudoers.d, named iap- followed by the user name.

After the run

Run List users to see the result on every server. New users sign in with the private key that matches the public key you added, for alice on a server at 203.0.113.10: ssh alice@203.0.113.10.

When someone leaves: Lock users immediately on every server, then Revoke sudo or groups, and Remove users once their files have been checked.

Common problems

"… is the account the platform signs in with, so it is never … by this playbook" — Change that account from the server's console, or connect the server with another account first.

"There is no user called … on this server. Use Create to add it." — The account does not exist on this server. Run Create users for it.

"There is no group called … on this server." — Check the group name, or turn on Create missing groups.

"… has … process(es) running, which usually means an open session." — Lock the user first, which refuses new logins, end their sessions on the server (for alice, pkill -u alice), then remove the account.

"… has no password, so sudo will ask for one that does not exist." — Set a password on the server (for alice, passwd alice), or grant Sudo without a password instead.

"… can still use sudo through a rule this playbook did not write" — Another sudo rule, in /etc/sudoers or a file in /etc/sudoers.d, grants access. The run shows the rule; remove it with visudo.

"sudo does not read /etc/sudoers.d on this server" — The @includedir /etc/sudoers.d line is missing from /etc/sudoers. Add it with visudo, then run again.

"One of the SSH keys is not an OpenSSH public key." — Paste the whole single line from the .pub file, not the private key and not a key in PuTTY's format. For a PuTTY key, load it in PuTTYgen and copy the box labelled Public key for pasting into OpenSSH authorized_keys file. For an OpenSSH private key, print its public line with ssh-keygen -y -f ~/.ssh/id_ed25519, using your own key file.