MSC1998: Two-Factor Authentication Providers by cyphar · Pull Request #1998 · matrix-org/matrix-spec-proposals

cyphar · 2019-05-14T04:50:56Z

Rendered

Implements: #1997
Signed-off-by: Aleksa Sarai cyphar@cyphar.com

SCT Stuff:

FCP closure tickyboxes

No MSC checklist.

turt2live · 2019-05-14T06:40:06Z

@cyphar I've flagged this as ready to review. If that's incorrect, please let me know.

I haven't ready the whole thing yet, but the detail is massively appreciated!

cyphar · 2019-05-14T07:15:10Z

I hope I didn't go overboard, I ended up copying the structure of the actual spec docs but maybe I should've been a bit more terse?

turt2live

looking pretty good so far!

changelogs/client_server/newsfragments/1998.feature

proposals/1998-two-factor-providers.md

In order to avoid overly-complicating the initial implementation we just provide a basic TOTP authentication flow and a recovery code flow. Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>

cyphar · 2019-06-12T15:28:32Z

@turt2live I've made the corrections you mentioned. One thing with using DELETE is that now it makes slightly less semantic sense to disable only some of the two-factor providers (then again, POST /disable is quite a bit uglier). If only there was a DELETE-PATCH. 😉

turt2live · 2020-01-09T16:20:47Z

proposals/1998-two-factor-providers.md

+
+  * `GET /_matrix/client/r0/account/twoFactor` to get the current state of enabled providers for the account.
+  * `POST /_matrix/client/r0/account/twoFactor` to configure providers.
+  * `DELETE /_matrix/client/r0/account/twoFactor` to disable providers.


turns out I can't read, as vdh points out these should be two_factor: #1998 (comment)

turt2live · 2020-01-13T18:04:25Z

@dainnilsson please move your comments to threads on the diff so people can reply.

dainnilsson · 2020-01-14T09:12:16Z

proposals/1998-two-factor-providers.md

+### `POST /_matrix/client/r0/account/twoFactor`
+
+This endpoint allows the client to enable (or reset) a two-factor provider. In
+order to avoid users locking themselves out of their accounts, servers should
+enable `m.login.two-factor.recovery` if it is not already enabled for the user.


Some 2FA credential variants will require more round-trips to set up, for example WebAuthn (https://www.w3.org/TR/webauthn/). Does this endpoint allow for that? For example, when setting up a credential the client needs to first get a challenge, and then provide a response based on that challenge to the server. Potentially other protocols might require even more round-trips to complete.

Likewise for TOTP, it's common that as part of credential registration the server requires a valid OTP for the new credential before activating it, to make sure the client has correctly received and supports the parameters used. Perhaps this should be part of the m.login.two-factor.totp registration flow?

Perhaps I'm misunderstanding WebAuthn (and I'd love to hear more about it -- I've only interacted with the first-gen FIDO stuff very superficially), isn't it intended to replace passwords as one of the factors of authentication (rather than being an alternative MFA mechanism)? If so, then adding a new login flow (separate to this proposal) would seem to be a better path forward to have WebAuthn supported in Matrix.

But I think you're right that the current design of Matrix's login flow system doesn't allow for multiple ping-pongs between clients and servers. You'd need to create separate login stages (which seems to me to be a little bit scary since forgetting to include a login flow step means that the authentication would succeed if I understand how it works correctly).

Perhaps this should be part of the m.login.two-factor.totp registration flow?

Yes it probably should be, and all MFA registration flows I can think of work that way...

WebAuthn can be used in several ways. Also as single factor. But I believe most common is to use instead of SMS or TOTP codes as second factor.

dainnilsson · 2020-01-14T09:14:41Z

proposals/1998-two-factor-providers.md

+### `POST /_matrix/client/r0/account/twoFactor`
+
+This endpoint allows the client to enable (or reset) a two-factor provider. In
+order to avoid users locking themselves out of their accounts, servers should
+enable `m.login.two-factor.recovery` if it is not already enabled for the user.


One other consideration is that a single 2FA provider may need to support multiple credentials. While I think this might be possible under the current API by leveraging the provider params dict, it does overlay a lot of functionality on a single endpoint. For any given provider we not only have "enable/reset", but also "add credential" and "remove (specific) credential". I'm not sure if this warrants additional endpoints or not.

dainnilsson · 2020-01-14T09:15:28Z

@dainnilsson please move your comments to threads on the diff so people can reply.

Done!

warriorzz · 2022-04-23T15:14:40Z

Any updates on this? I would like to have this merged as I would love to use WebAuthn as second factor when authenticating.

shoqvalue · 2022-05-29T22:15:29Z

Same question.

Any updates on this? I would like to have this merged as I would love to use WebAuthn as second factor when authenticating.

cyphar · 2022-05-30T06:00:46Z

I haven't had much time to review this after I first posted it. It is still a feature I'd like (I still use Matrix daily and wish we'd have 2FA) but it seems that WebAuthn would require a more flexible design than the pretty basic one I came up with here -- this feature would almost certainly turn out better if it's handled by someone with more experience dealing with authentication.

ShadowJonathan · 2022-09-30T16:20:53Z

Isn't this work effectively overshadowed by the OIDC initiative the matrix foundation is currently following?

From what I know, it'd essentially move authentication to somewhere else, which then has to implement webauthn instead. (The focus being that, by default, a server will use matrix-authentication-service as an internal OIDC provider, which already has an issue open about this: matrix-org/matrix-authentication-service#18)

richvdh · 2022-10-03T10:06:46Z

yes, OIDC would obviate the need for this. For now we'll keep it open until we are fully committed to OIDC.

zincentimeter · 2024-07-09T02:01:57Z

Is there any follow-up on this feature?

clokep · 2025-07-09T16:16:37Z

With the adoption of OAuth 2.0 based authentication API (MSC3861) I don't think the SCT will plan to further improve the Matrix-specific authentication APIs. With that in mind I'm going to put this up for closure. If the author wishes to close this they can do so directly at any point.

@mscbot fcp close

mscbot · 2025-07-09T16:16:41Z

cyphar · 2025-07-09T20:59:07Z

Yeah it seems this is obviated by OIDC, though it's not actually supported yet. Closing this 6-year-old PR...

turt2live · 2025-07-09T21:33:46Z

@mscbot fcp cancel

cyphar changed the title ~~proposals: add draft MSC1997 proposal~~ MSC1997: Two-Factor Authentication Providers May 14, 2019

cyphar force-pushed the msc1997-totp-two-factor branch from db2fa0d to bf3176e Compare May 14, 2019 04:53

cyphar mentioned this pull request May 14, 2019

Two-Factor Authentication Login (m.login.2fa.totp flow) #1997

Closed

4 tasks

turt2live added proposal A matrix spec change proposal proposal-in-review labels May 14, 2019

turt2live changed the title ~~MSC1997: Two-Factor Authentication Providers~~ MSC1998: Two-Factor Authentication Providers May 14, 2019

cyphar force-pushed the msc1997-totp-two-factor branch from bf3176e to 218eef6 Compare May 14, 2019 07:14

cyphar force-pushed the msc1997-totp-two-factor branch from 218eef6 to 88b3854 Compare May 14, 2019 07:20

turt2live self-requested a review June 12, 2019 01:45

turt2live reviewed Jun 12, 2019

View reviewed changes

cyphar added 2 commits June 13, 2019 01:21

MSC1998: Two-Factor Authentication Providers

2791a86

In order to avoid overly-complicating the initial implementation we just provide a basic TOTP authentication flow and a recovery code flow. Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>

fixup! MSC1998: Two-Factor Authentication Providers

97d9605

cyphar force-pushed the msc1997-totp-two-factor branch from 88b3854 to 97d9605 Compare June 12, 2019 15:27

This was referenced Jan 9, 2020

2FA for logins element-hq/element-meta#345

Closed

Support FIDO U2F authentication matrix-org/synapse#2460

Open

turt2live reviewed Jan 9, 2020

View reviewed changes

dainnilsson reviewed Jan 14, 2020

View reviewed changes

turt2live added the kind:core MSC which is critical to the protocol's success label Apr 20, 2020

clokep mentioned this pull request Jan 4, 2021

Support TOTP 2FA for accounts matrix-org/synapse#9009

Closed

beercanchicken mentioned this pull request Feb 28, 2021

2-Step Verification element-hq/element-android#2933

Open

clokep mentioned this pull request Mar 1, 2021

2-Step Verification matrix-org/synapse#9509

Closed

turt2live added the needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. label Jun 8, 2021

turt2live force-pushed the old_master branch from e895827 to dca99ee Compare August 30, 2021 22:34

turt2live removed the proposal-in-review label May 5, 2022

villepeh mentioned this pull request Jul 11, 2022

Allow multiple values for SSO attributes matrix-org/synapse#13238

Open

clokep mentioned this pull request Jul 10, 2023

background how to open Google Authenticator matrix-org/synapse#15894

Closed

Ahwxorg mentioned this pull request Jul 19, 2024

request: add 2FA element-hq/synapse#17459

Closed

mscbot added proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period. disposition-close labels Jul 9, 2025

turt2live added this to Spec Core Team Workflow Jul 9, 2025

github-project-automation bot moved this to Tracking for review in Spec Core Team Workflow Jul 9, 2025

turt2live moved this from Tracking for review to Ready for FCP ticks in Spec Core Team Workflow Jul 9, 2025

cyphar closed this Jul 9, 2025

cyphar deleted the msc1997-totp-two-factor branch July 9, 2025 20:59

turt2live added the obsolete A proposal which has been overtaken by other proposals label Jul 9, 2025

mscbot added proposal-in-review and removed proposed-final-comment-period Currently awaiting signoff of a majority of team members in order to enter the final comment period. disposition-close labels Jul 9, 2025

turt2live removed the proposal-in-review label Jul 9, 2025

turt2live moved this from Ready for FCP ticks to Merged in Spec Core Team Workflow Jul 9, 2025

Conversation

cyphar commented May 14, 2019 • edited by turt2live Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

turt2live commented May 14, 2019

Uh oh!

cyphar commented May 14, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

turt2live left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cyphar commented Jun 12, 2019

Uh oh!

turt2live Jan 9, 2020

Choose a reason for hiding this comment

Uh oh!

turt2live commented Jan 13, 2020

Uh oh!

dainnilsson Jan 14, 2020

Choose a reason for hiding this comment

Uh oh!

cyphar Jan 24, 2020

Choose a reason for hiding this comment

Uh oh!

ptman Jul 10, 2020

Choose a reason for hiding this comment

Uh oh!

dainnilsson Jan 14, 2020

Choose a reason for hiding this comment

Uh oh!

dainnilsson commented Jan 14, 2020

Uh oh!

warriorzz commented Apr 23, 2022

Uh oh!

shoqvalue commented May 29, 2022

Uh oh!

cyphar commented May 30, 2022

Uh oh!

ShadowJonathan commented Sep 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

richvdh commented Oct 3, 2022

Uh oh!

zincentimeter commented Jul 9, 2024

Uh oh!

clokep commented Jul 9, 2025

Uh oh!

mscbot commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cyphar commented Jul 9, 2025

Uh oh!

turt2live commented Jul 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

cyphar commented May 14, 2019 •

edited by turt2live

Loading

cyphar commented May 14, 2019 •

edited

Loading

ShadowJonathan commented Sep 30, 2022 •

edited

Loading

mscbot commented Jul 9, 2025 •

edited

Loading