Tenant API Specification

The Tenant API is used by Hono’s protocol adapters to retrieve information that affects all devices belonging to a particular tenant. A tenant is a logical entity, which groups together a set of devices. The information registered for a tenant is used for example to determine if devices belonging to the tenant are allowed to connect to a certain protocol adapter or if devices are required to authenticate.

This document describes the Tenant API’s operations and the payload data format used by them. Please refer to Multi Tenancy for details regarding the way Hono supports multiple tenants.

The Tenant API is defined by means of AMQP 1.0 message exchanges, i.e. a client needs to connect to Hono using an AMQP 1.0 client in order to invoke operations of the API as described in the following sections.

Preconditions for invoking the Tenant API

1. Client has established an AMQP connection with the Tenant service.
2. Client has established an AMQP link in role sender on the connection using target address tenant. This link is used by the client to send request messages to the Tenant service.
3. Client has established an AMQP link in role receiver on the connection using source address tenant/${reply-to} where reply-to may be any arbitrary string chosen by the client. This link is used by the client to receive responses to the requests it has sent to the Tenant service. This link’s source address is also referred to as the reply-to address for the request messages.

Get Tenant Information

Clients use this operation to retrieve information about a tenant.

Message Flow

The following sequence diagram illustrates the flow of messages involved in a Client retrieving tenant information.

Request Message Format

The following table provides an overview of the properties a client needs to set on a message to get tenant information:

The body of the request message MUST consist of a single Data section containing a UTF-8 encoded string representation of a single JSON object.

The JSON object MUST contain exactly one of the following search criteria properties:

The following request payload may be used to look up the tenant with identifier ACME Corporation:

{
  "tenant-id": "ACME Corporation"
}

The following request payload may be used to look up the tenant for which a trusted certificate authority with subject DN O=ACME Corporation, CN=devices has been configured:

{
  "subject-dn": "CN=devices,O=ACME Corporation"
}

Response Message Format

The following table provides an overview of the properties contained in a response message to a get tenant information request:

The response message’s status property may contain the following codes:

For status codes indicating an error (codes in the 400 - 499 range) the message body MAY contain a detailed description of the error that occurred. In this case, the response message’s content-type property SHOULD be set accordingly.

Otherwise the response message contains the information for the requested tenant as described in the following sections.

Tenant Information Format

Tenant information is carried in a single Data section of the response message as a UTF-8 encoded string representation of a single JSON object. It is an error to include payload that is not of this type.

The table below provides an overview of the standard members defined for the JSON response object:

The JSON object MAY contain an arbitrary number of additional members with arbitrary names which can be of a scalar or a complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.

Examples

The JSON structure below contains example information for tenant TEST_TENANT. Note that the structure contains some custom properties at both the root level (customer) as well as the adapter configuration level (deployment) and also defines a default TTL for downstream messages.

{
  "tenant-id": "TEST_TENANT",
  "defaults": {
    "ttl": 30
  },
  "enabled": true,
  "customer": "ACME Inc.",
  "resource-limits": {
    "max-connections": 100000,
    "data-volume": {
      "max-bytes": 2147483648,
      "period": {
        "mode": "days",
        "no-of-days": 30
      },
      "effective-since": "2019-07-27T14:30:00Z"
    }
  },
  "adapters": [
    {
      "type": "hono-mqtt",
      "enabled": true,
      "device-authentication-required": true
    }, {
      "type": "hono-http",
      "enabled": true,
      "device-authentication-required": true,
      "deployment": {
        "maxInstances": 4
      }
    }
  ]
}

Tracing Format

The table below provides an overview of the members defined for the tracing JSON object:

Trusted CA Format

The table below provides an overview of the members of a JSON object representing a trusted CA:

Examples

Below is an example payload for a response to a get request for tenant TEST_TENANT. The tenant is configured with two trusted certificate authorities, each using a different public key algorithm. Only one of them is configured to be used for auto-provisioning.

{
  "tenant-id" : "TEST_TENANT",
  "enabled" : true,
  "trusted-ca": [{
    "subject-dn": "CN=ca,OU=Hono,O=Eclipse",
    "public-key": "PublicKey==",
    "auto-provisioning-enabled": false,
    "algorithm":  "RSA"
  }, {
    "subject-dn": "CN=ca,OU=Hono,O=ACME Inc.",
    "public-key": "ECKey==",
    "auto-provisioning-enabled": true,
    "algorithm":  "EC"
  }]
}

Adapter Configuration Format

The table below contains the properties which are used to configure a Hono protocol adapter:

Protocol adapters SHOULD use the configuration properties set for a tenant when interacting with devices of that tenant, e.g. in order to make authorization decisions etc.

The JSON object MAY contain an arbitrary number of additional members with arbitrary names of either scalar or complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.

Resource Limits Configuration Format

The table below contains the properties which are used to configure a tenant’s resource limits:

Protocol adapters SHOULD use the max-connections property to determine if a device’s connection request should be accepted or rejected.

Protocol adapters SHOULD use the max-ttl property to determine the effective time-to-live for event messages published by devices as follows:

1. Set effective ttl to -1 (unlimited).
2. If a max-ttl value greater than effective ttl is set for the tenant, use that value as the new effective ttl.
3. If the event published by the device
   • contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl.
   • does not contain a ttl header but a default property with name ttl is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl.
4. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds).

Protocol adapters SHOULD use the max-ttl-telemetry-qos0 and max-ttl-telemetry-qos1 properties to determine the effective time-to-live for telemetry messages published by devices with QoS 0 or QoS 1 respectively as follows:

1. Set effective ttl to -1 (unlimited).
2. If a max-ttl-telemetry-qos0 value greater than effective ttl is set for the tenant, use that value as the new effective ttl.
3. If the message published by the device
   • contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl.
   • does not contain a ttl header but a default property with name ttl-telemetry-qos0 is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl.
4. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds).

Protocol adapters SHOULD use the max-ttl-command-response property to determine the effective time-to-live for command response messages published by devices as follows:

1. Set effective ttl to -1 (unlimited).
2. If a max-ttl-command-response value greater than effective ttl is set for the tenant, use that value as the new effective ttl.
3. If the message published by the device
   • contains a ttl header and either effective ttl is -1 or the ttl value (in seconds) provided by the device is smaller than the effective ttl, then use the ttl value provided by the device as the new effective ttl.
   • does not contain a ttl header but a default property with name ttl-command-response is configured for the device (with the device level taking precedence over the tenant level) and either effective ttl is -1 or the default property’s value is smaller than the effective ttl, then use the configured default ttl value as the new effective ttl.
4. If effective ttl is not -1, then set the downstream message’s ttl header to its value (in milliseconds).

The JSON object MAY contain an arbitrary number of additional members with arbitrary names of either scalar or complex type. This allows for future well-known additions and also allows to add further information which might be relevant to a custom adapter only.

Connection Duration Configuration Format

The table below contains the properties which are used to configure a tenant’s connection duration limit:

Protocol adapters that maintain connection state SHOULD use this information to determine if a connection request from a device should be accepted or not. For more information, please refer to the connection duration limit concept.

Data Volume Configuration Format

The table below contains the properties which are used to configure a tenant’s data volume limit:

Protocol adapters SHOULD use this information to determine if a message originating from or destined to a device should be accepted for processing.

Resource Limits Period Configuration Format

The table below contains the properties that are used to configure a tenant’s resource limits period:

Extension properties Format

The table below contains the extension properties that are used for addition configuration:

Delivery States used by the Tenant API

A Tenant service implementation uses the following AMQP message delivery states when receiving request messages from clients: