Jens Erat edited this page Jun 26, 2016 · 9 revisions

Documentation of openHAB's security features


To secure the communication with openHAB there are currently two mechanisms in place

  • Authentication

Authentication is implemented by SecureHttpContext which in turn implements HttpContext. This SecureHttpContext is registered with the OSGi !HttpService and provides the security hook handleSecurity. At least all authentication requests are delegated to the which is the entry point to JAAS ( !LoginModules.

The SecureHttpContext is currently used by the WebAppServlet and the CmdServlet which constitutes the default iPhone UI as well as the RESTApplication which provides the REST functionality.


openHAB supports HTTPS out of the box. Just point your browser to

and the HTTP communication will be encrypted by SSL.

If you prefer to use your own X.509 certificates, you can. Configure_SSL has information on how to do that, and there's a step-by-step guide specifically for openHAB users.

[Here is a guide] ( for using [Let's Encrypt] ( with openHAB.

Reverse Proxy

If you place a reverse proxy adding SSL in front of OpenHAB, make sure to either connect it to the OpenHAB HTTPS URI or pass an additional X-Forwarded-Proto header. This makes sure Jetty is aware the user accesses OpenHAB through an secured connection. Failure to do so will result in broken API access.

Add this next to the proxy_pass line for nginx:

proxy_set_header X-Forwarded-Proto $scheme;

For Apache, add this to your <VirtualHost> block:

RequestHeader set X-Forwarded-Proto "https" env=HTTPS


In order to activate Authentication one has to have the following parameters to the openHAB start command line. This may already be done by default.

  • - the configuration file of the JAAS !LoginModules

By default the command line references the file <openhabhome>/etc/login.conf which in turn configures a PropertyFileLoginModule that references the user configuration file One should use all available LoginModule implementation here as well (see for further information).

The default configuration for login credentials for openHAB is the file <openhabhome>/configuration/users.cfg. In this file, you can put a simple list of "user=pwd" pairs, which will then be used for the authentication. For example:


Note that you could optionally add roles after a comma, but there is currently no support for different roles in openHAB.

Security Options

The security options can be configured through openhab.cfg. One can choose between

  • ON - security is enabled generally
  • OFF - security is disabled generally
  • EXTERNAL - security is switched on for external requests (e.g. originating from the Internet) only

To distinguish between internal and external addresses one may configure the security:netmask in openhab.cfg. Every ip-address which is in range of this net mask will be treated as internal address must not be authorized though. Multiple netmasks can be specified (comma separated). This may be necessary on networks using both IPv4 and IPv6 addresses. To debug issues with netmasks set the logging level to TRACE in logback.xml.

feature overview


Setup intro

Linux and OS X





User Interfaces



(link to openHAB forum)



Application Integration



A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Binding configurations

Use case examples

Item definition examples

Sitemap definition examples

Collections of Rules on a single page

Single Rules


Syntax highlighting for external editors

Release Notes

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.