CCM

Client Credentials Management service (CCM) serves for the authentication of clients. CCM supports:

  • Client basic authentication by username/password combination
  • Client X.509 authentication using TLS certificates.

CCM provides REST APIs to manage client credentials and their states. CCM maintains a credentials state machine summarized in the following diagram.

CCM credentials state FSM

Credentials can be in one of the following states:

  • Inactive is the initial state for newly provisioned credentials that has not been used to authenticate a client.
  • Active is the state credentials automatically move to after they were first used for client authentication. Credentials can be suspended or revoked from the active state.
  • Suspended state is for temporarily disabled credentials. CCM service will reject authentication requests with suspended credentials. Suspended credentials can be re-activated.
  • Revoked state is the terminal state for credentials that are no longer valid.

CCM persists all credentials-related data to PostgreSQL.

CCM never stores passwords. Irreversible salted hash is stored for credentials verification instead. CCM uses Provos and Mazières’s bcrypt adaptive hashing algorithm for this purpose.

X.509 certificates

CCM provides API for issuing client X.509 certificates. A typical certificate chain is illustrated below.

CCM X.509 certificates CA chain

  • Root CA is an optional (but recommended) CA. It is not available to CCM, and you would usually keep it offline. You use Root CA to issue the platform instance CA.
  • Kaa platform instance CA is the CA made available to CCM together with the private key. CCM uses this CA to issue tenant root CAs.
  • Tenant root CA is a CA that gets automatically issued to each individual tenant. CCM safely stores both the certificate and the private key in Vault and uses this CA to issue client certificates.
  • Client certificate is the actual certificate tenant devices connect with. CCM issues these certificates using Vault in response to a REST API call. It does not store the client certificate private key, though—only the certificate metadata.

Interfaces

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

CCM interfaces diagram

Credentials management

CCM provides a REST-based interface for:

  • provisioning new credentials
  • transitioning credentials state
  • retrieving credentials information

Client authentication protocol

CCM exposes a NATS-based protocol for client authentication using basic and X.509 credentials. The protocol design is available from 22/CAP.

Kaa Tenant Manager integration

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

Management interface

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