fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 by cthach · Pull Request #57909 · gravitational/teleport

cthach · 2025-08-14T16:33:16Z

What?

Fixes the cluster client library and Apps connections handler so that they return a friendly error message when MFA is required and the user has no MFA devices enrolled. This is consistent with how the rest of the product handles this edge case (e.g., SSH, Kubernetes, Desktop, etc).

changelog: Improve error message when a User without any MFA devices enrolled attempts to access a resource that requires MFA.

Why?

Resolves the following issues:

After testing the SSH, Desktop, Kubernetes, DB, etc product features, it was found that only CLIs and Apps features do not properly handle this edge case.

Once this PR is merged, the product should handle this MFA-UX edge case in a consistent way

Screenshots

When accessing an SSH host through tsh and the user does not have a MFA device enrolled:

When accessing an App through the UI and the user does not have a MFA device enrolled:

How was this tested?

Deployed Teleport with GitHub SSO integration to replicate a non-local User without a MFA device enrolled
Configured Teleport to require Session MFA for all connections
Verified connecting via ./tsh ssh root@Mac using the GitHub SSO user produces the expected error
Verified connecting via the Web UI using the GitHub SSO user produces the expected error

TODOs

Fix tsh in v19
Test for whether backports are needed for prior releases of tsh
Fix web UI (RCA'd, see notes, awaiting feedback)
Test client tctl admin actions
Create backport PRs after this PR is merged

Backport?

Yes, testing in progress and I'll fill this affected versions matrix as I figure out the extent of this bug. Backport PRs will be created and linked for all affected versions.

	v19-dev	v18.1.4	v17.7.1	v16.5.9
v19-dev	🐛	🐛	🙈	🙈
v18.1.4	🙈	🐛	🐛	🙈
v17.7.1	🙈	🙈	🐛	🐛
v16.5.9	🙈	🙈	🙈	🐛

Legend

X axis: Teleport client version
Y axis: Teleport server version

Intersection meanings:

❓ = Untested, results coming 🔜
🐛 = Bug affects this Teleport server and client versions
☺️ = Bug does not affect this Teleport server and client versions
🙈 = Server-client versions are not supported so will not be tested

…has no devices enrolled Signed-off-by: Chris Thach <chris.thach@goteleport.com>

cthach · 2025-08-15T19:35:24Z

+			text = `Access to this app requires multi-factor authentication (MFA), but user has no MFA devices; see Account Settings in the Web UI or use 'tsh mfa add' to register MFA devices.
+
+See https://goteleport.com/docs/zero-trust-access/access-controls/guides/per-session-mfa/ for help.


Open to feedback on how this should be worded. I did try to follow the existing pattern established but wanted to provide a little more detail. Copied from

teleport/lib/auth/authclient/clt.go

Line 86 in c71b3f9

Message: "MFA is required to access this resource but user has no MFA devices; see Account Settings in the Web UI or use 'tsh mfa add' to register MFA devices",

for more consistency in product messaging.

What do you think about unifying all of our error messaging for this scenario? Right now tsh will result in MFA is required to access this resource but user has no MFA devices; see Account Settings in the Web UI or use 'tsh mfa add' to register MFA devices and the web ui will give you some form of only WebAuthn and SSO MFA methods are supported on the web terminal, please register a supported mfa method to connect to this server.

Maybe something similar to the following?

Multi-factor authentication is required to access this resource but the current user has no MFA devices enrolled; see Account Settings in the Web UI or use 'tsh mfa add' to register an MFA device.

@zmb3 any thoughts on this?

Love the the suggestion! Will unify messaging

Updated in 2d9c589. I also updated the screenshots in the PR description. I opted to reuse the custom error ErrNoMFADevices instead of copy-pasting the same message throughout.

I also opted to wrap the error with additional context in the case of accessing via the Web UI since we only support a subset of MFA methods that a user might have added (WebAuthn and SSO MFA).

Thoughts?

I think I'd remove the error wrapping to keep the error messaging more concise and consistent.

Yes, I agree!

Added in #57909 and updated screenshots in PR desc

…irements are not met upon connection to an App Signed-off-by: Chris Thach <chris.thach@goteleport.com>

Signed-off-by: Chris Thach <chris.thach@goteleport.com>

rosstimothy · 2025-08-18T20:11:55Z

+			text = `Multi-factor authentication (MFA) is required to access this resource but the current user has no supported MFA devices enrolled; see Account Settings in the Web UI or use 'tsh mfa add' to register an MFA device.
+
+See https://goteleport.com/docs/zero-trust-access/access-controls/guides/per-session-mfa/ for help.
+`


For consistency with the other error messages?

Suggested change

text = `Multi-factor authentication (MFA) is required to access this resource but the current user has no supported MFA devices enrolled; see Account Settings in the Web UI or use 'tsh mfa add' to register an MFA device.

See https://goteleport.com/docs/zero-trust-access/access-controls/guides/per-session-mfa/ for help.

`

text = authclient.ErrNoMFADevices.Error()

Done in #57909

Signed-off-by: Chris Thach <chris.thach@goteleport.com>

… body assertion Signed-off-by: Chris Thach <chris.thach@goteleport.com>

cthach · 2025-08-18T21:45:10Z

@rosstimothy @nklaassen

I appreciate the reviews! I just pushed a commit cb8c839 updating the unit tests after you submitted your approvals. It's passing locally for me.

Can you please give that look before we merge?

backport-bot-workflows · 2025-08-18T23:06:33Z

@cthach See the table below for backport results.

Branch	Result
branch/v16	Failed
branch/v17	Create PR
branch/v18	Create PR

…has no devices enrolled 🐛 (#57909) * fix: return friendly error message when MFA is required but the user has no devices enrolled Signed-off-by: Chris Thach <chris.thach@goteleport.com> * fix: improve error handling to provide clearer feedback when MFA requirements are not met upon connection to an App Signed-off-by: Chris Thach <chris.thach@goteleport.com> * refactor: make error messages consistent Signed-off-by: Chris Thach <chris.thach@goteleport.com> * refactor: remove wrapped message Signed-off-by: Chris Thach <chris.thach@goteleport.com> * test: add test for enrolled MFA device and update trusted device resp body assertion Signed-off-by: Chris Thach <chris.thach@goteleport.com> --------- Signed-off-by: Chris Thach <chris.thach@goteleport.com>

…has no devices enrolled 🐛 (#57909) (#58045) * fix: return friendly error message when MFA is required but the user has no devices enrolled * fix: improve error handling to provide clearer feedback when MFA requirements are not met upon connection to an App * refactor: make error messages consistent * refactor: remove wrapped message * test: add test for enrolled MFA device and update trusted device resp body assertion --------- Signed-off-by: Chris Thach <chris.thach@goteleport.com>

…has no devices enrolled 🐛 (#57909) (#58042) * fix: return friendly error message when MFA is required but the user has no devices enrolled * fix: improve error handling to provide clearer feedback when MFA requirements are not met upon connection to an App * refactor: make error messages consistent * refactor: remove wrapped message * test: add test for enrolled MFA device and update trusted device resp body assertion --------- Signed-off-by: Chris Thach <chris.thach@goteleport.com>

…has no devices enrolled 🐛 (#57909) (#58044) * fix: return friendly error message when MFA is required but the user has no devices enrolled * fix: improve error handling to provide clearer feedback when MFA requirements are not met upon connection to an App * refactor: make error messages consistent * refactor: remove wrapped message * test: add test for enrolled MFA device and update trusted device resp body assertion --------- Signed-off-by: Chris Thach <chris.thach@goteleport.com>

fix: return friendly error message when MFA is required but the user …

fe0d42f

…has no devices enrolled Signed-off-by: Chris Thach <chris.thach@goteleport.com>

cthach self-assigned this Aug 14, 2025

cthach added the backport-required label Aug 14, 2025

cthach changed the title ~~fix: return friendly error message when MFA is required but the user has no devices enrolled~~ fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 Aug 14, 2025

cthach mentioned this pull request Aug 14, 2025

Lack of MFA device should prompt user to add MFA when required #57114

Closed

cthach force-pushed the cthach/issue57114 branch from e292a62 to fe0d42f Compare August 14, 2025 21:13

Merge remote-tracking branch 'origin/master' into cthach/issue57114

d56b0ed

cthach commented Aug 15, 2025

View reviewed changes

cthach added backport/branch/v16 backport/branch/v17 backport/branch/v18 labels Aug 15, 2025

fix: improve error handling to provide clearer feedback when MFA requ…

99802bb

…irements are not met upon connection to an App Signed-off-by: Chris Thach <chris.thach@goteleport.com>

cthach force-pushed the cthach/issue57114 branch from 6d5cc83 to 99802bb Compare August 15, 2025 22:16

Merge branch 'master' into cthach/issue57114

e10b1a9

cthach marked this pull request as ready for review August 15, 2025 22:16

github-actions bot requested review from gzdunek and smallinsky August 15, 2025 22:17

github-actions bot added application-access size/sm labels Aug 15, 2025

cthach requested review from Joerger, marcoandredinis, nklaassen and rosstimothy August 15, 2025 22:17

refactor: make error messages consistent

2d9c589

Signed-off-by: Chris Thach <chris.thach@goteleport.com>

rosstimothy reviewed Aug 18, 2025

View reviewed changes

refactor: remove wrapped message

06b4927

Signed-off-by: Chris Thach <chris.thach@goteleport.com>

rosstimothy approved these changes Aug 18, 2025

View reviewed changes

nklaassen approved these changes Aug 18, 2025

View reviewed changes

public-teleport-github-review-bot bot removed request for Joerger and marcoandredinis August 18, 2025 21:39

public-teleport-github-review-bot bot removed request for gzdunek and smallinsky August 18, 2025 21:39

cthach and others added 2 commits August 18, 2025 17:42

test: add test for enrolled MFA device and update trusted device resp…

cb8c839

… body assertion Signed-off-by: Chris Thach <chris.thach@goteleport.com>

Merge branch 'master' into cthach/issue57114

8080486

cthach requested review from nklaassen and rosstimothy August 18, 2025 21:53

nklaassen approved these changes Aug 18, 2025

View reviewed changes

cthach added this pull request to the merge queue Aug 18, 2025

Merged via the queue into master with commit 33f9213 Aug 18, 2025
40 checks passed

cthach deleted the cthach/issue57114 branch August 18, 2025 23:03

cthach mentioned this pull request Aug 19, 2025

[v18] fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 #58042

Merged

cthach mentioned this pull request Aug 19, 2025

[v17] fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 #58044

Merged

This was referenced Aug 19, 2025

[v16] fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 #58045

Merged

Improve error message when user does not have an MFA device registered #48328

Closed

cthach mentioned this pull request Sep 4, 2025

Propagate app access MFA error to the UI #55357

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 #57909

fix: Return friendly error message when MFA is required but the user has no devices enrolled 🐛 #57909
cthach merged 8 commits intomasterfrom
cthach/issue57114

cthach commented Aug 14, 2025 •

edited

Loading

Uh oh!

cthach Aug 15, 2025

Uh oh!

rosstimothy Aug 18, 2025

Uh oh!

zmb3 Aug 18, 2025

Uh oh!

cthach Aug 18, 2025

Uh oh!

cthach Aug 18, 2025

Uh oh!

rosstimothy Aug 18, 2025

Uh oh!

cthach Aug 18, 2025 •

edited

Loading

Uh oh!

rosstimothy Aug 18, 2025

Uh oh!

cthach Aug 18, 2025

Uh oh!

cthach commented Aug 18, 2025 •

edited

Loading

Uh oh!

Uh oh!

backport-bot-workflows bot commented Aug 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		text = `Access to this app requires multi-factor authentication (MFA), but user has no MFA devices; see Account Settings in the Web UI or use 'tsh mfa add' to register MFA devices.

		See https://goteleport.com/docs/zero-trust-access/access-controls/guides/per-session-mfa/ for help.

Conversation

cthach commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

Screenshots

How was this tested?

TODOs

Backport?

Legend

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cthach Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cthach commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

backport-bot-workflows bot commented Aug 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cthach commented Aug 14, 2025 •

edited

Loading

cthach Aug 18, 2025 •

edited

Loading

cthach commented Aug 18, 2025 •

edited

Loading