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
- plain HTTP
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 username/password combination (basic auth) or client SSL certificate (X.509 auth). 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.
KPC provides REST API for retrieving a server certificate file configured under
It can be used as a trust store of the clients connecting over TLS.
KPC supports a number of interfaces to perform its functional role. The key supported interfaces are summarized in the following diagram.
For inter-service communication, Kaa services mainly use REST APIs and messaging protocols that run over NATS messaging system.
KPC uses the Kaa Protocol to communicate with clients. All connections are inbound from clients to KPC. The currently supported 1/KP bindings are MQTT and HTTP. See MQTT and HTTP sections for corresponding transport configurations.
The table below sums up the different transport capabilities.
|Transport||Communication||Encryption||Basic client auth||X.509 client auth||Endpoint token auth|
|MQTT/WebSocket||Asynchronous||TLS at ingress
|Plain HTTP||Synchronous||TLS at ingress
* “TLS at ingress” means that the transport encryption is not natively supported by KPC.
However, TLS can be enabled at the Kubernetes ingress gateway in a given Kaa cluster to provide additional transport security.
KPC uses the Client Authentication Protocol (22/CAP) to verify client basic and X.509 credentials.
KPC also subscribes to client credentials revocation events. It terminates communication sessions with clients when their credentials get suspended or revoked. On consequent attempts to reconnect, KPC will first require performing client authentication.
The default client authentication service that KPC uses is the Client Credentials Management service (CCM).
Basic and X.509 client authentication can be enabled in KPC on a per-tenant basis. Refer to the service configuration for more details on how to configure the client authentication.
Basic client authentication
Basic authentication is currently supported on all MQTT-based transports: plain MQTT, MQTT/TLS, and MQTT/WebSocket. It leverages a standard MQTT user name / password combination set by the client in the Connect packet.
KPC accepts MQTT connections with no user name / password set; however, endpoint communication is not allowed over unauthenticated sessions if such authentication is configured to be required in the tenant that owns the endpoint.
To complete the basic authentication, client must submit the MQTT user name formatted as
This is necessary so that KPC knows in scope of which tenant to perform client authentication.
Once the basic auth is enabled on a transport in a tenant, KPC disconnects all unauthenticated client sessions which use that transport and belong to the given tenant.
X.509 client authentication
X.509 client authentication is supported by the MQTT/TLS transport. It is implemented based on the standard client TLS authentication using X.509 certificates.
With X.509 client authentication enabled, 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 and authorized to exchange data on behalf of tenant’s endpoints.
To take effect, X.509 client authentication should be enforced at the tenant level. When X.509 auth is enabled in a tenant, KPC disconnects all unauthenticated client sessions that belong to the given tenant.
KPC uses the Endpoint and Client Authentication Protocol (16/ECAP) to verify endpoint tokens.
KPC also subscribes to endpoint token revocation events. It terminates communication sessions with endpoints when their tokens get suspended or revoked. To continue exchanging messages with the platform, endpoints have to obtain and present a valid, active token.
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.
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, which provides REST API for retrieving tenant security configs.
See the security configuration for more details on how to enable multi-tenancy in KPC.
KPC exposes an HTTP-based management interface with the following endpoints:
GET /healthreturns 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 /metricsprovides service metrics in Prometheus text-based format.