54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# Homelab MFA
|
|
|
|
Biometric push-approval for your homelab logins. When you sign in through Authentik, your phone
|
|
buzzes — approve with a fingerprint, or deny with one tap. A self-hosted alternative to Duo /
|
|
Authy push, with **no third-party cloud** in the loop.
|
|
|
|
## How it works
|
|
|
|
1. You log in via **Authentik**. A flow step fires an **ntfy** notification to your phone with two
|
|
action buttons: **Approve** and **Deny**.
|
|
2. The buttons are `homemfa://approve?token=…` / `homemfa://deny?token=…` deep links that open this app.
|
|
3. **Approve** triggers a biometric prompt (fingerprint / face / device PIN). On success the app
|
|
POSTs `approve:<token>` to `ntfy.khodak.me/mfa-approve`; your Authentik flow is listening on that
|
|
topic and completes the login.
|
|
4. **Deny** POSTs `deny:<token>` to `mfa-deny` and blocks the login — no biometric needed to reject.
|
|
|
|
The activity is `showWhenLocked` + `turnScreenOn`, so an approval works straight from the lock screen.
|
|
|
|
## Features
|
|
|
|
- **Biometric gate** — `BIOMETRIC_STRONG` or device credential required to approve (deny is instant)
|
|
- **Lock-screen ready** — wakes the screen and shows over the keyguard
|
|
- **Self-hosted** — talks only to your own ntfy instance; no Firebase, no vendor cloud
|
|
- **Zero stored secrets** — stateless; each request carries a one-time token
|
|
- **Setup self-check** — a "Test Biometric" button confirms enrollment before you rely on it
|
|
|
|
## Screenshots
|
|
|
|
<p align="center">
|
|
<img src="docs/screenshots/setup.png" width="240" alt="Setup / ready screen">
|
|
|
|
<img src="docs/screenshots/approved.png" width="240" alt="Login approved">
|
|
</p>
|
|
|
|
## Install
|
|
|
|
1. Download `homelab-mfa.apk` from the [latest release](../../releases/latest)
|
|
2. On your Android phone: **Settings → Apps → Install unknown apps** → allow your browser/file manager
|
|
3. Open the APK and tap Install
|
|
4. Open **Homelab MFA** and tap **Test Biometric** to confirm your fingerprint is enrolled
|
|
|
|
## Server side
|
|
|
|
You need:
|
|
|
|
- An **ntfy** instance reachable at `ntfy.khodak.me` (or change the host in `MainActivity.kt`)
|
|
- An **Authentik** flow that, on login, publishes a notification with the two `homemfa://` action
|
|
buttons, then waits on the `mfa-approve` / `mfa-deny` topics for the decision
|
|
|
|
## Requirements
|
|
|
|
- Android 9.0+ (API 28)
|
|
- A fingerprint, face, or device PIN enrolled
|