NginxProxyManager / NginxProxyManager/nginx-proxy-manager
TOTP Documentation Update - User Awareness
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 34.2k
- Forks
- 3.9k
- Avg merge
- 21h 12m
- Merged PRs (30d)
- 20
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No documentation file or test is named in the issue; start by locating the TOTP plugin documentation in the repository. Add guidance that enabling 2FA can break username/password API integrations and that dedicated service accounts without TOTP are the expected workaround, then verify the documented steps match the described Nginx Proxy Manager flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nginx
- Domain
- api, authentication, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 63/100