NginxProxyManager / NginxProxyManager/nginx-proxy-manager

TOTP Documentation Update - User Awareness

Open Beginner friendly
#5,174 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.