NixOS users.users attribute missing passwordExpiry for credential lifecycle management

The short answer

There is no upstream NixOS option that maps to the /etc/shadow aging fields (last change, max days, expiry date). The users.users.<name> attribute set covers passwords (hashedPassword, initialPassword), shells, groups, and SSH keys, but not the fields managed by chage. The practical mechanism today is to run chage idempotently from your configuration — via system.activationScripts or a systemd oneshot — so the policy lives in the Nix expression even though the module doesn't own the field.

What is confirmed vs. what depends on your release

Confirmed behavior: NixOS activation only writes the shadow fields the user module knows about. Expiry values set manually with chage are therefore invisible to your configuration, and whether they survive a rebuild untouched has varied across nixpkgs releases and depends on users.mutableUsers. Do not assume either "rebuilds preserve expiry" or "rebuilds reset it" — verify on your pinned release (see below). Also confirmed: removing a user from the configuration does not delete the account; the shadow entry, including its aging fields, remains until you run userdel.

Version-controlling the policy

A minimal activation script keeps expiry declarative:

system.activationScripts.userExpiry =
  lib.stringAfter [ "users" ] ''
    for u in alice bob; do
      if id "$u" >/dev/null 2>&1; then
        ${pkgs.shadow}/bin/chage -M 90 -W 7 "$u"
      fi
    done
  '';

Two details matter. First, the id guard handles first activation, when the user may not exist yet depending on script ordering. Second, chage -M is naturally idempotent for the max-days field, but avoid chage -d (last-change date) in a script that runs on every rebuild — it would reset the aging clock each switch. If you need absolute expiry dates, chage -E 2027-01-01 is also idempotent. For larger fleets, generate the loop from an attribute set in your config so users and their policies are declared in one place and reviewed in the same diff.

If you already set users.mutableUsers = false with hashedPassword, note that this makes password content declarative but still does not reset aging fields — drift in expiry persists unless you script it as above.

Auditing and reconciliation

Build the audit from the same source of truth. A periodic systemd timer (or a CI job against a built system) can compare actual state against expected values:

getent shadow alice   # field 8 is the expiry date (days since epoch)
chage -l alice        # human-readable view

A simple check script can parse getent shadow output and fail if field 8 (or field 5, max days) differs from the value in your Nix expression. Run it as a systemd.timers entry with OnCalendar=daily and wire failures into your existing alerting. For orphaned accounts, reconcile by diffing getent passwd against the users declared in your configuration and removing stragglers with userdel — there is no automatic purge.

Verify before you rely on it

1. Confirm the option gap on your release: nixos-option users.users, or read the users module in your pinned nixpkgs.
2. Run getent shadow <user> before and after nixos-rebuild switch to observe whether expiry fields change on your release.
3. Rebuild twice with the activation script and diff /etc/shadow to confirm idempotency.

One caveat worth flagging: if PAM modules (e.g., pam_unix with aging enforcement) also act on these fields, make sure the scripted policy and PAM behavior agree, or you risk contradictory lockout behavior. The exact interaction depends on your PAM stack, so test a forced-expiry account in a VM generation before rolling out.