Add support for MFA with Duo's Universal Prompt

[0x0fbc]

Overview

This adds support for MFA using Duo's "Universal Prompt".

On March 30th, 2024, the Duo MFA integration that Vaultwarden uses, the 'Traditional Prompt' was end-of-lifed. While Duo's API continues to allow the traditional prompt to be used in some cases, it is entirely unsupported, and it will eventually stop working. Some Vaultwarden users have already begun reporting that their Duo API keys are no longer functional in Vaultwarden. Bitwarden introduced Universal Prompt support in release 2024.2.3 on March 5th.

Duo's Universal Prompt uses the OIDC Authorization Code flow. This flow requires us to pack information about the authentication we want to be prompted for MFA into an authorization request (a JWT signed with a secret key provided by Duo) and send the user to their service, where MFA is performed. The user is then returned to our service with a code that we use to call Duo's API and obtain the result of the MFA. Once we validate the information passed back by the user's client and returned by Duo's service, we can log the user in.

Detailed documentation is located at https://duo.com/docs/oauthapi

The web vault handles receiving the redirection from Duo. It has a 'connector' page responsible for communicating the authorization code back to the user's true client so it can be provided in a call to Vaultwarden's API.

Major additions/changes

• Added a crate, duo_oidc, which implements the Duo Universal Prompt MFA flow.
• Added a database table, twofactor_duo_ctx, migrations, and a model to represent it. This table stores information about in-progress Duo MFA attempts for validation while an authenticating user completes MFA on Duo's service.
• Added an internal task to clear the twofactor_duo_ctx table of incomplete Duo MFA attempts.
• Added a configuration option to globally force Vaultwarden to use the legacy Duo traditional prompt flow instead of the universal prompt.

Specific Review Items

Beyond what you'd normally check, I'd like to highlight a few decisions I made that you should probably consider in your review.

• The OIDC 'nonce' parameter is optional and intended to harden against replay attacks. The best practice is to bind the nonce to a specific authentication attempt using something like an HttpOnly cookie. Cookies don't seem to be an option without significant changes to Vaultwarden, let alone the Bitwarden clients. Instead of not leveraging it, I tried to win back some of the hardening the parameter is intended to provide. I ended up with a strategy where a random nonce is generated, combined with the device_identifier reported by the client, and hashed to produce the OIDC nonce sent to Duo in the authorization request. Then, the device_identifier reported by the user's client when providing the authorization code is hashed with the saved nonce, and the resulting hash is compared to the OIDC nonce Duo reports when we call their API for the MFA result.
• Duo's official client libraries for the Universal Prompt pin hard-coded CA certs from Digicert, SecureTrust, and Amazon. Duo's implementation documentation didn't make any recommendations around pinning certs, and it looks like some of them are root CA certs (the pinning of which is controversial), so I did not implement this.
• Instead of copying or reimplementing the original duo crate's get_duo_keys_email function, which fetches the Duo keys from the database/config for a given user, I set its visibility to pub(crate) and re-used it.

Testing

Tested on the following clients; everything is working well:

• Vaultwarden-patched web vault
• Windows, macOS, and Linux (Flatpak) desktop clients
• Android app (as obtained from Google play)
• iOS app (as obtained from the Apple app store)
• Chrome and Firefox browser extensions

The only major client issue I found was with the unpackaged AppImage Linux desktop client. When authenticating users on desktop clients, the connector in the web vault opens a bitwarden:// link, which my system refused to use the AppImage to open. It looks like the AppImage client either doesn't or can't register itself as the x-scheme-handler for bitwarden, preventing the redirect connector from handing off to the client. It worked fine with the Flatpak packaged Bitwarden client, so I'm chalking it up to my not configuring the AppImage client correctly.

There is also a known issue upstream in the web vault where the redirect connector shows 'successful authentication', does not automatically close, and the JS 'close' button does not work. See bitwarden/clients#8554

I also tested this while running PostgreSQL and MariaDB using the versions packaged in Debian 12; no issues.

Fixes #4529

[BlackDex]

Thanks @0x0fbc.

On first glance it looks like you need to rebase already, but besides that it looks ok. No deep checking done.

The only thing that worries me is the collation for the state. That is going to give issues i think. Especially when the collation was wrong before and people need to update it. That will change it for that column too.

Isn't there a way to not have this as a key? Or less larger in size.
(I have not yet looked into this in a functional way, that is why i ask)

[0x0fbc]

The column size can be scaled back, absolutely.

I set the state and nonce column sizes in postgres and maria so that someone could change the constant dictating the state length to the largest Duo would accept (1024 characters) without having to mess with the database schema. That constant is set to 64 right now, so the large size is only useful to support this specific future proofing case. If you've seen issues with collations/charsets in the past I'd rather not tempt fate, so I'm in favor of just cutting the size down and dropping the overridden character set/collation for the columns in MariaDB. I'll take care of that and rebase when I get a chance later today.

[0x0fbc]

@BlackDex, I reduced the column sizes and removed the collation override I had for MariaDB. I also added the changes suggested by Clippy, did another rustfmt, synced my fork, and rebased.

[quexten]

@0x0fbc

The only major client issue I found was with the unpackaged AppImage Linux desktop client. When authenticating users on desktop clients, the connector in the web vault opens a bitwarden:// link, which my system refused to use the AppImage to open. It looks like the AppImage client either doesn't or can't register itself as the x-scheme-handler for bitwarden, preventing the redirect connector from handing off to the client. It worked fine with the Flatpak packaged Bitwarden client, so I'm chalking it up to my not configuring the AppImage client correctly.

This is an upstream client bug and unrelated to vaultwarden. Both snap and appimage builds have (different) issues with the url handlers at the moment. If I recall correctly from debugging, on AppImage the desktop file does not get created anymore. It needs to be created manually.

[BlackDex]

Overall looks nice, and it works fine too.
Just some small items i saw from my side.

[BlackDex]

btw @0x0fbc, sorry for the delay in testing. Also forgive me for pushing some changes, but i forgot the reqwest changes and those didn't popped up as a merge conflict, so i wanted to fix those.

[0x0fbc]

@BlackDex

No worries! I figured dealing with the beta client API changes over the last month was much more urgent. Thanks for taking care of the reqwest change. I'll get right on your callouts.

[0x0fbc]

@BlackDex

I completed the requested changes and verified that everything is still working fine.

[BlackDex]

Looks good too me.

Seems to work fine during my tests.

[dani-garcia]

Overall LGTM though I haven't had time to test that it works, just some small comments.

One question, seeing as the Duo traditional prompt is end of life and this is the replacement, is there any special case where someone might want to keep using the old iframe variant?

Just trying to think for how long we want to support the iframe version in Vaultwarden. If this is a drop in replacement with no downsides, I imagine we can keep support for the traditional prompt for a couple of versions until all the kinks are ironed out and then drop it.

[BlackDex]

Retesting the old iframe that still works until somewhere in August if I'm correct. Or maybe a bit longer.

[0x0fbc]

Duo hasn't been clear about when they're truly dropping the iframe prompt. For some Duo tenancies (mine included), it's continuing to work; for others, it's not. There's obviously no case to support it after Duo shuts their iframe prompt endpoints down, but I haven't seen any particular date for when they're removing or restricting the endpoints. September 30th, 2024, is the date Duo mentions dropping support for all exceptions that don't have more specific transition dates in the future. I think the Vaultwarden version releasing after that date would be a good time to drop the support.

The special case I had in mind when choosing to leave in the existing iframe prompt functionality is fairly niche. If I'm not mistaken, the iframe prompt works without Vaultwarden needing to communicate with Duo's API directly, but the new OIDC prompt does not. Someone who's deployed Vaultwarden in a restrictive environment may need to set up firewall exceptions or change other configuration to transition. If these changes would be time-consuming for them, I wanted to avoid forcing them to choose between disabling Duo for their Vaultwarden deployment or downgrading to restore their service while they made whatever arrangements they needed to get the OIDC prompt working.

[0x0fbc]

Also, I've synced my fork and rebased.

[dani-garcia]

LGTM! Thanks @0x0fbc for the explanations

[Gerardv514]

Once merged, are these automatically in the testing tag already?

Additionally, I see this version in server diagnostics, is there somewhere here on git I can compare this number to..to know if I’m grabbing the latest test?

[BlackDex]

Once merged it takes mostly less then 1 hour to build all the architectures and create a container.
You can see the status here: https://github.com/dani-garcia/vaultwarden/actions/workflows/release.yml

I just noticed that the alpine builds failed because GitHub killed that container. Those are building right now.

[Gerardv514]

Sorry just realized I didn’t post my version.

Server diagnostics has this version: 1.31.0- .b4b27019

Is there a place here to go to find out if .b4b27019 is latest testing?

**found it under actions. 👊💪

[GeorgeCastanza]

I'm not sure this is complete, b/c Duo is still asking for an update. I can login without 2FA, which is obviously wrong.

I didnt install Duo until after the old Duo was shut down for new users.

[BlackDex]

That is not something we can do, you need to configure that via your duo admin panel.

[Gerardv514]

Works for me. There is something on duo admin side that you have to do. There’s also an option to use new universal prompt there so make sure that is on.