mTLS Client Authentication support needed

[po1xi548Rysh8BH6]

Describe the feature

I would like very much to be able to use the companion app with an mtls guarded reverse proxy.

Use cases

I'm not sure how much to write here. I am not asking for a novel feature, rather feature parity with the android version.

Examples

No response

Anything else?

No response

[gerootech]

Yes, please reference this discussion:

https://community.home-assistant.io/t/secure-communication-channel-for-ios-app/785129

[po1xi548Rysh8BH6]

Thank you, I had no idea that there was already so much momentum behind this.

[simposiummm]

Yes, please reference this discussion:

https://community.home-assistant.io/t/secure-communication-channel-for-ios-app/785129

Voted

[dijitali]

And for context of anyone else coming across this:

• merged for Android here: TLS Client Authentication Support android#2526
• rejected for iOS here: Allow supplying client certificates iOS#2144

[xfallme]

I was looking into this as well, and there is a new draft PR for iOS: home-assistant/iOS#4261

[bgoncal]

I have submitted a beta to TestFlight, Apple is currently reviewing it.

It should show up as 2026.3.0

Please, be aware that it's considered still "experimental", it's not properly tested across OS versions, it does not work on Apple Watch and it may present unexpected behavior for widgets and shortcuts.

The initial goal is to test and collect feedback.

[hkdce]

I tested again and found that verify_if_given is a red herring.
Haven't figured out what is wrong yet. Since iOS Safari has no problem presenting the cert.

[hkdce]

I generated another p12 without the intermediate cert subject=/O=My Home Lab/CN=My Internal Intermediate CA. It works.

Since the full p12 (with the intermediate cert) file is working in iOS Safari (which contains the leaf, intermediate & root), but not in the app. And a client cert signed directly by the the same root cert works, there is a chance the code isn't handling the intermediate cert right, at least with privately managed root CA.

[mloveys]

@bgoncal This is awesome! I tested and was able to get this working. One thing I am curious about, would it be potentially better to let the keychain handle it as that may reduce potential maintenance burden? I noticed it was asking me to import the cert whereas if I use safari/chrome it'll prompt from my keychain and request my password to allow the app access

[bgoncal]

From what I researched there is no way in iOS to inherit OS level client certificates in third party apps, it needs to be handled per app. If you find any docs saying otherwise please share with me.
Interesting that chrome can access it though, not sure if it is something strict to browser apps or something that I missing, but still, I couldn't find docs that point to that

[hkdce]

Interesting that chrome can access it though, not sure if it is something strict to browser apps or something that I missing, but still, I couldn't find docs that point to that

In my experience Chrome cannot access the system cert store. Only Safari can.

[Natio]

First of all thanks a lot for the work!
I just installed the beta. At first it did not work but then I figured it was because my p12 did not have the full trust chain (I self-host step-ca). I regenerated the p12 including the root and intermediate certificates and now it connects without issues.

[JB5678]

Thankyou, this is great!
Latest iPhone IOS. Working well with Cloudflare issued client certificate and mTLS rule. Haven't noticed any issues with base app, notifications or widgets.

[KNGP14]

Thank you for the great work!
I can confirm that its perfectly working using Cloudflares mTLS Client certificates.
iPhone 13 with iOS 26.3.0

[matheusfaustino]

Same here. Just tested and it worked without issues in a pre-configured server. The only thing was that in order to work I had close and reopen the app.

Iphone 15 pro / 26.3

[ehmke]

Same here. However, for some reason I had to delete the "server" in the app and connect again to make it work. Also I am experiencing the random crashes, e.g. when switching back to an already running HA app.

[tuxtof]

The mTLS part works perfectly on my side, very nice 👍🏻 ,
i just had 3 apps crash since this morning , i have pushed the crash log

[gerootech]

How to get the beta app??

[adriankirchner]

https://companion.home-assistant.io/app/ios/beta

[corneels]

Beta is full.

[baurmatt]

Thanks for implement mTLS support! :) I was able to get it working with Traefik.

tls:
  options:
    mtls-required:
      clientAuth:
        clientAuthType: RequireAndVerifyClientCert
        caFiles:
          - /pki/rootCA.pem

http:
  routers:
    homeassistant-mtls:
      rule: "Host(`homeassistant.example.org`)"
      entryPoints:
        - websecure
      service: homeassistant
      tls:
        options: mtls-required@file

[bgoncal]

From what I researched there is no way in iOS to inherit OS level client certificates in third party apps, it needs to be handled per app. If you find any docs saying otherwise please share with me.

[baurmatt]

@bgoncal While the actual app still works, I found that notifications containing HLS stream don't. The notification is send like this:

  - action: notify.mobile_app_iphone_von_matthias
    data:
      title: Saugroboter Vacum
      message: >-
        Die Reinigung wurde um {{ now().strftime('%-H:%M') }} Uhr erfolgreich
        abgeschlossen.
      data:
        image: /api/camera_proxy/camera.vacum_camera
        entity_id: camera.pippilotta_camera
        priority: high
        url: /lovelace/
        clickAction: /lovelace/
        channel: Valetudo Success

Error message of the iOS notification is: HLS stream not available. URLSessionTask failed with error: The server ha.example.org requires a client certificate.

Let me know if you require further information to debug this!

[bgoncal]

Thanks for letting me know, mTLS is not fully done yet, please keep reporting these specific cases

[bgoncal]

@baurmatt Can you test the new testflight build? If the issue persists please open an issue as described here: https://github.com/orgs/home-assistant/discussions/1078#discussioncomment-15994444

[baurmatt]

Still existing :/ See home-assistant/iOS#4417

[tanihisadev]

Glad to see this functionality becoming available! Appreciate the work being done on it.

Managed to upload the cert and upon hitting refresh the app crashed (sent a crash report). Force closed the HA app and upon re-opening was able to connect as normal.

Will update this post/add another if I have any more feedback.

[bgoncal]

There is a new issue template that you can use to report issues about the experimental mTLS support, please use it so we group all issues and begin addressing those.
https://github.com/home-assistant/iOS/issues

[fschlag]

I can confirm it works with HAProxy (3.0.11-1+deb13u2) using mTLS (= verify required) together with Let’s Encrypt HTTPS. It runs with separate internal and external URLs, with mTLS enabled only on the external one.

Note

App version: 2026.3.0 (2026.1826)
iOS 26.3, iPhone 15 Pro Max

haproxy.cfg snippet

frontend test
	bind 192.168.xx.yy:80
	bind 192.168.xx.yy:443 ssl crt /etc/ssl/private/mytld.crt verify required ca-file /etc/ssl/private/ca/intermediate-ca.crt ca-verify-file /etc/ssl/private/ca/root-ca.crt
	http-request set-header X-SSL-Client-CN %[ssl_c_s_dn(cn)]
	http-request redirect scheme https unless { ssl_fc }
	default_backend homeassistant

backend homeassistant
	server server1 192.168.xx.yx:8123

[fuomag9]

I tested this with my own project and it works perfectly! https://github.com/fuomag9/caddy-proxy-manager

[hkdce]

Is anyone using a client certificate with a private root CA and an intermediate cert?

Could you share which certificates you install in the system stores and which ones you include in the P12 file?

[snsefive]

Using beta, all working great regarding the iOS App. Cloudflare tunnel.
Apple Watch app isolated (with LTE and iPhone power off) not working for me. Don't know if there are plans to include the mTLS support in the Watch native app.

Thanks!

edit: didnt' read the source PR. It says Apple watch still pending. Got it. (home-assistant/iOS#4362)

[dhruvb14google]

iOS App works great, MacOS app is missing button to add cert but the release notes say it support mTLS so I assume its just an accidental overlook.

home-assistant/iOS#4449

[bgoncal]

I think it is related to the check added "isTestFlight", for some reason it behaves differently on mac app, I will have a look

[MrGotAB]

Thank you for adding mTLS support to the iOS app. This is a feature I urgently need in order to properly secure my environment.

I have two quick questions:

Every time I check the beta, it appears to be full. Is there any possibility to expand the beta or to join it in another way?

Is there already an estimated timeline for the official release of mTLS support on iOS?

[bgoncal]

It's on track to arrive in the next public release as a beta/labs feature