MFA

[tamorgen]

@toggledbits ,
I didn't want to pile on to the Login protection thread, but it reminded me about the MFA authentication. I tried to set it up once, and I could never get it to work. I got the pop up to login, and it returns an Access Denied page.

I'm starting with a clean, newly opened browser window, and my credentials are correct.

I'm using these directions, and using my URL and my username in place of UUUU

https://notmyurl.com/api/v1/mfa.add/notmyuserid?askauth=1

I tried it via my private IP as well, and I'm still receiving Access Denied. I'm unsure what the log file is that would provide the why.

I'm running latest-26298-fbb75fb8

[gwp1]

@tamorgen My experience is the same and I’m sure I’m missing something obvious. I’m at work and haven’t had time to dig in as yet.

[gwp1]

@tamorgen I beat it. With a lot of AI help, admittedly. But it's up and running. I'm using Portainer inside Proxmox so it had... challenges... with what IP it was "seeing".

I'll see if tomorrow I can pull together the full steps.

[tamorgen]

@gwp1 said in MFA:

I'm using Portainer inside Proxmox so it had... challenges... with what IP it was "seeing".

I have the same setup, and I have my own Cloudflare domain, with a local LXC running Cloudflared for the tunnels, so yeah, I'm sure the authenticator is having issues with the IPs and the virtual networking. Please let me know what you did to get past it.

[gwp1]

@tamorgen I asked Lumo to pull together everything that WORKED to get to the end goal (we had a lot of trial and error at times).

Good luck. YMMV.

Here's the working procedure — tested end-to-end with your Reactor instance.

---

Setting Up MFA for Multi-System Reactor (MSR)

Problem: Requesting http://<reactor_host>:8111/api/v1/mfa.add/<username>?askauth=1 from a browser or host shell returns ACCESS DENIED, even after entering valid admin credentials.

Root Cause: When access control is enabled (config/users.yaml exists), MSR restricts API access by default to localhost only. Traffic reaching a Dockerised Reactor from the host appears to come from Docker's bridge gateway (172.17.0.1), not 127.0.0.1, so it fails the default loopback rule and falls through to the catch-all deny.

---

Working Setup Procedure

Prerequisites

• MSR installed and running in Docker
• Target user exists in config/users.yaml and is a member of the admin group
• You have shell access to the host running the container

Step 1: Enter the Reactor Container

docker exec -it <container_name> sh

Replace <container_name> with your container name (e.g., reactor). Find it with:

docker ps | grep reactor

Step 2: Request the MFA QR Code From Inside the Container

Run the following command inside the container:

curl -s -o /tmp/qrcode.png -u <target_username> \
  http://localhost:8111/api/v1/mfa.add/<target_username>

When prompted, enter the target user's password.

Notes:

• -u <target_username> makes curl prompt for the password interactively (safer than typing it in the command line).
• The request originates from 127.0.0.1 inside the container, which matches the default ACL allowing loopback.
• The ?askauth=1 parameter is not needed here — it's only for the browser-based flow.

Step 3: Verify the Image Was Generated

ls -la /tmp/qrcode.png
head -c 8 /tmp/qrcode.png | od -An -tx1

You should see 89 50 4e 47 0d 0a 1a 0a — the PNG magic bytes. If you see 41 63 63 65 73 73 20 64 ("Access denied"), the file is stale from an earlier failed attempt. Redo step 2.

Step 4: Copy the QR Code to Your Desktop

exit
docker cp <container_name>:/tmp/qrcode.png ~/Desktop/qr-mfa.png

Or from a separate machine:

scp root@<host_ip>:/tmp/qrcode.png .

Step 5: Scan the QR Code

Open qr-mfa.png in any image viewer and scan it with your authenticator app (Google Authenticator, Authy, Aegis, 1Password, Bitwarden, Ente, etc.).

Alternative: Manual Entry
If your viewer can't display the image, install zbar-tools:

apt update && apt install -y --no-install-recommends zbar-tools
zbarimg --quiet ~/Desktop/qr-mfa.png

This outputs an otpauth://totp/... URI. Use the secret= value in your authenticator app's "Manual Entry" or "Setup Key" option.

Step 6: Test the Login

Log into the Reactor UI as the target user. You should be prompted for a six-digit code. Enter the code from your authenticator app.

Step 7: Clean Up the Seed File

Both the host and container copies contain the TOTP secret in plaintext. Delete them after enrollment:

rm -f ~/Desktop/qr-mfa.png
docker exec <container_name> rm -f /tmp/qrcode.png

Anyone who photographs this image can generate valid codes indefinitely.

---

Recovery (If You Lose the Authenticator)

The same procedure applies for clearing MFA. From inside the container:

docker exec -it <container_name> sh
curl -s -o /dev/null -u <admin_user> -w 'HTTP %{http_code}\n' \
  http://localhost:8111/api/v1/mfa.clear/<username_to_clear>

You'll need admin credentials. The endpoint is subject to the same default ACL rules, so it must be called from inside the container.

---

What Not to Do (Common Pitfalls)

Don't	Do
Run curl from the host shell against localhost or the LAN IP	Run the command from inside the container via docker exec
Use ?askauth=1 with curl	Only use it for the browser-based flow
Edit users.yaml to add ACL rules	Not required for the initial setup; stick to stock defaults
Paste my suggested YAML without validation	Use python3 -c "import yaml; yaml.safe_load(open('users.yaml'))" to verify first
Re-run mfa.add after enrolling	It may rotate the secret and invalidate your existing setup
Leave the QR code PNG anywhere accessible	Delete it immediately after enrollment

---

Troubleshooting

Symptom	Likely Cause	Fix
HTTP 403 Forbidden	Request from host/network interface	Use docker exec to run curl inside container
HTTP 401 Unauthorized	Wrong password	Verify credentials, use -u <user> for interactive prompt
Empty qrcode.png or "Access denied" text	Stale file from failed attempt	Delete old copy and re-run step 2
File opens as text instead of image	curl wrote error body over PNG	Check magic bytes with od before scanning

---

Optional: Browser-Based MFA Setup (Requires ACL Change)

If you prefer the browser method from a LAN machine (http://<reactor_host>:8111/api/v1/mfa.add/<user>?askauth=1), you need to add an ACL rule in config/users.yaml:

api_acls:
  - url: "/api/v1/mfa.add"
    group: admin
    allow: true
  - url: "/api/v1/mfa.clear"
    group: admin
    allow: true

Place these at the top level of the file (same indent as users: and groups:). Then restart:

docker restart <container_name>

Validate the YAML before applying:

python3 -c "import yaml; yaml.safe_load(open('/var/reactor/config/users.yaml')); print('Valid')"

Note: This is optional. The docker exec method works on stock defaults and requires no configuration changes.

---

Documented based on real-world testing with Reactor in Docker, October 2026.

[gwp1]

When working you'll get this prompt for the code:

[toggledbits]

You don't need to run the commands from inside the container. You can add an ACL allowing the IP address of the host system or your LAN subnet (as source_ip). But in any case, once you add the user/group ACL entry to permit the endpoint as suggested above, as long as that entry also doesn't restrict IP (i.e. doesn't contain source_ip), any IP that can log in as that user (or a user in that group, if group), will be allowed from anywhere (i.e. authorized queries from outside the container will work).

[gwp1]

@toggledbits I honestly did not recall implementing any ACL or Access Control settings outside of adding a user.

That to say, this morning when I went in to start that work, I found entries in place. No recollection of adding them - but it made all of the above suddenly make much more sense.

I can remove the above post if it's way out.