Two-Factor authentication (TOTP)

[nabokihms]

Overview

This pull request implements multi-factor authentication (MFA) support in Dex with an extensible architecture designed for future authenticator types (WebAuthn, etc.).

MFA secrets are stored in UserIdentity objects. Authenticators are defined globally and referenced by clients via mfaChain. A server-wide defaultMFAChain applies to clients without explicit configuration. Authenticators can be scoped to specific connector types (e.g., LDAP, local) to avoid redundancy with providers that have built-in MFA.

Upon first login, users enroll by scanning a QR code; subsequent logins require a TOTP code. The feature requires the DEX_SESSIONS_ENABLED=true feature flag.

Example configuration:

mfa:
  authenticators:
  - id: totp-1
    type: TOTP
    config:
      issuer: "dex"
    connectorTypes:
    - ldap
    - mockCallback
  defaultMFAChain:
  - totp-1

Per-client override:

staticClients:
- id: my-app
  mfaChain:    # overrides defaultMFAChain; use [] to explicitly disable
  - totp-1

What this PR does / why we need it

Enhancing Dex with 2FA adds an additional layer of security, making unauthorized access significantly more difficult. This is particularly valuable for connectors like LDAP and local connectors that do not inherently support 2FA. By implementing 2FA, we align Dex with industry best practices for identity management, meet higher security compliance requirements, and ensure better protection for user data, thereby building greater trust with our users.

Special notes for your reviewer

[nabokihms]

closes #352

[nabokihms]

closes #1547

[nabokihms]

closes #1270

[cnd4]

I'm not a maintainer nor a reviewer so I'm not sure this is the best place to ask this, but would it be possible to display the "textual" code below the QR code?

This is useful when you can't scan the QR code, for example when your TOTP application is directly on your computer.

(Edit: typo)

[lanord]

Do we know if we are going to see this merge in the near future ? This would be a great feature to see deployed. As more and more security requirement ask for 2FA on auth provider.

[nabokihms]

@sambonbonne good addition, thanks!
@lanord I am willing to merge it this year after figuring out some API nuances.

[Kludex]

@nabokihms Is there a way to fund the work in this PR?

[shaohme]

Nice feature to have indeed.

Have you considered supporting slapo-otp(5) when you started the project?

[p-alexander]

Hi, is TOTP still planned for this year? My team would like to use this amazing feature with local connectors. 🙏

A small update: I've taken a look at the PR and noticed that totp.Generate is always called with an empty secret option and generally it is good to have it randomized, but for simpler use cases (e.g. in-memory storage), it might be worth supporting a static secret in order to keep offlineSessions.TOTP idempotent between restarts. Kind of similar to how static passwords are already handled in Dex.

[braginini]

Would love to see this one merged as we are planning to integrate Dex in NetBird.

[jjzazuet]

Super cool feature right here. Any chances of merging? Thanks!

[nabokihms]

For all waiting the feature. We are working now on the proposal, which will make this PR be merged in the future.

You can see the progress here #4560

[sagikazarmark]

I had some comments, but it probably needs a closer look to see if they are valid, hence just comments.

[sagikazarmark]

I know we don't do that in other places, but this is a security sensitive form that would probably benefit from CSRF.

[nabokihms]

There is a kind of CSRF protection using HMAC. It's generated server-side with a secret key and validated on submission, so a forged request from an external origin would fail verification. Same principle as a synchronizer token, just delivered via the URL rather than a hidden form field.

We use it all over critical forms. I can open an issue to add a different CSRF mechanism, but not in the scope of this PR.

[nabokihms]

No API to recover mfa and no recovery codes for now, but I still think it is ok to be merged now. We will add the API later.