hmdooris - Dooris via HomeMatic

Configuration

All configuration is handled through environment variables.

Name	Default	Description
HMDOORIS_ALLOWED_IPS	-	List of IP addresses in CIDR notation that are allowed to control the locks.
HMDOORIS_DISCOVERY_URL	http://localhost:8080/realms/testing/.well-known/openid-configuration	OIDC configuration discovery URL.
HMDOORIS_CCUJACK_CERTIFICATE_PATH	-	File of a private certificate, or false.
HMDOORIS_CCUJACK_PASSWORD	-	Password in CCU Jack.
HMDOORIS_CCUJACK_URL	https://raspberrymatic:2122	URL of the CCU Jack server.
HMDOORIS_CCUJACK_USERNAME	-	Username in CCU Jack.
HMDOORIS_CLIENT_ID	hmdooris	OIDC client ID.
HMDOORIS_CLIENT_SECRET	-	ODIC client secret for the confidential flow.
HMDOORIS_LISTEN	127.0.0.1:3000	Which IP and port to listen on.
IDINVITE_OIDC_SCOPE	["openid", "email", "profile"]	JSON list of OIDC scopes to request. The OIDC IDP will need to send the group attribute.
IDINVITE_OIDC_USER_ATTR	email	The attribute to use as the user ID.
HMDOORIS_REQUIRES_GROUP	-	Set to require users to be a member of this groups.
HMDOORIS_URL	http://localhost:3000	URL of the application, used to construct links to itself.

Required Group

If you would like to restrict lock operations to members of a particular group, configure the OIDC client to add group information to the ID token, and set HMDOORIS_REQUIRES_GROUP to the name of the group you would like to use.

Otherwise, all users that can authenticate successfully can operate the locks.

TLS Certificate Configuration

If you'd like to secure access to CCU Jack via TLS, you either need to install a publically trusted certificate on RaspberryMatic. If you are using a private certificate, you will need to use HMDOORIS_CCU_CERTIFICATE_PATH to point the HTTP client to a suitable CA certificate. Setting the variable to false will disable certificate verification. Alternatively, you can use plain http.

Managing the CCU certificate

If you want to talk to the RaspberryMatic/CCU-Jack and you are using a self-signed certificate (which is the default), you will need to supply that certificate to hmdooris.

1. Create a self-signed certificate:

openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 \
  -nodes -keyout hmdooris-ccu.ccchh.net.key -out hmdooris-ccu.ccchh.net.crt -subj "/CN=hmdooris-ccu.ccchh.net" \
  -addext "subjectAltName=DNS:hmdooris-ccu.ccchh.net"
cat hmdooris-ccu.ccchh.net.crt hmdooris-ccu.ccchh.net.key >hmdooris-ccu.ccchh.net.certkey.pem

2. Save the certificate to a file:

echo | \
  openssl s_client -servername hmdooris-ccu.ccchh.net -connect hmdooris-ccu.ccchh.net:2122 | \
  openssl x509 -text >self-signed.cert

2. Start hmdooris and pass the path to the file in the environment variable HMDOORIS_CCU_CERTIFICATE_PATH.

If you only want to use http, or your CCU has a public certificate (from for example Let's Encrypt), then you don't need to do anything.

Local Development Setup with Docker Compose

The included docker-compose.yaml will bring up a local Keycloak instance with a preconfigured realm that includes a client that can be used to test the application locally. You can log in to the admin console at http://localhost:8080/admin/master/console/ using "admin"/"admin".

Realm Keycloak: Client hmdooris and User hmdooris

In order for ID Invite to create users, it needs to access the Keycloak REST API with suitable credentials. This is implemented through a client hmdooris in the Keycloak realm, with the client secret XXX, and a username of hmdooris and password geheim.

Realm testing: Client hmdooris and User tony

Keycloak will import the realm export from local-dev/import/testing.json and create a realm testing, including a client and a user.

The client ID is hmdooris and the secret is ´8p21riiYPDEhpgRh2rgRDNu9uWVZ9KRj`.

You can log in to the realm and the application with user tony and password tester.

Updating the testing realm

If you'd like to make changes to the configuration of the testing realm, and have it persist across restarts, you can export the realm. Run this command:

docker compose exec -it keycloak /opt/keycloak/data/import/export.sh