MongoDB Based Device Registry Configuration

The MongoDB based Device Registry component provides an implementation of Eclipse Hono™’s Device Registration, Credentials and Tenant APIs. Protocol adapters use these APIs to determine a device’s registration status, e.g. if it is enabled and if it is registered with a particular tenant, and to authenticate a device before accepting any data for processing from it. In addition to the above, this Device Registry also provides an implementation of Device Registry Management APIs for managing tenants, registration information and credentials of devices.

The registry is implemented as a Quarkus application, using a MongoDB database as the persistence store. It can be run either directly from the command line or by means of starting the corresponding Docker image created from it.

Service Configuration

The following table provides an overview of the configuration variables and corresponding system properties for configuring the MongoDB based Device Registry.

The variables only need to be set if the default value does not match your environment.

In addition to the options described in the table above, this component supports the following standard configuration options:

• Common Java VM Options
• Common vert.x Options
• Monitoring Options

Port Configuration

The Device Registry supports configuration of both, an AMQP based endpoint as well as an HTTP based endpoint proving RESTful resources for managing registration information and credentials. Both endpoints can be configured to listen for connections on

• a secure port only (default) or
• an insecure port only or
• both a secure and an insecure port (dual port configuration)

See Port Configuration for more information.

Authentication Service Connection Configuration

See Authentication Service Connection Configuration for more information.

Metrics Configuration

See Monitoring & Tracing Admin Guide for details on how to configure the reporting of metrics.

Encrypting Secrets

Hono’s CoAP protocol adapter supports authentication of devices during the DTLS handshake based on a pre-shared key. A pre-shared key is an arbitrary sequence of bytes which both the device as well as the protocol adapter need to present during the handshake in order to prove their identity. The Mongo DB based registry implementation supports managing these keys by means of PSK credentials which can be set for devices. By default, the bytes representing the key are stored as a base64 encoded string property of the credentials document. In order to better protect these keys from unintended disclosure, the registry can be configured to encrypt these keys before they are written to the database collection. During read operations the keys are then decrypted again before they are returned to an authorized client.

In order to activate this transparent encryption/decryption, the HONO_CREDENTIALS_SVC_ENCRYPTIONKEYFILE configuration variable needs to be set to the path to a YAML file containing the definition of the symmetric keys that should be used for encryption. The file is expected to have the following format:

defaultKey: 2
keys:
- version: 1
  key: hqHKBLV83LpCqzKpf8OvutbCs+O5wX5BPu3btWpEvXA=
- version: 2
  key: ge2L+MA9jLA8UiUJ4z5fUoK+Lgj2yddlL6EzYIBqb1Q=

The file needs to contain at least all versions of the key that values in the database collection have been encrypted with. Otherwise the registry will not be able to decrypt these values during reading. The defaultKey property indicates the version of the key that should be used when encrypting values. Please refer to the CryptVault project for additional information regarding key rotation.

Messaging Configuration

The Device Registry uses a connection to an AMQP 1.0 Messaging Network and/or an Apache Kafka cluster to

• send Device Provisioning Notification event messages to convey provisioning related changes regarding a device, to be received by downstream applications,
• send notification messages about changes to tenant/device/credentials data, to be processed by other Hono components.

For the event messages a connection to an AMQP 1.0 Messaging Network is used by default, if configured. If both kinds of messaging are configured, the decision which one to use is done according to the Tenant Configuration.

For notification messages, the Kafka connection is used by default, if configured. Otherwise the AMQP messaging network is used.

AMQP 1.0 Messaging Network Connection Configuration

The connection to the AMQP 1.0 Messaging Network is configured according to the Hono Client Configuration with HONO_MESSAGING being used as ${PREFIX}. Since there are no responses being received, the properties for configuring response caching can be ignored.

Kafka based Messaging Configuration

The connection to an Apache Kafka cluster can be configured according to the Hono Kafka Client Configuration.

The following table shows the prefixes to be used to individually configure the Kafka clients used by the Device Registry. The individual client configuration is optional, a minimal configuration may only contain a common client configuration consisting of properties prefixed with HONO_KAFKA_COMMONCLIENTCONFIG_ and hono.kafka.commonClientConfig. respectively.