[PM-39573] mTLS client certificate authentication fails when the reverse proxy trusts only the root CA

[jalenfran]

Steps To Reproduce

1. Set up a self-hosted server behind a reverse proxy that requires mutual TLS (client certificate authentication).
2. Configure the proxy to trust only the root CA — i.e. the client-CA bundle contains the root certificate but not the intermediate CA.
3. Issue a client certificate whose chain is leaf → intermediate → root, and export it as a .p12 containing the leaf, its private key, and the intermediate.
4. In the iOS app, set the self-hosted server URL and import the .p12 client certificate.
5. Attempt to log in / connect to the server.

Expected Result

The app authenticates successfully, the same way a web browser and the Android app do with the identical client certificate and reverse-proxy configuration.

Actual Result

The TLS handshake fails and the app shows:

This is not a recognized Bitwarden server. You may need to check with your provider or update your server.

Disabling the client-certificate requirement on the proxy (or adding the intermediate CA to the proxy's client-CA bundle) lets login succeed, confirming the failure is specific to the mTLS handshake.

Screenshots or Videos

No response

Additional Context

Root cause: When answering the client-certificate TLS challenge, the app presents only the leaf certificate and not the intermediate chain (the credential is built with no additional certificates). When the reverse proxy trusts only the root CA, it cannot build leaf → intermediate → root from the leaf alone, so it rejects the handshake.

• Browsers and the Android app send the entire chain from the .p12, which is why the same certificate and server work there but the iOS app fails.
• This affects both API requests and vault item icon loading, since both go through the client-certificate challenge.
• Workaround: add the intermediate CA(s) to the reverse proxy's client-CA bundle (e.g. nginx ssl_client_certificate) so the server can complete the chain itself.

The misleading "not a recognized Bitwarden server" message also sends users toward checking the server URL rather than the certificate chain, which makes this harder to diagnose.

Build Version

2026.5.1 (also affects earlier versions that support client-certificate authentication)

What server are you connecting to?

Self-host

Self-host Server Version

Reproduces with a reverse proxy in front of a self-hosted server (verified against Vaultwarden 1.36.0); applies to any self-host setup that terminates mTLS at a proxy trusting only the root CA.

Environment Details

• Device: iPhone (any)
• OS Version: iOS 18+

Issue Tracking Info

• I understand that work is tracked outside of Github. A PR will be linked to this issue should one be opened to address it, but Bitwarden doesn't use fields like "assigned", "milestone", or "project" to track progress.

[bitwarden-bot]

Thank you for your report! We've added this to our internal board for review.
ID: PM-39573

[jtodddd]

Hi there,

This has been escalated for further investigation. If you have more information that can help us, please add it below.

Thanks!

[jalenfran]

Hi there,

This has been escalated for further investigation. If you have more information that can help us, please add it below.

Thanks!

Hi, I have already made a PR implementing the fix. I was the main contributor behind the mTLS features. You can find the PR here #2833.

[forkrails]

@jalenfran I appreciate your work on mTLS. It's certainly useful for some deployments. But for smaller teams, mTLS is a significant burden to manage. Not to mention the user experience is annoying when needing to install certs manually.

Custom headers are usually much simpler, on all fronts. Each client app simply needs to append a header key and value to each request, which the user sets pre-auth. There is a feature request here for it.

Is there any chance bitwarden may consider implementing a custom header approach alongside mTLS?

[jalenfran]

@jalenfran I appreciate your work on mTLS. It's certainly useful for some deployments. But for smaller teams, mTLS is a significant burden to manage. Not to mention the user experience is annoying when needing to install certs manually.

Custom headers are usually much simpler, on all fronts. Each client app simply needs to append a header key and value to each request, which the user sets pre-auth. There is a feature request here for it.

Is there any chance bitwarden may consider implementing a custom header approach alongside mTLS?

Hello @forkrails I can take a look!

[forkrails]

Sounds great! If it helps, both immich and opencloud ios apps use this custom header pattern, and it works very well.

[jalenfran]

Sounds great! If it helps, both immich and opencloud ios apps use this custom header pattern, and it works very well.

Awesome! I use Immich on my personal server. It will definitely help me to see their patterns.

[jalenfran]

Sounds great! If it helps, both immich and opencloud ios apps use this custom header pattern, and it works very well.

I decided to spend my night implementing your request 😄! I have opened and tested a PR here #2925. Let me know if you have any other suggestions!

[forkrails]

Dude you're awesome! Can't wait to see this make it in. I really think custom headers are the way forward, I hate mTLS with such a passion lol

Now to give some context, the reason custom headers are needed is because these mobile/extension clients either don't do browser based auth, or they don't persist and send out the auth cookie for example from CF access or oauth2 proxy, etc.

You can't really enforce these custom headers per client or by client type. Its all or nothing. So this feature can't really be used until the other clients gain the same functionality.

Do you have any familiarity with the extension/desktop app, or who we can loop in to add this functionality there as well?

[jalenfran]

Dude you're awesome! Can't wait to see this make it in. I really think custom headers are the way forward, I hate mTLS with such a passion lol

Now to give some context, the reason custom headers are needed is because these mobile/extension clients either don't do browser based auth, or they don't persist and send out the auth cookie for example from CF access or oauth2 proxy, etc.

You can't really enforce these custom headers per client or by client type. Its all or nothing. So this feature can't really be used until the other clients gain the same functionality.

Do you have any familiarity with the extension/desktop app, or who we can loop in to add this functionality there as well?

Thank you! I will do a deep dive on the clients repo this weekend. I have a pretty mixed range of experience, so it might be fun. I will keep you posted. Funny thing is I'm not a maintainer or anything, just someone who contributes some code when I can😄.