407e71072d
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>
77 lines
3.1 KiB
Markdown
77 lines
3.1 KiB
Markdown
# dangerousthings.authforge
|
|
|
|
Ansible role that installs and configures [AuthForge](https://github.com/dangerousthings/authforge),
|
|
the FIDO2 / U2F / TOTP MFA stack for Ubuntu, on fleet hosts.
|
|
|
|
The role:
|
|
|
|
1. Adds the `ppa:dangerousthings/authforge` PPA.
|
|
2. Installs `authforge-daemon`, `authforge-pam`, and `authforge-cli` (and
|
|
optionally `authforge-gui` for desktop fleets).
|
|
3. Renders a TOML fleet policy file at `/etc/authforge/policy.d/90-fleet.conf`
|
|
from your variables.
|
|
4. Restarts `authforge-daemon.service` whenever the policy file changes.
|
|
5. 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
|
|
|
|
```yaml
|
|
- 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.
|