258 lines
9.6 KiB
Markdown
258 lines
9.6 KiB
Markdown
# UniFi Access Badge-In Dashboard
|
|
|
|
A Dockerised Flask + SQLite attendance dashboard that receives real-time door unlock
|
|
webhooks from one or more **UniFi Access Developer API** controllers, resolves
|
|
badge holders to real names, and displays a unified live attendance table with
|
|
first/latest badge times, source controller, and ON TIME / LATE status.
|
|
|
|
**Multi-controller:** add as many UniFi Access controllers as the host can reach.
|
|
Webhooks are auto-registered when you add a controller from the UI.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Linux host with Docker + Docker Compose (Unraid works great)
|
|
- One or more UniFi OS consoles running **UniFi Access 1.9.1 or later**
|
|
- Network reachability from the dashboard host to each controller on port **12445**
|
|
- A **Developer API token** from each UniFi Access controller you plan to add
|
|
|
|
---
|
|
|
|
## Step 1 — Open firewall port 12445 to each controller
|
|
|
|
The UniFi Access Open API runs exclusively on **port 12445** (HTTPS, self-signed cert).
|
|
The host running the dashboard must be able to reach each controller on that port.
|
|
|
|
In UniFi Network → Settings → Firewall & Security → Firewall Rules, add a **LAN IN** rule on each controller:
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Action | Accept |
|
|
| Protocol | TCP |
|
|
| Destination Port | 12445 |
|
|
| Source | the subnet your dashboard host lives on |
|
|
|
|
Verify from the dashboard host:
|
|
|
|
```bash
|
|
# Linux:
|
|
nc -zv 10.0.0.1 12445
|
|
|
|
# Windows PowerShell:
|
|
Test-NetConnection -ComputerName 10.0.0.1 -Port 12445
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2 — Generate a Developer API token on each controller
|
|
|
|
> ⚠️ This token is **different** from the UniFi OS / Network API token.
|
|
> Creating it in the wrong place will result in 401 Unauthorized errors.
|
|
|
|
1. Open the UniFi OS console at `https://<controller-ip>` in a browser.
|
|
2. Open the **Access** app (blue door icon).
|
|
3. Go to **Settings → General → Advanced → API Token**.
|
|
4. Click **Create New**, name it, enable **all permission scopes**, and pick a validity period.
|
|
5. Click **Create** and **immediately copy the token** — it's only shown once.
|
|
|
|
Repeat for each controller you plan to add.
|
|
|
|
---
|
|
|
|
## Step 3 — Clone the repo on the host
|
|
|
|
```bash
|
|
cd /mnt/user/appdata
|
|
git clone https://github.com/jasonMPM/unifi-access-dashboard.git unifi-access-dashboard
|
|
cd unifi-access-dashboard
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4 — Create your .env file
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
nano .env
|
|
```
|
|
|
|
The `UNIFI_*` and `WEBHOOK_SECRET` values are **optional**. If set, they auto-create
|
|
a "Default" controller on first boot — handy for single-controller installs. You can
|
|
leave them blank and add every controller via the UI instead.
|
|
|
|
```dotenv
|
|
# Optional: seeds a "Default" controller on first boot
|
|
UNIFI_HOST=10.0.0.1
|
|
UNIFI_PORT=12445
|
|
UNIFI_API_TOKEN=YOUR_TOKEN_HERE
|
|
WEBHOOK_SECRET=
|
|
|
|
# Required
|
|
TZ=America/Chicago
|
|
DB_PATH=/data/dashboard.db
|
|
|
|
# Optional: override the URL the dashboard uses when registering webhooks
|
|
# DASHBOARD_BASE_URL=http://10.0.0.5:8000
|
|
```
|
|
|
|
> **Never commit `.env` to git.** It is listed in `.gitignore`.
|
|
|
|
---
|
|
|
|
## Step 5 — Build and start the container
|
|
|
|
```bash
|
|
cd /mnt/user/appdata/unifi-access-dashboard
|
|
/usr/bin/docker compose up -d --build
|
|
```
|
|
|
|
The container will:
|
|
- Build the image from the local `Dockerfile`
|
|
- Start Flask on port **8000**
|
|
- Create `/data/dashboard.db` inside the container (mapped to `./data/` on the host)
|
|
- If env-var credentials are set, seed a "Default" controller and sync its users
|
|
- Schedule a user-cache refresh every hour for every enabled controller
|
|
|
|
Verify it's running:
|
|
|
|
```bash
|
|
/usr/bin/docker ps
|
|
/usr/bin/docker logs -f unifi-access-dashboard
|
|
```
|
|
|
|
---
|
|
|
|
## Step 6 — Add controllers from the UI
|
|
|
|
Navigate to:
|
|
|
|
```
|
|
http://<HOST-IP>:8000/
|
|
```
|
|
|
|
Click the **⚙ Controllers** button in the header. For each UniFi Access instance you want
|
|
to receive events from, fill in:
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| **Name** | Friendly label shown in the Source column (e.g. "Main Office", "Warehouse") |
|
|
| **Host / IP** | Controller IP, e.g. `10.0.0.1` |
|
|
| **Port** | `12445` (don't change unless your controller is non-standard) |
|
|
| **Developer API Token** | Token from Step 2 |
|
|
|
|
Click **Add Controller**. The dashboard will:
|
|
|
|
1. Call the controller's `POST /webhooks/endpoints` with this dashboard's URL.
|
|
2. Store the returned webhook secret so it can verify incoming events (HMAC-SHA256).
|
|
3. Immediately sync the controller's user list to resolve names.
|
|
|
|
If the controller can't reach this dashboard at the URL shown in the form hint
|
|
(it uses `window.location.origin` by default), set `DASHBOARD_BASE_URL` in `.env`
|
|
and restart.
|
|
|
|
Per-controller actions in the modal:
|
|
|
|
| Action | Description |
|
|
|---|---|
|
|
| **Test** | Hits the controller's `/users` endpoint to confirm the token works |
|
|
| **Sync** | Pulls latest users from this controller right now |
|
|
| **Enable / Disable** | Pause ingestion + sync without deleting the controller |
|
|
| **Remove** | Deletes the webhook from the controller and wipes all its badge events from the dashboard |
|
|
|
|
---
|
|
|
|
## Dashboard controls
|
|
|
|
| Control | Description |
|
|
|---|---|
|
|
| **Date picker** | Choose which day to view |
|
|
| **Badged in by** | Set your on-time cutoff (HH:MM) |
|
|
| **Controller** | Filter the table to one controller, or show All |
|
|
| **Refresh** | Reload the table |
|
|
| **Sync Users** | Pull latest users from every enabled controller |
|
|
| **⚙ Controllers** | Add / manage controllers |
|
|
| **Reset Day** | Delete all badge records for the selected date (respects the Controller filter — testing only) |
|
|
|
|
### Dashboard columns
|
|
|
|
| Column | Description |
|
|
|---|---|
|
|
| **#** | Row number |
|
|
| **Name** | Resolved display name from UniFi Access |
|
|
| **Source** | Controller this badge event came from |
|
|
| **First Badge In** | Earliest door entry for the day — never changes once set |
|
|
| **Latest Badge In** | Most recent entry — shows *"— same"* if only one badge event |
|
|
| **Actor ID** | First 8 characters of the UniFi user UUID |
|
|
| **Status** | ON TIME (green) or LATE (red) based on first badge vs cutoff |
|
|
|
|
> The same physical person on two different controllers will appear as two rows
|
|
> (different controllers issue different user UUIDs). They're distinguishable
|
|
> by the Source column.
|
|
|
|
---
|
|
|
|
## Updating from GitHub
|
|
|
|
```bash
|
|
cd /mnt/user/appdata/unifi-access-dashboard
|
|
git pull
|
|
/usr/bin/docker compose up -d --build
|
|
```
|
|
|
|
The SQLite database in `./data/` persists across rebuilds. On first start after
|
|
upgrading from a single-controller install, existing badge events are
|
|
automatically attached to the seeded "Default" controller — nothing to migrate
|
|
by hand.
|
|
|
|
---
|
|
|
|
## API reference
|
|
|
|
All endpoints are unauthenticated by design — this app assumes a LAN-only
|
|
deployment. Do not expose port 8000 to the internet without putting a
|
|
reverse proxy with auth in front of it.
|
|
|
|
| Method | Path | Params / Body | Description |
|
|
|---|---|---|---|
|
|
| `POST` | `/api/unifi-access/<controller_id>` | webhook body | Receives UniFi Access webhook for that controller |
|
|
| `POST` | `/api/unifi-access` | webhook body | Legacy alias — routes to the oldest controller |
|
|
| `GET` | `/api/first-badge-status` | `date`, `cutoff`, `controller_id?` | Returns first + latest badge per user |
|
|
| `GET` | `/api/controllers` | — | List configured controllers |
|
|
| `POST` | `/api/controllers` | `name`, `host`, `port`, `api_token` | Add a controller (also registers webhook) |
|
|
| `PATCH` | `/api/controllers/<id>` | `name?`, `enabled?` | Rename or enable/disable a controller |
|
|
| `DELETE` | `/api/controllers/<id>` | — | Remove a controller (deletes webhook + its events) |
|
|
| `POST` | `/api/controllers/<id>/test` | — | Test controller reachability + token |
|
|
| `POST` | `/api/controllers/<id>/sync` | — | Sync one controller's user cache immediately |
|
|
| `GET` | `/api/sync-users` | — | Sync every enabled controller |
|
|
| `DELETE` | `/api/reset-day` | `date`, `controller_id?` | Delete badge records for a date (optionally scoped to one controller) |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Cause | Fix |
|
|
|---|---|---|
|
|
| Add Controller fails with "webhook registration rejected" | Token invalid or wrong scope | Regenerate token in Access → Settings → General → API Token with all scopes enabled |
|
|
| Add Controller fails with a connection error | Host unreachable on port 12445 | Verify firewall rule from Step 1; `nc -zv <ip> 12445` from the dashboard host |
|
|
| Events arrive but signature is rejected | Webhook secret missing or stale | Remove the controller and re-add it (the dashboard re-registers and gets a fresh secret) |
|
|
| Source column says "—" | Pre-migration row with no controller_id | Restart the container; the migration runs on every boot |
|
|
| Names show as `Unknown (xxxxxxxx...)` | Users not synced yet for that controller | Click **Sync** in the Controllers modal |
|
|
| Webhook URL stored in controller points to the wrong address | Browser's origin isn't reachable from the controller | Set `DASHBOARD_BASE_URL` in `.env`, remove + re-add the controller |
|
|
| `Port 12445 connection refused` | Firewall blocking port | Add LAN IN firewall rule in UniFi Network (Step 1) |
|
|
| Dashboard shows stale names after a user rename | Cache not refreshed | Click **Sync Users** or wait for the hourly auto-sync |
|
|
|
|
---
|
|
|
|
## Security notes
|
|
|
|
- `.env` is excluded from git via `.gitignore` — never commit it.
|
|
- API tokens are stored **in plaintext** in the SQLite DB; the dashboard
|
|
assumes a LAN-only deployment. Filesystem permissions on `./data/dashboard.db`
|
|
are the only thing protecting them.
|
|
- All admin endpoints (`/api/controllers/*`, `/api/sync-users`, `/api/reset-day`)
|
|
are **unauthenticated**. Do not expose port 8000 publicly. If external access
|
|
is required, place Nginx, Traefik, or Caddy with HTTPS + auth in front of port `8000`.
|
|
- Each controller's `webhook_secret` is enforced via HMAC-SHA256 on incoming
|
|
events so spoofed webhook posts from outside the LAN are rejected.
|