Security

This page is about Domoticz version 2023.1 (which has significant security related changes to previous versions)

Introduction

Any Domoticz installation comes with a default User (admin) and Password (domoticz) so you can login as an administrator and start configuring your Domoticz setup.

A key step in setting up Domoticz is considering how to properly secure your setup.

IMPORTANT: First thing to do is changing the default password of the 'admin' user into something else! Otherwise everyone knows your admin password just by reading this page. Goto menu Setup - Users to change the admin password.

There are a number of 'components' involved when it comes to Domoticz security:

• Users (see page User management)
• Trusted networks
• Applications (in security context often referred to as Clients)
• Domoticz itself, which has 3 parts
  • The Domoticz User Interface (or website. This is the standard Application that comes with every installation)
  • The Domoticz Resource server (or core server that does all the magic)
  • The Domoticz IAM server (the part responsible for Identity & Access Management)

        (technically build-in the core server at the moment)

And there are a few more security specific settings that can be configured to further fine-tune Domoticz security.

Basic Security setup

In a basic setup, the following steps are sufficient for a proper- and secure functioning Domoticz.

Users

Create one or more Users to allow different people to control Domoticz. Assign the proper rights to each User.

Domoticz comes with 3 different rights (often called 'roles'). These are:

• admin; with admin rights you can control every aspect of Domoticz including all settings, configurations and user/rights management.
• user; this is the role for most Users as it gives them control to access all devices and if possible control them, like turning a light on or off.
• viewer; this is the most restrictive role as it only allows to 'view' devices but not control them. So such a user can 'read' the temperature target for a thermostat, but can not change the thermostat target temperature.

In general, you do not need multiple admins. Maybe a second User with admin privileges can be used as a backup admin User in case you forgot the credentials of the first admin. Your Users should either get 'user' or 'viewer' privileges.

For more info and instructions see the Setup Users page.

TIP: For the main User, create 2 accounts. One called for example 'mike' (if he is called Mike) with 'user' privileges. And a second one called 'mikeadmin' with 'admin' privileges. This way, 'mike' can login to Domoticz as a normal user, and leave his phone unprotected at the table without the risk that someone else abuses his 'admin' rights. When 'mike' needs to perform actions that require 'admin' privileges, he can login using his 'mikeadmin' account. And logout once he is done and go back using his normal 'mike' User account.

TIP2: Create a new admin User (for example 'mikeadmin') and disable the default User called 'admin'.

TIP3: You cannot switch users when the client is mentioned in the Trusted Network setting. Domoticz will then automatically login with the first admin account.

Pro-tip: You can see the Active User on the 'About' screen:

Advanced Security setup

Domoticz has support for multiple Identification & Authorization methods. These are:

• Login via a Browser with Username/Password (and as long as the session is alive, using a cookie, Domoticz remembers who you are)
• Retrieve an 'Access Token' (JWT Token) from the IAM server and provide this Bearer token with each request
• Provide valid credentials via 'Basic-Auth' with each API request. Only accepted for API calls!

NOTE: Somewhere in the future, the first method will be phased-out and the standard Domoticz application will be using the 2nd method.

The Security-tab

An admin user can access the menu 'Setup - Settings' screen and one of the Settings-tabs is the 'Security'-tab. Which looks as followed:

Here you can fine-tune several aspects.

API Protection

In the API Protection block, it is possible to enable Allow Basic Authentication over plain HTTP. By default, Basic-Auth credentials are only accepted when received properly encrypted using HTTPS. But sometimes, especially in local networks, the interaction between for example scripts or devices and Domoticz (API) is not secured via HTTPS and with this setting enabled Domoticz will accept Basic-Auth credentials when received over HTTP.

WARNING: Be careful with enabling this. Basic-Auth credentials are send in plaintext so can easily be captured and read when not encrypted via HTTPS. Especially if Domoticz is reachable from outside, for example via the Internet, it becomes easier for hackers to capture these credentials.

NOTE: Basic-Auth is only accepted for API-calls and not any other requests to Domoticz! This means only calls to '/json.htm' (the current API entrypoint) will look for credentials provided via Basic-Auth.

NOTE: API URLs with username and password as parameters (eg https://IP:PORT/json.htm?username=userBASE64&password=PWDBASE64& ) are not supported anymore!

Use https://username:password@IP:PORT/json.htm instead. Sending the User/Pass using Basic-Auth is actually safer then using the URL parameters as the user/password is not send as is, but (base64) encoded and not as part of the URL but in a separate header. And when done over HTTPS, everything is encrypted as well.

NOTE: API URLs with user/password normally only work with HTTPS when tested on browsers. Current browsers already remove the user/password section from the URL when used over HTTP. Use tools like 'curl' or 'postman' to test with HTTP. For external access it is advised to use HTTPS as it brings an extra encryption layer. See wiki Native HTTPS / SSL support and Native secure access with Lets Encrypt.

NOTE: When using some method other than a browser to connect to Domoticz API it may be necessary to do user Authorization differently. User Authorization over HTTP is done by setting the "Authorization" HTTP request header when sending the request to Domoticz. The value of this header is a base64 encoded string of the username and password. See wiki page Domoticz API authorisation for more details

Trusted Networks

By default Domoticz can only be accessed by providing valid credentials. But in some circumstances that might not be possible, for example when a certain device can send data to Domoticz but cannot provide credentials.

It is possible to receive requests from certain IP addresses that should be considered as Trusted. When a request comes in without any credentials, Domoticz will look at the IP-address of the request and check if it falls within the given 'Trusted Network'.

If the request comes from within a Trusted network and does not have any credentials provided, Domoticz will look for the first 'admin'-user it has in its Users list, and assumes the identity of that user. Now the request is processed further as if coming from this admin user.

NOTE: If a request comes in that provides credentials in some way, these credentials will be validated and accepted OR rejected regardless whether the IP-address comes from a Trusted network or not!

NOTE: For setups where a (reverse) Proxy is used, the IP address of that Proxy should be in the list of Trusted Networks. If that is the case, Domoticz will trust the Proxy Header information from the Proxy to determine the origin IP address of the request. This IP address is than used as the real source of the request, meaning that Domoticz will look at that address to determine how to handle the request, for example if it originates from the Trusted network or not. More info can be found in the section about Proxies.

Pro-TIP: A secure Domoticz setup should have no need for any Trusted networks. Only the IP-address(es) of trusted Proxy server(s) should be in the list!

Proxy servers

Special attention is required when using Domoticz behind a proxy server.

It does make sense to run Domoticz behind a Proxy for example to perform SSL offloading and/or safely route internet traffic to Domoticz when a connecting to the Internet is wanted.

Without any special action, Domoticz will see every request coming from the IP-address of the Proxy server and will treat that IP-address as the origin address. Although the request from the Proxy might contain information telling that a Proxy is involved, this information is not used by Domoticz as any request could be extended to contain such information that states it is coming from a Proxy.

Before Domoticz looks at this Proxy information, the IP-address of the Proxy should be specified in the Trusted Network list. Once the IP-address is in this list, Domoticz will use Proxy information in any request coming from such a trusted IP-address.

Domoticz honours the following Proxy-headers (in order):

• Forwarded
• X-Forwarder-For
• X-Real-IP

If it finds one of these headers, it will process them and use that information to further handle the request.

NOTE: It will only process 1 header and that is the first it will find (see above order). So when 2 different headers are provided, the 2nd will be ignored. Even when the 2nd could be more relevant, but Domoticz has no way to determine if one header is more relevant or accurate than another.

See page WebServer Proxy for example configuration on Apache, Nginx or Synology NAS.

Light/Switch Protection

If you want that an On/Off device be "protected" (see page Managing Devices), you can create a password that will be required by the system before executing commands, provided that you have ticked the "protected" box during the device editing phase.

Security Panel

The system has a security panel to specify if you are home/home-armed/away. You can use this as an alarm system. Here you can set the security code to change the arming state.

When you press arm on the security panel the default delay is set on 30 seconds before the alarm system becomes active. This can be modified with the setting Delay.

When the password has been entered in the password field and saved (apply button) an internal Domoticz device "Domoticz Security Panel" will be created and can be added as switch. To be sure also try to Arm/Disarm the security panel (Menu Settings - More Options - Security panel)

After this the security panel can be renamed, activated and used in scripting.

For information how to setup an alarm system with existing sensor see page Alarm Setup

Remote Shared Port

If you wish to share your sensors to other users, you can specify the remote port that Domoticz will listen on for remote connections. Consult your router for setting up a firewall/NAT rule to this port or check this howto.

More on security

As Domoticz supports OAuth2 and OpenID Connect, it has become easier and more secure to provide granular access for Domoticz to other external tools like Dashboards, Mobile Apps, other home-automation systems, etc.

To see what is supported, please query the OpenID Connect discovery endpoint at https://<yourdomoticzip:port>/.well-known/openid-configuration.

Applications

Each application known to a Domoticz instance needs an Application Name (ClientID in OIDC/Oauth2 terminology). The actual client application needs to transmit this ClientID when going through the identification and authorization steps.

As Domoticz can also act as the IAM Service (Identity and Access Management), domoticz can give out Tokens that client applications can use as proof that they are acting on behave of a specific User. For each application, it can give out these Tokens which are specifically intended for use with its corresponding application. These Tokens are cryptographically signed to prevent tampering and have a limited validity. To perform these signing and checking actions, Domoticz needs somekind of secret (ClientSecret in OAuth2/OIDC terms) for each application.

It can either be an 'application secret' (when 'isPublic' is off), which is 'just' a string acting as a key (or password). So please specify a strong key (use a good password generator)!

Or generate cryptographic public/private key-pair, and store both in a PEM-file, and point Domoticz to this PEM-file by enabling the 'IsPublic' setting. <-- Recommended way

The actual client Applications have no need to know either the 'application secret' and/or public key as they just pass on the Token received from Domoticz during the Authorization process.

External IAM services (Single-Sign-On)

It is possible to use other Identity & Access Management servers or services to manage identities and access to Domoticz. That way there is no need to use the internal IAM service and it becomes possible to implement Single Sign-On across multiple applications including Domoticz.

As Domoticz uses OAuth2 and OpenID Connect (OIDC), any Identity services that supports these protocols could be used in theory.

Scripts and other integrations

Instead of using 'Basic-Auth' as authorization mechanism, scripts or any other integration should try to use the OAuth2 authorization_code grant-type flow (preferably with use of the PKCE extension) or fall-back on the password grant-type. These modern mechanism ensure that only a temporary valid Token has to be exchanged with each request and not the user credentials.

Also, each script or integration should become its own application ensuring that the credentials used, are only used by the specified application. And in case the credentials for an application have been compromised/leaked, just disabling the application is sufficient to prevent abuse.

More information

More information can be found by reading the SECURITY_SETUP.md file in the Domoticz sourcecode repository on GitHub.