Stefan Bethke
f49cb3d6f3
All checks were successful
docker-image / docker (push) Successful in 9m31s
91 lines
No EOL
5.9 KiB
Markdown
91 lines
No EOL
5.9 KiB
Markdown
# 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_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`.
|
||
|
||
1. Create a self-signed certificate:
|
||
|
||
```shell
|
||
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:
|
||
|
||
```shell
|
||
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`](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:
|
||
|
||
```shell
|
||
docker compose exec -it keycloak /opt/keycloak/data/import/export.sh
|
||
``` |