Client Certificates (mTLS) for Home Assistant: Let Only Your Own Devices In

What a client certificate is

Every HTTPS connection already uses a certificate: the server shows one to your browser to prove that it really is your address. Mutual TLS (mTLS) adds the opposite direction. The browser or app also shows a certificate, and the server lets the connection through only if that certificate was issued by an authority it trusts.

With Pluggie, that authority is created by the Pluggie app on your own hardware. You issue one certificate per device — your phone, your tablet, your laptop — and install it there once. A device without one of your certificates gets a "Client Certificate Required" page instead of the Home Assistant login.

The certificate authority, including its private key, is stored only in the Pluggie app's private data folder. It is never sent to Pluggie. The private key of each device certificate exists only inside the downloaded .p12 file, which is protected by a one-time password.

Why use it — and when not to

A client certificate does not replace anything — it extends the options you already have. Geo blocking and IP ranges work well when you know where your visitors come from. They cannot be tight when your phone connects from mobile data or changing Wi-Fi networks, where the IP address changes all the time and may even be in another country while you travel. A client certificate belongs to the device, not to its address, so it fits exactly there. Keep your Pluggie access rules, and keep Home Assistant's own login, two-factor authentication and IP banning. A client certificate adds a layer in front of them:

• Nobody else even reaches the login page — not even from an allowed country or IP range. Password guessing, credential stuffing and automated scanners stop at the certificate check.
• A future bug in a login page matters less. If a vulnerability is ever found in Home Assistant or a custom integration, an attacker without your certificate cannot get to it through your Pluggie address.
• Each device can be cut off on its own. Lost a phone? Revoke its certificate and everything else keeps working.

It is optional, and it is not for every setup. Be aware of the trade-offs before you switch to Enforce:

• Every device needs its certificate installed once. Without client certificates, your Pluggie address works from any browser with nothing to install. With them, a borrowed laptop or a friend's phone will not get in.
• Cloud services cannot present a certificate. If something on the internet calls your Pluggie address directly — a webhook from an online service, a voice assistant integration you set up by hand — those requests are rejected in Enforce mode.
• Your local network is never affected. At home, Home Assistant and the Pluggie panel keep working on their local addresses exactly as before. The check only applies to your Pluggie address.

Before you start

You need Pluggie 0.8.0 or newer, either the Pluggie app in Home Assistant or the Pluggie Docker container. The settings are in the same place in both:

Everything in this card takes effect immediately. There is no need to click Save Settings.

The three modes

Enforce cannot be selected straight away. It becomes available only after at least one device has connected with its certificate in Test mode — a safety net so that you cannot lock out every device by accident.

Step by step

Installing the certificate on your devices

The file is a standard PKCS#12 (.p12) file with your device certificate and its private key. Menu names below are from current versions of each system; they can differ slightly between versions and manufacturers.

iPhone and iPad (Safari)

1. Get the .p12 file onto the iPhone or iPad, for example with AirDrop or by saving it to the Files app, and tap it. iOS reports that a profile was downloaded.
2. Open the Settings app and tap Profile Downloaded near the top.
3. Tap Install, enter your device passcode, then enter the certificate password and finish the installation. The profile is shown as not signed; that is expected for a certificate you created yourself.
4. Open your Pluggie address in Safari.

A downloaded profile has to be installed within 8 minutes, otherwise iOS deletes it and you need to tap the file again. If Stolen Device Protection is on and you are away from a familiar location, iOS asks you to turn it off before installing a profile. You can remove the certificate later in Settings → General → VPN & Device Management.

Certificates installed this way are used by Safari. Other browsers on iPhone and iPad may not be able to use them. The Home Assistant Companion app keeps its own copy — see the next section.

Home Assistant Companion app

iPhone and iPad: the Home Assistant Companion app supports client certificates itself, and version 2026.9.1 or newer asks for one when your server requires it. The app does not use the certificate installed in Settings; it imports the .p12 file directly:

• When you add a server that requires a certificate, the app shows Client Certificate Required. Tap Select Certificate File, pick the .p12 file, enter the password under Certificate Password and tap Import.
• If the server is already set up in the app, open it in the app's settings and use Client Certificate → Import Certificate. If you skip this, the app shows Certificate required once Enforce is on, with an Import certificate button.
• If the certificate has been revoked or replaced, the app shows Certificate rejected and lets you import a new one.

Do this in Test mode first, so you can see the device's Last seen time before anything is blocked. The same certificate can be used by both Safari and the app on the same iPhone.

Android: the Android Companion app uses the certificates installed on the phone. Install the file as described in the Android section; the app asks you to choose the certificate when your server requests one. A Wear OS watch cannot use certificates installed on the phone — it asks for the certificate file during its own setup.

Android

Android requires a screen lock — a PIN, pattern or password — before it lets you install a certificate. Set one up first if the phone has none.

1. Download the file to the phone. Copy or download the .p12 file to the phone.
2. Install it. Open Settings, search for "certificate" and tap Install a certificate → VPN & app user certificate. Pick the file and enter the password that was shown when the certificate was issued. (If search does not find it: Security & privacy → More security settings → Encryption & credentials.)
3. Choose the certificate when asked. Open your Pluggie address in Chrome, or open the Home Assistant app. When Android asks which certificate to use, choose the one you just installed. Firefox for Android can use installed certificates too (since version 138).

Installed certificates are listed under Encryption & credentials → User credentials, where you can also remove them.

macOS

1. Open Keychain Access (search for it in Spotlight).
2. Choose File → Import Items, select the .p12 file and keep login as the destination keychain.
3. Enter the certificate password.
4. Open your Pluggie address. Safari and Chrome use the certificate from the keychain and ask which certificate to use; macOS may also ask for permission to use the key — allow it.

Windows 11

1. Double-click the .p12 file. The Certificate Import Wizard opens.
2. Select Current User as the store location and continue; the file is already selected.
3. Enter the certificate password and keep the default import options.
4. Keep the automatic certificate store selection and click Finish.
5. Windows may show a security warning about installing a certificate authority named Pluggie client CA followed by your address. That is the authority your own Pluggie app created; confirm it.
6. Open your Pluggie address in Edge or Chrome and choose the certificate when asked.

Firefox and Linux

On Windows and macOS, Firefox offers certificates from the operating system automatically (since Firefox 90), so the steps above are enough. On Linux, import the file in Firefox itself: Settings → Privacy & Security → Certificates → View Certificates… → Your Certificates → Import…, then enter the certificate password. Other browsers on Linux have their own certificate settings.

Revoking a device

If a phone is lost or a laptop is sold, find the device in the list and click Revoke, then Confirm revoke. Its certificate stops working immediately for new connections; all other devices keep working. The device stays in the list with a Revoked badge, and you can add a new device with the same name.

• A connection that is already open at that moment — for example the Companion app keeping a live connection — can stay open until it ends. Restart the Pluggie app if you need to cut it off at once.
• While Enforce is on, you cannot revoke the last device that has connected. Switch to Test or Off first; this prevents you from locking yourself out.
• Delete all certificates at the bottom of the card removes the certificate authority and every device certificate and turns client certificates off. Type RESET and click Delete all. Every certificate you installed so far stops working for good.

Device certificates are valid for 5 years. The Expires column shows the date for each one; when it comes close, add the device again and revoke the old entry.

Changing your Pluggie address

If you change your Pluggie address, nothing has to be reissued. The Pluggie app picks up the new address without a restart, usually within a minute, and keeps the mode and all device certificates. Update the address in the Companion app and your bookmarks; the browser or app may ask once more which certificate to use.

Locked out?

At home: switch it off locally

Client certificates never apply to your local network or to the Pluggie panel. Open Pluggie from the Home Assistant sidebar on your local network — or the Pluggie admin UI on your Docker host — and select Off. Your Pluggie address works from any browser again immediately.

Away from home: turn it off from your Pluggie account

If you are travelling and none of your devices has a working certificate, you can turn client certificates off from my.pluggie.net. This requires two-factor authentication on your Pluggie account, so set it up before you need it: Settings → Two-Factor Authentication → Enable 2FA. When you enable it, Pluggie shows ten one-time recovery codes — save them somewhere safe, away from your phone.

1. Sign in at my.pluggie.net and open Connections. The badge next to each connection shows the current mode: mTLS, mTLS test or mTLS off.
2. Click the button Emergency: turn off client certificates next to the connection.
3. Enter a code from your authenticator app or one of your recovery codes and click Turn off client certificates.

The request reaches the Pluggie app through its existing connection, usually within seconds to about a minute. Connections then shows "Client certificates turned off", and the Pluggie panel shows a Client certificates turned off notice so you know it happened. If the Pluggie app is offline at that moment, the request waits and is applied when it connects again, for up to 7 days.

Lost access to your Pluggie account too?

If you have lost both your password and your two-factor authentication, the Pluggie app itself can prove that the connection is yours:

1. Contact support@pluggie.net. Support gives you a one-time code.
2. On your local network, open the Pluggie panel (or the admin UI of the Docker container) → Show Advanced Settings → Account Recovery.
3. Enter the code under Code from Pluggie support and click Verify.
4. The panel shows a link, once. It lets you set a new password for your Pluggie account and turns off two-factor authentication on the account. The link is valid for 30 minutes and is not stored by the app.
5. Sign in with the new password and set up two-factor authentication again.

The support code is valid for a limited time and works once; after 5 wrong attempts within 15 minutes you have to wait before trying again.

Backups

In Home Assistant, the certificate authority is stored in the Pluggie app's private data folder and is included in Home Assistant backups that include the Pluggie app, so restoring such a backup keeps all device certificates working. Restoring an older backup also brings back certificates you revoked after it was made, so revoke them again. With the Docker container it is stored in /data/mtls inside the container's data directory; include that directory in your backups. Keep in mind that a backup containing the certificate authority is as sensitive as the certificates themselves.