feat: add support for Android user-installed certificates by jfly · Pull Request #19830 · immich-app/immich

jfly · 2025-07-09T01:12:08Z

Description

This is part of #15230.

Frustratingly, Dart/Flutter ignores user-installed certificates. Working around this requires rooting your Android device to install certificates as "system" certs, which isn't an option for everyone.

This is a known issue with Dart, see
dart-lang/sdk#50435 and
flutter/flutter#56607 for details.

I have read through
#15230 and #13555, and I understand that switching to
cronnet_http would also resolve this. While that may be the correct long-term approach, it looks like there are a lot of network codepaths in Immich, and as I know basically nothing about Dart, nor Flutter, nor Immich's codebase, I thought this would be a better short term approach.

This depends on my fork of
johnstef99/flutter_user_certificates_android, which I've sent a PR for here
johnstef99/flutter_user_certificates_android#2. If y'all don't like the supply chain implications of that, I'm happy to inline the implementation here instead.

How Has This Been Tested?

I have step-ca and DNS configured so that immich.mm resolves to an immich server with a certificate issued by my step-ca certificate authority. I've installed that certificate authority as a user-installed certificate on my Android phone.

With a fresh install of immich, I can configure https://immich.mm as a server
After logging in, I can view photos, upload photos and video, and play video.

Screenshots (if appropriate)

The help text on this option is no longer true. I'd suggest that we deprecate it in favor of encouraging people to add certificates to their OS:

Checklist:

I have performed a self-review of my own code
I have made corresponding changes to the documentation if applicable
I have no unrelated changes in the PR.
I have confirmed that any new dependencies are strictly necessary. Strictly? No. See my offer above about to inline the implementation if that's preferred.
I have written tests for new code (if applicable)
I have followed naming conventions/patterns in the surrounding code
All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

bo0tzz · 2025-07-09T09:17:51Z

mobile/android/app/src/main/res/xml/network_security_config.xml

+  <base-config>
+    <trust-anchors>
+      <certificates src="system"/>
+      <certificates src="user"/>


There's no way to make this opt-in, right?

I don't know, but everything I know about android development I learned in the last week while researching this issue.

mobile/pubspec.yaml

shenlong-tanwen · 2025-07-21T14:23:28Z

@jfly Hey, Thanks a lot for working on this. However, if we are to merge this in, rather than deprecating the existing "Allow Self signed certificates" toggle, we could just remove all the custom verification logic all together. We don't need a lot of different codepath to address the same issue. However, this would mean that we would also need to test this exhaustively to make sure it does not break anything from the current setup. So things like:

mTLS
Self-signed certificates
Custom CAs

For all cases, we'd need to test both the dart side of things and the native side of things. Most network calls are from the dart side. Video player, Asset download are made from native side and we should validate these as well. If we are to remove the self signed toggle, we've to make sure everything works on iOS as well.

You could just inline all the changes. We are migrating to using pigeon for all message passing between flutter and the platform side, so you can add an API to fetch the certificates and load it in the dart's SecurityContext. We might also need some documentation change to inform users about installing certificates to the OS cert store, rather than loading it in the app like they used to.

The core team currently has got it's hands full with working towards the stable release. I know this is a significant undertaking for your free time, but if you can get this properly tested after removing the existing toggle and adding in your changes, we can happily merge this in. If you need help setting up specific test scenarios or access to different certificate setups, let us know - we can coordinate with the community to help test various configurations.

mobile/android/app/src/main/res/xml/network_security_config.xml

jfly · 2025-07-21T16:53:16Z

shenlong-tanwen · 2025-07-21T17:20:31Z

Sure, I'm happy to take this on. I've converted my understanding of your requirements into a checklist below.

This is perfect! Thanks a lot for taking this on. As far the documentation, we can discuss this during the release of this PR. But yes, a callout in the release note might just do. It is also probably worth testing the migration from the older version with the setting on with a certificate to the new one without the toggle. Please feel free to ping me here or over discord if you need any help with the implementation or testing

I ran into this while testing out <immich-app#19830>. When I add, change, or remove a client certificate under Immich's advanced settings, the change wouldn't take effect until some mysterious point in the future. For example: 1. Add a client certificate. It doesn't get used. 2. Remove certificate. *Now* the client certificate from step 1) is used. 3. Restart application. Now no client certificate is used. This all boils down to some missing `await`s. The user would change the cert, and we'd start asynchronously saving it to the store, and while the save is still happening, [`HttpSSLOptions` pulls the "old" value out of `SSLClientCertStoreVal`](https://github.com/immich-app/immich/blob/v1.136.0/mobile/lib/utils/http_ssl_options.dart#L30). With the appropriate `await`s, this behaves much more sanely.

I ran into this while testing out <#19830>. When I add, change, or remove a client certificate under Immich's advanced settings, the change wouldn't take effect until some mysterious point in the future. For example: 1. Add a client certificate. It doesn't get used. 2. Remove certificate. *Now* the client certificate from step 1) is used. 3. Restart application. Now no client certificate is used. This all boils down to some missing `await`s. The user would change the cert, and we'd start asynchronously saving it to the store, and while the save is still happening, [`HttpSSLOptions` pulls the "old" value out of `SSLClientCertStoreVal`](https://github.com/immich-app/immich/blob/v1.136.0/mobile/lib/utils/http_ssl_options.dart#L30). With the appropriate `await`s, this behaves much more sanely.

jfly · 2025-07-25T07:31:49Z

@shenlong-tanwen, I'm ready for you to take another look at this PR. I've updated my checklist with what I have done and not done.

Notably, with these changes, self-signed certificates work, but Android only lets you install them if they have the X.509v3 CA:true flag. You get a really confusing message saying a "private key is required to install a certificate". See https://android.stackexchange.com/questions/237141/how-to-get-android-11-to-trust-a-user-root-ca-without-a-private-key for details.

So, we need to decide what to do here. A couple proposals:

Just make the change. Folks who want to self-sign their own certificates can do so, but they should be running a proper certificate authority. The existing feature (where we don't validate certs at all) is dangerous and should go away.
Keep the "Allow self-signed SSL certificates" feature around, but reword it so it's clear that you should not be using it if you're running your own CA.
- I still think it's a dangerous feature and should go away. Ideally we'd tell people it's deprecated and will be removed [at some point].

richardlt · 2025-07-25T09:36:04Z

Personally I agree with your second point, since this feature here will not strictly replace the existing flag it could be a breaking change for some users to remove it. I'm also not sure about the options for IOS users to install custom CA.
Maybe another proposal could be to keep it for now and to improve it later. For example in some applications if you try to reach a server with a self signed cert you have to approve it directly in the app and then this app will remember your choice so if the cert change you'll have to approve it again.

jfly · 2025-07-25T15:56:18Z

I'm also not sure about the options for IOS users to install custom CA.

This works fine. My wife is on iOS and has our custom CA installed on her phone, and immich works great.

For example in some applications if you try to reach a server with a self signed cert you have to approve it directly in the app and then this app will remember your choice so if the cert change you'll have to approve it again.

Yeah, that would be a ssh-style TOFU scheme. I don't have the same safety concerns, but that's a whole bunch of code that I don't really see the value in anyone writing, nor having the core immich team maintain.

IMO, it would be better for immich to take an opinionated stance and say that anyone running their immich server without "universally trusted" certs is required to be have that cert chained off of a root of trust with CA:true (aka: running their own certificate authority). Anyone who is doing this is likely going to run into the same issue with other self hosted services, anyways. Baking the trust into your OS is simplest for both the app developers and the users.

Of course I am happy to do whatever the core team needs to get this PR landed. IMO, the best solution would be to rebrand the existing option as dangerous and mark it deprecated, with the intent to remove it before the stable release.

jfly · 2025-12-16T15:29:47Z

Thanks, @shenlong-tanwen.

But we have to keep this on hold till the next major release since this is still a breaking change

What if keep the existing option, but reword it a little bit (as I suggested here: #19830 (comment)).

before the next major release

Do you mean "after" the next major release?

denysvitali · 2026-01-03T07:30:15Z

FYI: #22768 supports user-provided certificates and fixes all the problems mentioned in #15230 by using the same client everywhere.

The idea here is to use OkHttp, which supports user certs on Android.

jfly · 2026-01-13T09:47:11Z

@denysvitali, agreed that using a single client with support for Android user-installed certificates sounds like a better long term solution.

I did just rebase this PR and dropped the breaking change. Instead, I've just marked the existing "Allow self-signed SSL certificates" feature as deprecated. @shenlong-tanwen, I'd really love to get this PR merged. I've been daily driving it since July 2025 and have had no issues, other than my immich android client getting progressively more out of date.

shenlong-tanwen

Sorry that this got shelved for so long. Can you add the pigeon generator command to the mise.toml file in the mobile app directory as well?

The other parts looks good and we can actually merge this sooner now that we have proper backward support for current installs. Apologies again and Thanks a lot for working on this

This is part of immich-app#15230. Frustratingly, Dart/Flutter ignores user-installed certificates. Working around this requires rooting your Android device to install certificates as "system" certs, which isn't an option for everyone. This is a known issue with Dart, see dart-lang/sdk#50435 and flutter/flutter#56607 for details. I have read through <immich-app#15230> and <immich-app#13555>, and I understand that switching to [`cronnet_http`](immich-app#14335 (comment)) would also resolve this. While that may be the correct long-term approach, it looks like there are [a lot of network codepaths](immich-app#15230 (comment)) in Immich, and as I know basically nothing about Dart, nor Flutter, nor Immich's codebase, I thought this would be a better short term approach. For the record: the important code here is copied from my fork of `johnstef99/flutter_user_certificates_android`. See this PR for more context: <johnstef99/flutter_user_certificates_android#2>.

This is unnecessary now that we support user-installed certificates on Android. Users should be adding certs to their system instead, which will work in more places (such as browsers), and won't blindly trust the cert.

jfly · 2026-01-19T14:53:38Z

Can you add the pigeon generator command to the mise.toml file in the mobile app directory as well?

@shenlong-tanwen, done. It's unclear to me how this relates to the pigeon target in mobile/makefile. I've just followed the existing patterns.

mertalev · 2026-01-26T03:49:35Z

I'd love to move away from the Dart HttpClient entirely after measuring just how much worse it is compared to the native clients. To that end, I'd prefer a solution that moves away from HttpClient rather than depending on it.

denysvitali · 2026-01-27T21:27:57Z

@mertalev My proposed solution uses OkHttp on Android and solve the issues mentioned here

mertalev · 2026-01-28T04:18:52Z

@mertalev My proposed solution uses OkHttp on Android and solve the issues mentioned here

I think OkHttp is the right direction here. I have a WIP branch that handles certs app-wide for both platforms. It creates a shared client on the platform side and constructs the cupertino_http/ok_http client from its pointer on the Dart side. This would mean even all Flutter isolates and engines use the same client.

jfly · 2026-01-28T15:22:24Z

I don't care what networking stack we use. OkHttp sounds great if it can also do proper handling of user-installed certificates on Android. I just want to get back to installing Immich from f-droid, rather than infrequently rebasing this branch (and dealing with conflicts).

My preference would be to land this PR as is so certificate handling on android can get un-broken. I'd be happy for @denysvitali to resurrect their work in #22768 and delete the hack I've added here. I don't think landing this PR increases the effort to switch to OkHttp.

@shenlong-tanwen, WDYT?

mertalev · 2026-01-29T00:19:22Z

I totally get that you want to fix this sooner rather than later and I agree! I'm just already working on a more complete solution, so it seems unnecessary to merge this code if it's going to be superseded soon.

jfly · 2026-01-29T02:08:52Z

Sorry, I'm getting little frustrated here. This wouldn't be the first time this PR has had to wait for a networking refactor you've done (#19830 (comment)). This PR exists, is reviewed and ready to land, and fixes a real issue in the wild. It also deprecates a very dangerous feature that IMO shouldn't exist. Why not merge as is? I'll still cheer the day you delete this hack!

mertalev · 2026-01-29T04:01:21Z

Sorry for the frustration. This wouldn't be merged until 2.6, by which point I expect the whole app to be switched over to native clients. Merging this PR implies testing it only to revert it right after, which in turn means a larger diff for others in the team to review. It's honestly not a good use of time.

As a team, we have our own planning and this is a task I've already picked up, so please rest assured that I'll take care of it.

jfly · 2026-01-29T04:20:09Z

Ok, I appreciate the timeline.

richardlt · 2026-01-29T20:00:57Z

What a surprise to see this PR closed after all the discussions and changes made to remove any breaking changes.
Hope that we will finally have that fix/feature soon in 2.6 🙏🏼

jfly · 2026-01-29T20:40:52Z

@mertalev, could you share an issue/PR I can subscribe to so I know how your OkHttp work is going? Thanks, and good luck!

mertalev · 2026-01-30T07:42:26Z

@mertalev, could you share an issue/PR I can subscribe to so I know how your OkHttp work is going? Thanks, and good luck!

It still needs some work before it's ready for a PR, but I'll ping you when it's up :)

jfly · 2026-02-02T23:57:34Z

For anyone else who wants to follow along, @mertalev and I are discussing this over in #25802

github-actions bot added the 📱mobile label Jul 9, 2025

bo0tzz added the changelog:enhancement label Jul 9, 2025

bo0tzz changed the title ~~Add support for Android user-installed certificates~~ feat: add support for Android user-installed certificates Jul 9, 2025

bo0tzz reviewed Jul 9, 2025

View reviewed changes

jfly force-pushed the support-android-user-certs branch 2 times, most recently from 8546274 to 01f0a57 Compare July 9, 2025 18:21

mmomjian mentioned this pull request Jul 20, 2025

feat(mobile): load user certificates for Android #20033

Closed

8 tasks

shenlong-tanwen reviewed Jul 21, 2025

View reviewed changes

mobile/android/app/src/main/res/xml/network_security_config.xml Outdated Show resolved Hide resolved

jfly mentioned this pull request Jul 21, 2025

Add support for Android user-installed certificates UnicornsOnLSD/finamp#1276

Merged

jfly force-pushed the support-android-user-certs branch 2 times, most recently from 5182425 to c6419f1 Compare July 24, 2025 20:38

jfly mentioned this pull request Jul 25, 2025

fix: add missing awaits when changing client certificate #20189

Merged

jfly force-pushed the support-android-user-certs branch from 0925f1e to 187a465 Compare July 25, 2025 01:28

jfly force-pushed the support-android-user-certs branch from 187a465 to 813adfc Compare July 25, 2025 01:30

jfly force-pushed the support-android-user-certs branch 4 times, most recently from db8d15e to b396b38 Compare July 25, 2025 06:11

jfly force-pushed the support-android-user-certs branch from b396b38 to 5e45a35 Compare July 28, 2025 23:38

jfly force-pushed the support-android-user-certs branch from f24922b to 0cfc278 Compare January 13, 2026 09:41

jfly marked this pull request as ready for review January 13, 2026 09:50

jfly force-pushed the support-android-user-certs branch 3 times, most recently from 382e892 to 6fbe850 Compare January 17, 2026 19:46

shenlong-tanwen reviewed Jan 19, 2026

View reviewed changes

jfly added 2 commits January 19, 2026 06:52

chore: deprecate the "Allow self-signed SSL certificates" feature

d9c9ff5

This is unnecessary now that we support user-installed certificates on Android. Users should be adding certs to their system instead, which will work in more places (such as browsers), and won't blindly trust the cert.

jfly force-pushed the support-android-user-certs branch from 6fbe850 to d9c9ff5 Compare January 19, 2026 14:52

jfly requested a review from shenlong-tanwen January 19, 2026 14:53

shenlong-tanwen added changelog:enhancement and removed changelog:breaking-change labels Jan 19, 2026

jfly mentioned this pull request Jan 25, 2026

feat(mobile): native clients #21459

Merged

jfly closed this Jan 29, 2026

Uh oh!

Conversation

jfly commented Jul 9, 2025

Description

How Has This Been Tested?

Screenshots (if appropriate)

Checklist:

Uh oh!

bo0tzz Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

jfly Jul 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shenlong-tanwen commented Jul 21, 2025

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

shenlong-tanwen commented Jul 21, 2025

Uh oh!

jfly commented Jul 25, 2025

Uh oh!

richardlt commented Jul 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

jfly commented Dec 16, 2025

Uh oh!

denysvitali commented Jan 3, 2026

Uh oh!

jfly commented Jan 13, 2026

Uh oh!

shenlong-tanwen left a comment

Choose a reason for hiding this comment

Uh oh!

jfly commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mertalev commented Jan 26, 2026

Uh oh!

denysvitali commented Jan 27, 2026

Uh oh!

mertalev commented Jan 28, 2026

Uh oh!

jfly commented Jan 28, 2026

Uh oh!

mertalev commented Jan 29, 2026

Uh oh!

jfly commented Jan 29, 2026

Uh oh!

mertalev commented Jan 29, 2026

Uh oh!

jfly commented Jan 29, 2026

Uh oh!

richardlt commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jfly commented Jan 29, 2026

Uh oh!

mertalev commented Jan 30, 2026

Uh oh!

jfly commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jfly commented Jul 21, 2025 •

edited

Loading

jfly commented Jul 25, 2025 •

edited

Loading

jfly commented Jan 19, 2026 •

edited

Loading

richardlt commented Jan 29, 2026 •

edited

Loading