starred/nginx-proxy-manager-NginxProxyManager

Fork 0

mirror of https://github.com/NginxProxyManager/nginx-proxy-manager.git synced 2026-04-25 01:15:51 +03:00

[GH-ISSUE #5174] TOTP Documentation Update - User Awareness #3132

New issue

Open

opened 2026-02-26 07:37:55 +03:00 by kerem · 4 comments

kerem commented

2026-02-26 07:37:55 +03:00

Owner

Originally created by @Hackpig1974 on GitHub (Jan 15, 2026).
Original GitHub issue: https://github.com/NginxProxyManager/nginx-proxy-manager/issues/5174

Hi,

I wanted to share some feedback after implementing TOTP 2FA on my Nginx Proxy Manager instance. This isn't a bug, but rather a documentation enhancement that could help users avoid a common integration issue.

Issue Encountered:
After enabling TOTP 2FA on my NPM admin account, my Homepage dashboard widget for NPM immediately stopped working and began showing "API Error: Internal Error" in the UI. The NPM container logs showed repeated jwt malformed warnings whenever Homepage attempted to authenticate.

Root Cause:
Homepage (and likely other dashboard/monitoring tools) authenticates to NPM's API using username/password credentials. When 2FA is enabled on an account, the API authentication endpoint cannot complete the 2FA challenge, causing the authentication to fail and return invalid JWTs.

Solution/Workaround:
The standard solution is to create a dedicated service account in NPM specifically for API access:

Create a new user in NPM (e.g., homepage-api@domain.com)
Set password via the Edit User dialog
Do NOT enable TOTP 2FA on this service account
Update Homepage (or other tools) to use these credentials instead

This is a common pattern across many platforms - the primary admin account uses 2FA for security, while service/API accounts remain without interactive authentication challenges.

Recommendation:
It would be helpful to add a note in the TOTP plugin documentation warning users that:

Enabling 2FA on an account will break API integrations that authenticate with that account
Users should create dedicated service accounts without 2FA for API/automation purposes
This is expected behavior, not a bug

This would save users troubleshooting time and prevent confusion when their integrations suddenly stop working after enabling 2FA.

Thanks for the great TOTP enhancement! Just wanted to share this in case it helps other users.

Originally created by @Hackpig1974 on GitHub (Jan 15, 2026). Original GitHub issue: https://github.com/NginxProxyManager/nginx-proxy-manager/issues/5174 Hi, I wanted to share some feedback after implementing TOTP 2FA on my Nginx Proxy Manager instance. This isn't a bug, but rather a documentation enhancement that could help users avoid a common integration issue. Issue Encountered: After enabling TOTP 2FA on my NPM admin account, my Homepage dashboard widget for NPM immediately stopped working and began showing "API Error: Internal Error" in the UI. The NPM container logs showed repeated jwt malformed warnings whenever Homepage attempted to authenticate. Root Cause: Homepage (and likely other dashboard/monitoring tools) authenticates to NPM's API using username/password credentials. When 2FA is enabled on an account, the API authentication endpoint cannot complete the 2FA challenge, causing the authentication to fail and return invalid JWTs. Solution/Workaround: The standard solution is to create a dedicated service account in NPM specifically for API access: Create a new user in NPM (e.g., homepage-api@domain.com) Set password via the Edit User dialog Do NOT enable TOTP 2FA on this service account Update Homepage (or other tools) to use these credentials instead This is a common pattern across many platforms - the primary admin account uses 2FA for security, while service/API accounts remain without interactive authentication challenges. Recommendation: It would be helpful to add a note in the TOTP plugin documentation warning users that: Enabling 2FA on an account will break API integrations that authenticate with that account Users should create dedicated service accounts without 2FA for API/automation purposes This is expected behavior, not a bug This would save users troubleshooting time and prevent confusion when their integrations suddenly stop working after enabling 2FA. Thanks for the great TOTP enhancement! Just wanted to share this in case it helps other users.

kerem added the

enhancement

label

2026-02-26 07:37:55 +03:00

kerem commented

2026-02-26 07:37:56 +03:00

Author

Owner

@piotrfx commented on GitHub (Jan 15, 2026):

@Hackpig1974, thank you for your input. I'm happy that more and more users are finding TOTP useful, as I did when I developed it. There are more issues to be resolved, and when I've got more time during the weekend, I'll sit, read them all again, create a list and hope to find the time to work on them :).

@piotrfx commented on GitHub (Jan 15, 2026): @Hackpig1974, thank you for your input. I'm happy that more and more users are finding TOTP useful, as I did when I developed it. There are more issues to be resolved, and when I've got more time during the weekend, I'll sit, read them all again, create a list and hope to find the time to work on them :).

kerem commented

2026-02-26 07:37:56 +03:00

Author

Owner

@piotrfx commented on GitHub (Jan 15, 2026):

Off the topic, @Hackpig1974 , what do you think about #5138 ? When I deal with the 2FA requests, I can try to develop it next.

@piotrfx commented on GitHub (Jan 15, 2026): Off the topic, @Hackpig1974 , what do you think about #5138 ? When I deal with the 2FA requests, I can try to develop it next.

kerem commented

2026-02-26 07:37:56 +03:00

Author

Owner

@Hackpig1974 commented on GitHub (Jan 15, 2026):

Appreciate you asking for input on this. I think it's a "sounds good on paper" idea, but there's a practical problem that kills it: the container boundary.

Most people run NPM in Docker. When you use something like systeminformation, you're getting container metrics, not host metrics, unless you start bind-mounting /proc and /sys, which gets messy fast and opens up security questions. Users will see container resource limits and think it's showing host health, which would be confusing.

If someone actually needs host-level monitoring, they should just use tools built for that: Netdata, Glances, Homepage, Prometheus, whatever. NPM trying to do it too just creates maintenance burden without really solving the problem.

What might make more sense: focusing on NPM-specific stuff.

Per-proxy metrics: request rates, errors, backend health
Active connections per host
Cert expiry warnings
Nginx worker stats

That's the kind of data people can actually use inside NPM, and it's directly tied to what NPM's managing. If you want to get fancy, add a /metrics endpoint for Prometheus and call it a day.

Anyway, that's my take. Hope that helps.
Good luck with whatever direction you go.

@Hackpig1974 commented on GitHub (Jan 15, 2026): Appreciate you asking for input on this. I think it's a "sounds good on paper" idea, but there's a practical problem that kills it: the container boundary. Most people run NPM in Docker. When you use something like systeminformation, you're getting container metrics, not host metrics, unless you start bind-mounting /proc and /sys, which gets messy fast and opens up security questions. Users will see container resource limits and think it's showing host health, which would be confusing. If someone actually needs host-level monitoring, they should just use tools built for that: Netdata, Glances, Homepage, Prometheus, whatever. NPM trying to do it too just creates maintenance burden without really solving the problem. What might make more sense: focusing on NPM-specific stuff. Per-proxy metrics: request rates, errors, backend health Active connections per host Cert expiry warnings Nginx worker stats That's the kind of data people can actually use inside NPM, and it's directly tied to what NPM's managing. If you want to get fancy, add a /metrics endpoint for Prometheus and call it a day. Anyway, that's my take. Hope that helps. Good luck with whatever direction you go.

kerem commented

2026-02-26 07:37:56 +03:00

Author

Owner

@piotrfx commented on GitHub (Jan 18, 2026):

Thank you, for now I thought I'll have a time to sit on the 2FA, and it has to wait a bit as we have a funeral situation here and no way to optimise my time for 2FA. Hope to have time soon. One of my technicians is coming back in one week from holiday, so I'll start to have more time after that.

@piotrfx commented on GitHub (Jan 18, 2026): Thank you, for now I thought I'll have a time to sit on the 2FA, and it has to wait a bit as we have a funeral situation here and no way to optimise my time for 2FA. Hope to have time soon. One of my technicians is coming back in one week from holiday, so I'll start to have more time after that.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/nginx-proxy-manager-NginxProxyManager#3132

No description provided.

Rows
Columns