hmdooris - Dooris via HomeMatic

Configuration

All configuration is handled through environment variables.

Name	Default	Description
`HMDOORIS_URL`	`http://localhost:3000`	URL of the application, used to construct links to itself
`HMDOORIS_DISCOVERY_URL`	`http://localhost:8080/realms/testing/.well-known/openid-configuration`	OIDC configuration discovery URL
`HMDOORIS_CLIENT_ID`	`hmdooris`	OIDC client ID
`HMDOORIS_CLIENT_SECRET`	-	ODIC client secret for the confidential flow
`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_CCUJACK_URL`	`https://raspberrymatic:2122`	URL of the CCU Jack server
`HMDOORIS_CCU_CERTIFICATE_PATH`	-	File of a private certificate, or `false`
`HMDOORIS_CCUJACK_USERNAME`	-	Username in CCU Jack
`HMDOORIS_CCUJACK_PASSWORD`	-	Password in CCU Jack

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.

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

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

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

5.7 KiB Raw Blame History Unescape Escape