KPC

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 kaa.kpc.transports.mqtt.tls.cert-file. It can be used as a trust store of the clients connecting over TLS.

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 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
Plain MQTT Asynchronous - + - +
MQTT/TLS Asynchronous TLS + + +
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.

Client authentication

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 <username>@<tenant ID>. 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.

Endpoint identification

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.

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, 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.