Security - Revision history

Gizmocuz: /* Security Panel */

2026-03-28T06:47:07Z

Security Panel

← Older revision		Revision as of 06:47, 28 March 2026
Line 136:		Line 136:

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

			Make sure accept new devices is enabled under settings and to check the devices tab for the security device.

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

Gizmocuz at 19:54, 27 March 2026

2026-03-27T19:54:05Z

← Older revision		Revision as of 19:54, 27 March 2026
Line 1:		Line 1:
	'''''<big>This page is about Domoticz version ~~2023~~.1 (which has significant security related changes to previous versions)</big>'''''<br />		'''''<big>This page is about Domoticz version 2026.1 (which has significant security related changes to previous versions)</big>'''''<br />
	===Introduction===		===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.		Any new Domoticz installation will ask you for a administrator user/password 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.		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:		There are a number of 'components' involved when it comes to Domoticz security:

	*Users (see page [[User Management\|User management]])		*Users (see page [[User Management\|User management]])
	*Trusted networks		*Trusted networks
Line 21:		Line 18:

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

	~~<br />~~

	===Basic Security setup===		===Basic Security setup===

Walter vl: /* Applications */

2026-03-13T15:18:59Z

Applications

← Older revision		Revision as of 15:18, 13 March 2026
Line 164:		Line 164:
	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.		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.

			More information can be found by reading the [https://github.com/domoticz/domoticz/blob/development/SECURITY_SETUP.md SECURITY_SETUP.md] file in the Domoticz sourcecode repository on GitHub.
	<br />		<br />

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

			More information can be found by reading the [https://github.com/domoticz/domoticz/blob/development/SECURITY_SETUP.md SECURITY_SETUP.md] file in the Domoticz sourcecode repository on GitHub.
	<br />		<br />

Line 177:		Line 179:

	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.		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.

	~~<br />~~

	===More information===		===More information===
	More information can be found by reading the [https://github.com/domoticz/domoticz/blob/development/SECURITY_SETUP.md SECURITY_SETUP.md] file in the Domoticz sourcecode repository on GitHub.		More information can be found by reading the [https://github.com/domoticz/domoticz/blob/development/SECURITY_SETUP.md SECURITY_SETUP.md] file in the Domoticz sourcecode repository on GitHub.
	<br />		<br />

Walter vl: /* API Protection */

2024-07-29T12:21:27Z

API Protection

New page

'''''<big>This page is about Domoticz version 2023.1 (which has significant security related changes to previous versions)</big>''''' 
===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|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 [[User Management|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 [[User Management|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:

 
[[File:Domoticz_about.png|alt=Domoticz 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:

[[File:Domoticz security tab.png|alt=Security-tab of the Settings screen]]

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 '<code><nowiki>/json.htm</nowiki></code>' (the current API entrypoint) will look for credentials provided via Basic-Auth.

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

Use <code><nowiki>https://username:password@IP:PORT/json.htm</nowiki></code> 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/JSON URL's#Authorization|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 [[WebServer Proxy|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#Protected|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 [http://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/ 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 <code>https://<yourdomoticzip:port>/.well-known/openid-configuration</code>.

 

====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 [https://github.com/domoticz/domoticz/blob/development/SECURITY_SETUP.md SECURITY_SETUP.md] file in the Domoticz sourcecode repository on GitHub.