[PM-23409] feat: Add client certificate authentication (mTLS) support for self-hosted environments

[jalenfran]

🎟️ Tracking

• GitHub Discussion: Add mTLS Support Discussion
• Feature Request: Implementing mTLS in the Bitwarden apps

📔 Objective

This PR implements client certificate authentication (mTLS) support for iOS app when connecting to self-hosted Bitwarden environments that require client certificates.

Key Features:

• PKCS#12 (.p12/.pfx) certificate import with password support
• Secure certificate storage independent of user login
• mTLS HTTP client integration for server authentication
• Certificate management UI integrated into self-hosted server configuration
• Comprehensive error handling and user feedback

Technical Implementation:

• ClientCertificateConfiguration model for certificate data and metadata
• ClientCertificateService for secure certificate management operations
• CertificateHTTPClient with URLSession delegate for mTLS authentication
• Global certificate storage using existing app settings infrastructure
• SwiftUI interface for certificate import, display, and removal

This enables users to authenticate with self-hosted Bitwarden servers that require client certificates for enhanced security.

📸 Screenshots

⏰ Reminders before review

• Contributor guidelines followed
• All formatters and local linters executed and passed
• Written new unit and / or integration tests where applicable
• Protected functional changes with optionality (feature flags) - N/A: Feature is opt-in via certificate import
• Used internationalization (i18n) for all UI strings
• CI builds passed
• Communicated to DevOps any deployment requirements - N/A: No deployment changes needed
• Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

Key Areas for Review:

• 🔐 Security implementation of certificate storage and mTLS authentication
• 🎨 UI/UX integration with existing self-hosted configuration flow
• 📝 Error handling for various certificate import scenarios
• ⚡ Performance impact of certificate validation and HTTP client changes
• 🧪 Test coverage for certificate management workflows

Files to Focus On:

• ClientCertificateService.swift - Core certificate management logic
• CertificateHTTPClient.swift - mTLS HTTP client implementation
• SelfHostedView.swift - UI integration and user experience
• StateService.swift & AppSettingsStore.swift - Secure storage implementation

• 👍 (:+1:) or similar for great changes
• 📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
• ❓ (:question:) for questions
• 🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
• 🎨 (:art:) for suggestions / improvements
• ❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
• 🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
• ⛏ (:pick:) for minor or nitpick changes

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ jalenfran
❌ matt-livefront
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[bitwarden-bot]

Thank you for your contribution! We've added this to our internal Community PR board for review.
ID: PM-23409
Link: https://bitwarden.atlassian.net/browse/PM-23409

Details on our contribution process can be found here: https://contributing.bitwarden.com/contributing/pull-requests/community-pr-process.

[KeenMaron]

Any updates on this implementation?

[jalenfran]

Any updates on this implementation?

Just waiting on any comments

[maxkpower]

Hey @jalenfran, thanks a lot for your PR! Please excuse the long silence, an automation issue unfortunately kept this ticket off our review board. We do want to support mTLS and will be reviewing the PR shortly.

[xXxNIKIxXx]

@maxkpower do you have any Updates on this. I would love to fully entroll Bitwarden but without mTLS it is to insecure. Is there and ETA or new Status? Probably soon to be in the IOS Beta?

[edgenative]

Adding a bump here.

Would love to see this functionality landed

[Nexulo]

Hey jalenfran, thanks a lot for your PR! Please excuse the long silence, an automation issue unfortunately kept this ticket off our review board. We do want to support mTLS and will be reviewing the PR shortly.

@maxkpower May I ask if there are any updates on the implementation of this feature?

[AvallaSD]

@maxkpower Is there any updates on this feature? Really looking forward to use this feature
@jalenfran May be they're waiting for you to resolve conflict?

[jalenfran]

I fixed the merge conflicts.

[AvallaSD]

@maxkpower Ready to release now?)

[KuyomieKurama]

@maxkpower do you have any Updates on this.

[xXxNIKIxXx]

@matt-livefront any Updates on this? You are the one assigned as reviewer.

[Nexulo]

It’s been several weeks now and this PR is still waiting without any visible progress. The implementation seems to be complete, tested, and the community is clearly interested. Could we please get an update on what exactly is blocking this from moving forward?

[KeenMaron]

It’s been several weeks now and this PR is still waiting without any visible progress. The implementation seems to be complete, tested, and the community is clearly interested. Could we please get an update on what exactly is blocking this from moving forward?

I don’t want to be pessimistic, but at the moment it seems something is going wrong with Bitwarden’s development. For weeks we’ve suddenly had so many issues with the browser extensions. It’s confusing how such buggy versions could be released to the public. They also don’t do any rollback. instead they leave the broken extensions in place, trying to fix the issues while customers have to wait and continue using buggy versions for so long. Sorry for this post, but this is my subjective feeling at the moment. Something just isn’t right… I hope everything will get back on track again soon :(

[zhuqf]

can owner rewiew this, upgrade to iOS26 recently and client cerfiticate is even tricky, system level confgure profiles is not work for bitwarden client, we need this feature

[sapfeer0k]

We are eagerly waiting this to be merged and deployed to app store. Very much needed feature.

[xXxNIKIxXx]

I think this is not going to be merged in the near Future. This PR is opened since 6 Months at this Point. All other Clients are capable of MTLs besides IOS. Bitwarden Self states they want to implement this feature but there is no progress. Even after asking over and over no one of the Bitwarden team is responding.

[sapfeer0k]

I think this is not going to be merged in the near Future. This PR is opened since 6 Months at this Point. All other Clients are capable of MTLs besides IOS. Bitwarden Self states they want to implement this feature but there is no progress. Even after asking over and over no one of the Bitwarden team is responding.

Thanks for the information. Could you suggest any other iOS client for bitwarden-compatible protocol server behind mTLS?

[edgenative]

@vvolkgang you were involved in bitwarden/android#4486 over on the android side for this. Any help you can offer here to move this one along...? it's been stuck a while

[EuKeck]

What is the status of this feature? Is there still one "requested change" open or is the implementation finished? Thanks for the good work so far!

[jalenfran]

What is the status of this feature? Is there still one "requested change" open or is the implementation finished? Thanks for the good work so far!

The last comment I got on Friday was "Thanks @jalenfran! I need to do some additional testing next week, but this is looking to be in a good spot."

[matt-livefront]

@jalenfran Just a heads up, I added a few commits to build on your changes here: mostly filling in some tests, aligning a few things with our conventions, and trimming a bit of extra functionality to keep things simpler.

[github-actions]

Checkmarx One – Scan Summary & Details – 7180ecf8-3ab6-4a25-b316-0760c9b2c061

Great job! No new security vulnerabilities introduced in this pull request

[jalenfran]

@jalenfran Just a heads up, I added a few commits to build on your changes here: mostly filling in some tests, aligning a few things with our conventions, and trimming a bit of extra functionality to keep things simpler.

Hi Matt, I was taking a look and I really appreciate the quickness and helping me get this through!

[codecov]

Codecov Report

❌ Patch coverage is 87.14653% with 150 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.95%. Comparing base (02573ca) to head (1049464).

Files with missing lines	Patch %	Lines
...e/Platform/Services/ClientCertificateService.swift	60.18%	43 Missing ⚠️
...ed/UI/Auth/Landing/SelfHosted/SelfHostedView.swift	63.71%	41 Missing ⚠️
.../UI/Auth/Landing/SelfHosted/SelfHostedAction.swift	48.71%	20 Missing ⚠️
...Core/Platform/Services/CertificateHTTPClient.swift	75.00%	12 Missing ⚠️
.../Auth/Landing/SelfHosted/SelfHostedProcessor.swift	91.73%	10 Missing ⚠️
...d/Core/Auth/Services/KeychainRepositoryTests.swift	94.01%	7 Missing ⚠️
.../Services/TestHelpers/MockKeychainRepository.swift	80.00%	5 Missing ⚠️
.../Landing/SelfHosted/SelfHostedProcessorTests.swift	98.14%	4 Missing ⚠️
...ed/Core/Platform/Services/EnvironmentService.swift	0.00%	3 Missing ⚠️
...Platform/Services/CertificateHTTPClientTests.swift	97.58%	3 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1720      +/-   ##
==========================================
- Coverage   87.09%   85.95%   -1.14%     
==========================================
  Files        1859     2092     +233     
  Lines      164348   180223   +15875     
==========================================
+ Hits       143136   154915   +11779     
- Misses      21212    25308    +4096     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[matt-livefront]

@jalenfran Just a heads up, I added a few commits to build on your changes here: mostly filling in some tests, aligning a few things with our conventions, and trimming a bit of extra functionality to keep things simpler.

Hi Matt, I was taking a look and I really appreciate the quickness and helping me get this through!

You bet! Thank you for all of your work on putting this PR together and working through the changes!