The Additional CA integration for Home Assistant automatically loads a private Certificate Authority or self-signed certificate into Home Assistant to access 3rd-party services with TLS/SSL, even after Home Assistant is upgraded.
- If you manage your own CA, or you trust a specific CA, you will have a
ca.crtfile (or equivalent). This can be called a personal / own / private / custom CA. - If you generate a self-signed TLS/SSL certificate, you will get a
.crtfile (or equivalent), which is also considered a personal / own / private / custom trusted CA.
📒 This documentation uses 'private CA' or 'self-signed cert' interchangeably for the same purpose.
Scenario: You want to import a certificate file into the Home Assistant OS (HAOS) trust store or the Home Assistant Docker container trust store to access a 3rd-party service with TLS/SSL:
- Some of your installed integrations in Home Assistant need to access devices or third-party services with TLS/SSL (HTTPS, etc.), and you have received a
ca.crtfile (or equivalent) from the service provider. ➡ You can load it with the Additional CA integration. - You have generated a self-signed TLS/SSL certificate for your own service (e.g., a personal HTTPS web server, SMTP, LDAP, etc.) that you want Home Assistant to trust. ➡ You can load it with the Additional CA integration.
- Install HACS
- Install the Additional CA integration via HACS or manually without HACS (full docs below).
- Copy your private CA to the config folder:
mkdir -p config/additional_ca
cp my_ca.crt config/additional_ca/- Enable
additional_cainconfiguration.yaml:
# configuration.yaml
---
default_config:
additional_ca:
my_private_ca: my_ca.crt
# ...- Restart Home Assistant
- Done!
Table of contents
- Additional CA for Home Assistant
- 📘 What does 'private Certificate Authority (CA)' mean here?
- 📘 What are the use cases for this integration?
- 📘 Quick Setup (TL;DR)
- 1. INSTALL WITH HACS
- 2. INSTALL WITHOUT HACS
- 3. CONFIGURATION
- 4. UPGRADE
- 5. HOW DOES Additional CA WORK UNDER THE HOOD?
- 6. HOW TO TEST YOUR CA WITH HTTPS
- 7. HOW TO REMOVE A PRIVATE CA?
- 8. UNINSTALL
- 9. TROUBLESHOOTING
- 10. KNOWN ISSUES
To install the Additional CA integration with HACS:
- Install HACS if not already done.
- Then, go to your Home Assistant instance,
- -> HACS
- -> Search for "Additional CA"
- -> Click the three-dots menu for Additional CA, then click Download
To install Additional CA integration without HACS, if you're running Home Assistant with Docker, you can use git or wget.
Download and install using git:
# move to your Home Assistant directory containing the 'config' folder
cd /path/to/home-assistant
# git clone Addition CA integration
git clone https://github.com/Athozs/hass-additional-ca.git
# copy additional_ca integration to Home Assistant custom components
mkdir -p config/custom_components
cp -r hass-additional-ca/custom_components/additional_ca config/custom_components/
# Installation is done, now see section [Configuration](#3-configuration) in this README.mdIf not installing using git, download and install using wget:
# move to your Home Assistant directory containing the 'config' folder
cd /path/to/home-assistant
# download Addition CA integration archive
wget https://github.com/Athozs/hass-additional-ca/releases/latest/download/additional_ca.zip
# unzip archive
unzip additional_ca.zip
# copy additional_ca integration to Home Assistant custom components
mkdir -p config/custom_components
cp -r additional_ca config/custom_components/
# Installation is done, now see section [Configuration](#3-configuration) in this README.md- Click the button to download the ZIP archive of Additional CA
- Unzip the archive.
- Move the
additional_cafolder into theconfig/custom_components/directory. - Installation is done. Now, see the section Configuration in this README.md.
To install the Additional CA integration without HACS if you're running Home Assistant from HAOS:
- Go to the Add-on store
- Install one of the SSH add-ons (you need to enable "Advanced mode" in your user profile to see them: Click your login name at the bottom left of the screen -> Enable Advanced mode)
- Configure your chosen SSH add-on by following its documentation.
- Start the SSH add-on
- Connect to the SSH add-on
- Download the latest release of Additional CA from GitHub (the .zip archive):
wget https://github.com/Athozs/hass-additional-ca/releases/latest/download/additional_ca.zip- Unzip the archive:
unzip additional_ca.zip- Move or copy the
additional_cafolder into theconfig/custom_components/directory:
mkdir -p config/custom_components
cp -r additional_ca config/custom_components/If you're running Home Assistant Core (as a Python package) directly on the host, you don't need the Additional CA integration. You should update the CAs from your host OS.
For now, Additional CA cannot be configured from the UI dashboard. This may be possible in a future release.
To configure the Additional CA integration, follow these steps:
- CA files must be in PEM format (often with a
.crtor.pemextension). You can check the content with a text editor. Here is an example of a certificate file (the following is a fake):
-----BEGIN CERTIFICATE-----
ACeuur4QnujqmguSrHU3mhf+cJodzTQNqo4tde+PD1/eFdYAELu8xF+0At7xJiPY
i5RKwilyP56v+3iY2T9lw7S8TJ041VLhaIKp14MzSUzRyeoOAsJ7QADMClHKUDlH
UU2pNuo88Y6igovT3bsnwJNiEQNqymSSYhktw0taduoqjqXn06gsVioWTVDXysd5
qEx4t6sIgIcMm26YH1vJpCQEhKpc2y07gRkklBZRtMjThv4cXyyMX7uTcdT7AJBP
ueifCoV25JxXuo8d5139gwP1BAe7IBVPx2u7KN/UyOXdZmwMf/TmFGwDdCfsyHf/
ZsB2wLHozTYoAVmQ9FoU1JLgcVivqJ+vNlBhHXhlxMdN0j80R9Nz6EIglQjeK3O8
I/cFGm/B8+42hOlCId9ZdtndJcRJVji0wD0qwevCafA9jJlHv/jsE+I9Uz6cpCyh
sw+lrFdxUgqU58axqeK89FR+No4q0IIO+Ji1rJKr9nkSB0BqXozVnE1YB/KLvdIs
uYZJuqb2pKku+zzT6gUwHUTZvBiNOtXL4Nxwc/KT7WzOSd2wP10QI8DKg4vfiNDs
HWmB1c4Kji6gOgA5uSUzaGmq/v4VncK5Ur+n9LbfnfLc28J5ft/GotinMyDk3iar
F10YlqcOmeX1uFmKbdi/XorGlkCoMF3TDx8rmp9DBiB
-----END CERTIFICATE-----
- Create the directory
config/additional_caand copy your private CA into it:
mkdir -p config/additional_ca
cp my_ca.crt config/additional_ca/Optionally, you can group CAs into subfolders.
Directory structure example:
.
├── compose.yml
├── config/
│ ├── additional_ca/
│ │ ├── my_ca.crt
│ │ ├── selfcert.crt
│ │ └── my_folder/
│ │ └── selfcert_2.pem
│ │ └── some_folder/
| | ├── ca2.pem
│ │ └── ca3.crt
│ ├── blueprints/
│ │ └── ...
│ ├── configuration.yaml
│ ├── custom_components/
│ │ └── additional_ca/
│ │ ├── __init__.py
│ │ ├── config_flow.py
│ │ ├── const.py
│ │ ├── exceptions.py
│ │ ├── manifest.json
│ │ └── utils.py
│ ├── ...
...
- Enable the Additional CA integration in
configuration.yamland set the private CA:
The Additional CA integration will search in config/additional_ca/ to find your CA. If your CA has the path config/additional_ca/my_ca.crt, then your configuration.yaml should look like this:
# configuration.yaml
---
default_config:
additional_ca:
some_ca: my_ca.crt
# ...Model:
# configuration.yaml
---
default_config:
additional_ca:
<string>: <Certificate filename or Certificate relative path as string>
# ...: ...Another example:
# configuration.yaml
---
default_config:
additional_ca:
some_ca: my_ca.crt # a cert file
ca_foo: some_folder/ca2.pem # relative path + a cert file
ca_bar: some_folder/ca3.crt # relative path + a cert file
my_self_signed_cert: selfcert.crt # a self-signed certificate
self_signed_crt: my_folder/selfcert_2.pem # relative path + a self-signed certificate
# ...- Restart Home Assistant.
Important
Some integrations need to be set up again to use the updated system CA trust store (which now includes your private CA).
After upgrading Home Assistant to a new version, you need to restart Home Assistant to load your certificates again.
- Check the logs. Look for the pattern
additional_cain the traces (there is no UI for Additional CA).
If you upgrade to a new version of Home Assistant, you need to restart Home Assistant to load your certificates again with Additional CA.
If you upgrade to a new version of the Additional CA integration, you need to restart Home Assistant to load your certificates again.
If you're running Home Assistant with Docker:
When enabled, the Additional CA integration looks for private Certificate Authority (CA) files and self-signed certificates in the config/additional_ca/ directory.
The Additional CA integration loads private CAs and self-signed certs only at Home Assistant startup.
The Additional CA integration copies the private CAs and self-signed certs to the /usr/local/share/ca-certificates/ directory inside the container and runs the update-ca-certificates command to update the system CA trust store at /etc/ssl/certs/ca-certificates.crt.
Note
In earlier versions of Additional CA (0.4.x and below), you needed to set the REQUESTS_CA_BUNDLE environment variable for certificate verification. This is no longer required. The integration now uses the certifi-linux Python package, which automatically points Certifi to the system CA trust store at /etc/ssl/certs/ca-certificates.crt.
HAOS is actually a Linux-based OS that runs a homeassistant Docker container inside.
If you're running Home Assistant from a HAOS or Supervised installation, the Additional CA integration works the same way as with Docker installation.
To show the system CA content:
- Turn off Protection mode in the SSH add-on to enable the
dockerCLI (Settings > Add-ons > SSH > turn off Protection mode). - Connect to HAOS with SSH, then from the command line, run:
docker exec homeassistant cat "/etc/ssl/certs/ca-certificates.crt"After adding your CA, you can create a test action/service to verify that the https connection is working.
- Here is an example of
configuration.yamlto create an actionRESTful Command: additional_ca_test:
# configuration.yaml
logger:
default: info
additional_ca:
my_ca: ca.crt
rest_command:
additional_ca_test:
url: "https://your-server.com/" # <- use your own url here
method: get
verify_ssl: true
timeout: 30
- Then, run the action
RESTful Command: additional_ca_testfrom the Developer Tools panel. You should seestatus: 200in the response to confirm success. - If TLS/SSL does not work, you will see error details in the Home Assistant logs:
[homeassistant.components.rest_command] Client error. Url: https://your-server.com/.
Error: Cannot connect to host your-server.com ssl:True
[SSLCertVerificationError: (1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
unable to get local issuer certificate (_ssl.c:1006)')]
To test your CA using curl, if you're running Home Assistant with Docker, then from your shell prompt, run:
docker exec CONTAINER_NAME curl -v -I https://your-server.comYou should see an HTTP code 200 to confirm success.
To test your CA using curl, if you're running Home Assistant with HAOS:
- Turn off Protection mode in the SSH add-on to enable the
dockerCLI (Settings > Add-ons > SSH > turn off Protection mode). - Connect to HAOS via SSH, then from the command line, run:
docker exec homeassistant curl -v -I https://your-server.comYou should see an HTTP code 200 to confirm success.
To remove your CA: remove or comment out the CA entry under the additional_ca domain key in configuration.yaml:
# configuration.yaml
---
default_config:
additional_ca:
# some_ca: my_ca.crt
# ...Optionally, remove your private CA file from the config/additional_ca/ directory.
On the next restart of Home Assistant, the Additional CA integration will remove unused CA from system CA trust store, ensuring that only the active CA entries under the additional_ca domain key in configuration.yaml will be loaded.
Alternatively, you could reset system CA of Home Assistant, see section Reset CA trust store of Home Assistant in this README.md.
To uninstall the Additional CA integration, follow these steps:
- Uninstall it from
custom_components:
If you installed the Additional CA integration via HACS:
- Go to your Home Assistant
- -> HACS
- -> Locate Additional CA
- -> Click the three-dots menu for Additional CA, then click Remove
Or, if you installed the Additional CA integration manually:
rm -r config/custom_components/additional_ca- Remove the
additional_cadomain key fromconfiguration.yaml:
# configuration.yaml
---
default_config:
# additional_ca:
# some_ca: my_ca.crt
# ...- Optionally, remove the
additional_cafolder containing your private CAs:
rm -r config/additional_ca- Restart Home Assistant.
If you are using Docker Compose, recreate the container:
docker compose up -d --force-recreateSome tips for cleaning your system CA trust store inside Home Assistant in case of failure.
- Enable the INFO log level in Home Assistant (see Tips below).
- Check the error logs in Home Assistant at Settings > System > Logs.
- Some integrations need to be set up again to use the updated system CA trust store (which now includes your private CA).
To reset the system CA trust store in Home Assistant with Docker:
- Stop and remove the HA container. This will remove all changes made inside the container. Then, start Home Assistant with Docker again.
docker compose up -d --force-recreateAlternatively, you can do the following:
- Manually remove the private CA files from the
/usr/local/share/ca-certificates/directory inside the HA container. - Then, manually update the system CA trust store by running the command
update-ca-certificatesinside the HA container.
To reset the system CA trust store in Home Assistant from a HAOS or Supervised installation:
- Turn off Protection mode in the SSH add-on to enable the
dockerCLI (Settings > Add-ons > SSH > turn off Protection mode). - Connect to HAOS via SSH, then from the command line, run the following to stop and remove the
homeassistantDocker container inside HAOS and reboot HAOS:
docker stop homeassistant
docker rm homeassistant
reboot- To enable the INFO log level, add the following to your
configuration.yaml:
# configuration.yaml
logger:
default: info- To check your certificate's validity, if using x509 certs, run:
openssl x509 -in config/additional_ca/my_ca.crt -text -noout- In some cases, you may have to restart Home Assistant twice for the new CA to be taken into account. This is due to Home Assistant creating an SSL context before integrations can be loaded.