Files

michael 407e71072d ansible: document role variables and ship example playbook

README walks through what the role does, every default, and how to
invoke it from a parent playbook. examples/playbook.yml is a runnable
copy that targets a `workstations` group with a sudo=required+fido2
stack and one pending user.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-27 08:36:29 -07:00

defaults

ansible: scaffold dangerousthings.authforge role skeleton

2026-04-27 08:34:26 -07:00

examples

ansible: document role variables and ship example playbook

2026-04-27 08:36:29 -07:00

handlers

ansible: scaffold dangerousthings.authforge role skeleton

2026-04-27 08:34:26 -07:00

README.md

dangerousthings.authforge

Ansible role that installs and configures AuthForge, the FIDO2 / U2F / TOTP MFA stack for Ubuntu, on fleet hosts.

The role:

Adds the ppa:dangerousthings/authforge PPA.
Installs authforge-daemon, authforge-pam, and authforge-cli (and optionally authforge-gui for desktop fleets).
Renders a TOML fleet policy file at /etc/authforge/policy.d/90-fleet.conf from your variables.
Restarts authforge-daemon.service whenever the policy file changes.
Seeds first-login pending-enrollment flags via authforgectl pending set.

The role talks to AuthForge exclusively through authforgectl and the documented config-file shape - it does not touch daemon state directly.

Requirements

Target host: Ubuntu 22.04 (jammy) or 24.04 (noble).
Control host: Ansible 2.14 or newer.
The host must be able to reach ppa.launchpad.net (or your internal mirror - override authforge_ppa to point at it).

Role variables

All variables and their defaults live in defaults/main.yml.

Variable	Default	Description
`authforge_install_gui`	`false`	Also install the `authforge-gui` package (only useful on desktop fleets).
`authforge_ppa`	`ppa:dangerousthings/authforge`	Source PPA. Override to use an internal mirror.
`authforge_stacks`	`{}`	Map of PAM stack name to `{ mode, methods }`. `mode` is one of `disabled`, `optional`, `required`. `methods` is a list e.g. `["fido2", "totp"]`.
`authforge_storage_backend`	`per-user`	Credential storage backend. `per-user` writes under each user's home; `central` uses `authforge_storage_central_path`.
`authforge_storage_central_path`	`""`	Path for the central storage backend. Ignored when `authforge_storage_backend` is `per-user`.
`authforge_firstrun_methods`	`["fido2"]`	Methods accepted during first-login enrollment.
`authforge_firstrun_deadline_hours`	`0`	Hours before an unenrolled pending user is locked out. `0` disables the deadline.
`authforge_pending_users`	`[]`	List of `{ user, methods }` to mark as pending-enrollment.

Example playbook

- hosts: workstations
  become: true
  roles:
    - role: dangerousthings.authforge
      vars:
        authforge_stacks:
          sudo:
            mode: required
            methods: [fido2]
          sshd:
            mode: optional
            methods: [fido2, totp]
        authforge_pending_users:
          - user: alice
            methods: [fido2]

A runnable copy lives at examples/playbook.yml.

Idempotence notes

The apt_repository, apt, template, and file tasks are all idempotent; only the authforgectl pending set loop is forced to changed_when: true because the CLI does not currently expose a clean "is this user already pending?" check that's cheap to call from Ansible. Running pending set against an already-pending user is a no-op on the daemon side.
The handler restarts authforge-daemon only when the policy file contents actually change.

License

Apache-2.0. Same as the rest of AuthForge.