Overview

Kaa Protocol Communication service (KPC) implements 1/KP-based communication with clients and endpoints the client represents. Supported transports are:

  • plain MQTT
  • MQTTS (MQTT over TLS)
  • MQTT over Websocket

All listed transports can be enabled and supported concurrently by a single KPC instance.

KPC is the first point of contact between a client and the Kaa IoT platform. KPC performs client authentication and endpoint identification. For clients, authentication can be done using MQTT username/password combination or client SSL certificate. Endpoints are identified using endpoint tokens.

Once a client is connected to KPC, this service manages further client’s interactions with Kaa extension services. KPC is unaware of the specifics of the extension protocols that are multiplexed on top of 1/KP (2/DCP, 7/CMP, 10/EPMP, etc.). Rather, it uses information available in 1/KP to (de-)multiplex extensions protocols and route messages from clients to appropriate extension service instances and vice versa.

Interfaces

KPC supports a number of interfaces to perform its functional role. The key supported interfaces are summarized in the following diagram.

KPC interfaces diagram

For inter-service communication, Kaa services mainly use REST APIs and messaging protocols that run over NATS messaging system.

Kaa Protocol

KPC uses 1/KP over MQTT to communicate with clients. The service listens to incoming client sessions on an exposed TCP port.

Client MQTT-based communication can be protected with TLS. With a bidirectional TLS handshake configured, KPC performs initial verification of the client’s certificate (signature, authority, expiration, etc.). After verification, KPC uses the configured authentication interface to complete the client authentication and make sure that the client is allowed to connect.

Authentication

KPC uses the Endpoint and Client Authentication Protocol (16/ECAP) to validate client and endpoint credentials:

  • client MQTT username/password combination
  • client SSL certificate
  • endpoint token

KPC also subscribes to endpoint token revocation events and client credential revocation events. It terminates communication sessions with endpoints and clients, respectively, when their credentials get revoked. On consequent attempts to send a message or reconnect, KPC will first require performing authentication.

The default authentication service that KPC uses is the Credential Management service (CM).

Endpoint connectivity events

When an endpoint is connected to the system or disconnected from it, KPC broadcasts a corresponding 9/ELCE event to other services. KPC also listens to connectivity events for the purpose of detecting and handling endpoint roaming across service replicas.

Extension service protocol

KPC uses 4/ESP over NATS to deliver client-originated messages to extension services and vice versa.

Tekton integration

KPC is integrated with the Kaa Tekton for centralized application configuration management. It receives configuration update messages from Tekton over 17/SCMP and uses Tekton REST API to retrieve current configs.

See configuration for more information.

Kaa Tenant Manager integration

KPC supports multi-tenancy with each tenant using a separate OAuth 2.0 issuer for authentication, authorization, and resource management. The list of the existing tenants is managed by [the Kaa Tenant Manager][Tenant Manager], which provides REST API for retrieving tenant security configs.

See the security configuration for more details on how to enable multi-tenancy in KPC.

Management interface

KPC exposes an HTTP-based management interface with the following endpoints:

  • GET /health returns 200 OK if the service is up and running properly, and 500 Internal Server Error otherwise. In case of errors, the response payload contains their human-redable descriptions. This endpoint can be used by Kubernetes for liveness and readiness probing.
  • GET /metrics provides service metrics in Prometheus text-based format.