Cloud Services for OHX

OHX is a modern smarthome solution, embracing technologies like software containers for language agnostic extensibility. Written in Rust with an extensive test suite, OHX is fast, efficient, secure and fun to work on.

This repository contains all OHX cloud related services. The following stateless function services are present:

• OAuth service: For Amazon Alexa, and the Addon command line utility as well as the website.
• The cloud-vault service which provides authenticated clients access to certain secrets depending on the user granted access token scopes.
• Subscriptions: Manages payed subscriptions. Hosting a connection broker on Amazon EC2 does not come for free. A tiny subscription fee helps to compensate.
• Addon-Registry: Provides an http interface for the website and addon CLI to interact with the Addon registry.

One long-running service is required:

• A connection/message broker

The following libraries are hosted in this repository:

• cloud-auth-lib: Provides OAuth DTOs, jwt handling (creating, verifying), credentials handling, rocket guards and fairings for Cors support, rate limiting, oauth token guard and oauth client login functions.
• cloud-addon-lib: Used by the Addon CLI and the cloud-addon-registry service. Provides DTOs and related functionality for the addon registry.

The authentication concepts are summarized below, because external services are involved.

OAuth Service

OAuth authentication for the Website, Cloud-Connector, Alexa Skill

Note: OHX installations use their own, local authentication service, residing in https://github.com/openhab-nodes/core.

This service implements the OAuth Code Grant and OAuth Device flow in combination with the website, which renders the login page via Google Firestore Auth.

For caching intermediate tokens during the OAuth device flow, a Redis database is used.

Firestore Auth provides automatic profile consolidation, federated logins via Github, Facebook and other OIC providers, email address confirmation and a lost password function.

Firestore Auth tokens are exchanged into OHX OAuth tokens and can be revoked by the user on the website.

This service is itself an OIC provider.

OAuth clients

Find all allowed services in oauth_clients.json. This is currently

• the Addon registry CLI tool,
• Amazon Alexa,
• Google Home,
• the cloud message broker,
• the Cloud Connector Addon.

Looking at Amazon Alexa as an example, the procedure works like this:

• The Amazon Alexa App opens https://oauth.openhabx.com/authorize?client_id={}&client_secret={}&state={}&redirect_uri={}
• This service will redirect to the website https://openhabx.com/auth, passing all arguments and adding two more (unsigned and code). Those are transparent blobs for the website.
• The user logs in via his openhabx.com credentials and confirms access.
• The website calls /grant_scopes with the granted scopes, unsigned and code attached and gets an OAuth code in response.
• The webpage redirects to the given redirect_url, appending the code.
• Amazon servers will now exchange the code for an access token / refresh token tuple via the https://oauth.openhabx.com/token endpoint of this service.
• The user can enumerate and revoke refresh tokens on https://openhabx.com/access_tokens.

For the CLI it works a bit different, because the OAuth device flow is used. Instead of a redirect, the /token endpoint is polled while the user is logging in and confirming access.

Build and local test run

Change the log level via the "RUST_LOG" environment variable to "info", "warn", "error". Build and start with RUST_LOG=info cargo run for example.

Find deployment information in deployment.

You need the "secrets" directory.

This directory hosted on a private git repository with restricted access to the maintainer team only. Use the ./scripts/get-secrets.sh to check it out before building. Read about setting up a complete new "secrets" directory (and infrastructure) in create-secrets/readme.

See also Deployment for the Cloud-Deployment team.

Operation costs w/out tax

Assuming that Amazon AWS is used and in one region only.

Region	Service	Monthly	First 12 months total	Currency	Configuration summary
EU (Ireland)	AWS Lambda	0	0.00	USD	Number of requests (1000000)
EU (Ireland)	AWS API Gateway	0	0.00	USD	Number of requests (1000000)
EU (Ireland)	Amazon ECS t2.micro	7.40	88.80	USD	Linux, 1 GB Memory
EU (Ireland)	AWS Data Transfer	0.01	0.12	USD	Data Transfer 1 GB
EU (Ireland)	AWS CloudWatch	0	0.00	USD	5 Metrics free, Dashboard

• Paying 1yr upfront or 3yr upfront lowers the price by about 30%.
• Lambdas are only called on the website and via the Addon CLI. 1 Million should last for many, many users and addons. If the free-tier is exhausted, the next 333 Million calls cost $3,50 (API Gateway) + $0.2 per Million (Lambda).

Scalable

All stateless services that run as Google Cloud Functions or Amazon Lambdas are implemented via the Rust Rocket crate (a full https/http2 webserver) and adapted to Lambdas via the Rocket Lamb Crate.

If Amazon Lambda + API Gateway is getting too expensive with too many (concurrent) calls, those services can easily be migrated to an ECS instance.