authorized_keys

authorized_keys manages a user's ~/.ssh/authorized_keys on the node: the file <home>/.ssh/authorized_keys of the account named by for_user_account, with the home from the account database. Every task says what happens to keys it does not list, with the required keys_not_listed. keep adds the listed keys and keeps other lines. remove makes the file contain exactly the listed keys, so removing someone from the list removes their access.

The node HTTPS API process reads the same file for every new connection. A key added this way gains MMX access; a removed key's next connection is refused, as Administrator SSH keys authorize HTTPS describes. To give an account on a node its own key pair, use ssh_key_pair. If the node's AuthorizedKeysFile points elsewhere, use MMX's file module to manage the configured path.

Inputs

  • for_user_account (string; required): the account and its home must exist; with state: absent, or with keys_not_listed: remove and no keys, a missing account is unchanged
  • keys (list of strings; optional): OpenSSH key lines: [options] type base64-key [comment]; a key's identity is its type and base64 key; no key twice; at least one of keys, key_files_on_controller_machine, or key_directories_on_controller_machine
  • key_files_on_controller_machine (list of strings; optional): files on the controller machine, relative to the project root, or to the role's directory inside a role like file.source, each with one or more key lines; blank lines and lines starting with # are skipped; read when the run starts, so mmx resume uses the same keys
  • key_directories_on_controller_machine (list of strings; optional): directories on the controller machine; every file directly inside whose name ends in .pub, in name order, read like key_files_on_controller_machine; a directory without a .pub file fails, since an empty list could lock everyone out (write keys: [] to remove every key); like file.source, key_files_on_controller_machine and key_directories_on_controller_machine may read the node's name, vars, role inputs, and loop items
  • replace_options_of_listed_keys (boolean; default false): with keys_not_listed: keep or remove, true replaces existing listed lines with the task's lines, including removing restrictions absent from them; without it, plain keys preserve existing lines and different explicit options fail before changes; omit with state: absent
  • keys_not_listed (remove or keep; required): keep adds missing keys and keeps unlisted lines; remove keeps only listed keys, and keys: [] empties the file; both preserve existing lines for plain keys and refuse different explicit options unless replace_options_of_listed_keys: true; omit with absent
  • state (present or absent; default present): absent removes the listed keys whatever their options; accepts only for_user_account, keys, key_files_on_controller_machine, and key_directories_on_controller_machine

Outputs

The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.

  • status
  • change
  • value.added
  • value.updated
  • value.removed

What a dryrun reports

Supported; lists keys to add, update, or remove by type, fingerprint, and comment.

Retries and time limits

Bounded automatic retries by default; retry: false turns them off.

The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.

Examples

Keys written in the task

- authorized_keys:
    for_user_account: deploy
    keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIORZZg3NlYdxJ28janK/DsJ1O0O2YgF7KN2aiEPskegs alice@laptop
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAII3tDLF30LgdbEPBetQzx/5yTYIIskR2lUV8GRnqXzer bob@laptop
      - 'from="10.0.0.0/8",no-agent-forwarding ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPpV63vQaaUhs7d11ravJpkOpRWhCElUYrbh42Kg0rrS ci'
    keys_not_listed: remove

The account deploy accepts exactly these three keys: Alice's, Bob's, and the key of the CI machine, which works only from 10.0.0.0/8 and without agent forwarding. Options come before the key type. An entry may also be a reference to a public-key variable you define, such as "{{ .vars.alice_key }}". With keys_not_listed: keep, the task would add the three keys and keep every other line.

Keys from files in the project

With one file for each person, the files decide who can log in:

- authorized_keys:
    for_user_account: deploy
    key_directories_on_controller_machine: [files/public_keys/production_deploy]
    key_files_on_controller_machine: [files/ci.pub]
    keys_not_listed: remove

key_files_on_controller_machine names files on your controller machine, and key_directories_on_controller_machine names directories whose files ending in .pub MMX reads, in name order. Deleting barbara.pub from the directory removes Barbara's key on the next run.

One directory of keys for each environment

Like file.source, a path may contain references to what the controller machine knows before it connects: the node's name, vars, role inputs, and loop items. With an environment value in each inventory's vars, every environment gets its own directory of keys:

- authorized_keys:
    for_user_account: deploy
    key_directories_on_controller_machine: ["files/public_keys/{{ .vars.environment }}"]
    keys_not_listed: remove

Remove a person's key

state: absent removes every line containing a listed key from the selected account's <home>/.ssh/authorized_keys, regardless of the line's options:

- authorized_keys:
    for_user_account: deploy
    key_files_on_controller_machine: [files/public_keys/former/barbara.pub]
    state: absent

For an account that no longer exists, the state: absent task succeeds without changes, so offboarding does not fail after the account is gone.

How it works

Where the keys come from

The keys come from three fields, which add up to one list; at least one of them is required:

  • keys: key lines written in the task. An entry may be a reference, such as "{{ .vars.alice_key }}".
  • key_files_on_controller_machine: files on the controller machine. Each holds one or more key lines; blank lines and lines starting with # are skipped.
  • key_directories_on_controller_machine: directories on the controller machine. MMX reads every file directly inside whose name ends in .pub, in name order.

Both kinds of paths are relative to the project root, or to the role's directory inside a role, as file.source is. A path with references is resolved for every node of the inventory before the run starts.

Each key line is one OpenSSH key line: optional options, key type, base64 key, and optional comment, parsed as MMX's HTTPS authorization parses it. A key's identity is its type and base64 body. MMX reads the key files when the run starts and saves the keys with the run, so mmx resume installs the same keys even after the files changed.

Keys that are not listed

  • keep adds missing listed keys after existing lines and keeps unlisted lines.
  • remove keeps only listed keys, in the task's order; keys: [] empties the file.

Both choices use the same options rule. Without replace_options_of_listed_keys: true, a plain public-key line keeps every existing line for that key, including its options and comment. A task line with options must match the existing options; different options fail the task before any change, in dryrun too. The error names the key, the file, the node's options, the task's options, and the line to add.

With replace_options_of_listed_keys: true, the task's line replaces existing listed lines and drops repeats, under both keep and remove. This can remove restrictions such as from= when the task's line has none. A key missing from the node is always added exactly as the task gives it.

state: absent accepts for_user_account and the three key fields and removes those keys wherever they appear, whatever their options; a missing file or key is unchanged.

Accounts that do not exist

A task that only takes keys away, state: absent or keys_not_listed: remove with no keys, changes nothing for an account that no longer exists, so offboarding does not fail after the account is gone. Except for the removal-only cases above, tasks require the account and the account's home directory. Dryrun reports tasks requiring an account and home directory as not checked when the account or home directory is missing. During a run, a missing account or home directory fails tasks requiring the account and home directory.

The file and its directory

MMX creates .ssh with mode 0700 and authorized_keys with mode 0600 when missing, and sets both to the user and the user's primary group with those modes. It writes through the atomic installer without following links; a symlink at .ssh or at the file fails the task, because the account controls that directory. An unchanged rerun finds the keys and metadata already in place. The file is not an input of a node task block's service.

Dryrun and results identify keys by type, SHA-256 fingerprint, and comment, in .this_node_task.value.added, .updated, and .removed, instead of a text difference. A run that fails before the file is written shows no value, so a node task in on_failure can read what happened.

Errors and what they mean

What fails What the failure means, and what to do
Validation fails and names the file and line A key line is malformed.
Validation fails and names both places A key appears twice. Keep one.
Validation fails and names the file A key file holds no key.
Validation fails and names the directory, and for a path with references the node A key directory holds no file ending in .pub. MMX does not read alice_ed25519 or alice.key. To remove every key on purpose, write keys: [].
The run fails before it starts, naming the node and the path A path with references resolves to a missing file or directory for that node.
Validation fails for a path that reads a fact or a node task's result A fact is a value MMX gathers about a node, such as .node.arch. Facts and node task results are known only during the run. Use the node's name, vars, role inputs, or loop items.
The task reports different node and task options Add replace_options_of_listed_keys: true to replace the existing line with the task's line, or make the task's options match. No file or metadata changes first. Dryrun also refuses differing node and task options.
The task fails for a symlink <home>/.ssh or <home>/.ssh/authorized_keys is a symlink. MMX refuses the authorized_keys task.
A dryrun reports the task not checked The account or its home does not exist yet; an earlier node task may create it.

Tested on

Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04, Arch Linux, openSUSE Leap 16.1, Rocky Linux 9, AlmaLinux 10, Fedora 45.

The base suite covers this module (access.py, account_units.py) and runs on every tested distribution.

Three suites cover the module on Debian 12 and 13 and Ubuntu 24.04 and 26.04:

  • tests/integration/access.py: keys_not_listed: keep with HTTPS access, remove refusing HTTPS and SSH, and state: absent refusing HTTPS;
  • tests/integration/account_units.py: key files and directories, resume with saved keys, and removal for a removed account;
  • tests/integration/ssh_key_pairs.py: a key made by ssh_key_pair on one node and accepted on another through a fleet stage output.

The validation record gives the latest results.

Why it works this way

  • File input names say controller machine. The controller process reads the files named by key_files_on_controller_machine and key_directories_on_controller_machine before connecting to nodes. The input names distinguish controller machine paths from node paths.

  • keys_not_listed is required. A task that owns a list says what happens to the rest, as the rule for every module says. With remove, deleting a person's file removes that person's access.

  • A key directory without a .pub file fails. An empty list would make keys_not_listed: remove empty authorized_keys and lock out every administrator, the key MMX connects with included. A task that means "no keys" says keys: [].

  • Plain public keys keep existing restrictions under keep and remove. Reading a .pub file must not remove an administrator's access restrictions. Different explicit options fail because ignoring a restriction the task writes would give a wrong result without telling anyone. Replacing options needs replace_options_of_listed_keys: true, following the protective-choice rule.

  • Keys are saved with the run. mmx resume installs the saved keys even after the controller machine's source key files changed.

  • A task that only removes keys is unchanged for a missing account. Offboarding then does not fail after the account is gone.

  • A symlink at <home>/.ssh or <home>/.ssh/authorized_keys fails. The account controls <home>/.ssh.

This page is docs/reference/modules/authorized_keys.md in the MMX repository.