API security

Prerequisites

To get the most out of the below documentation, we recommend that you:

Introduction

The Kaa platform is based on multiple microservices that implement various aspects of the overall platform functionality. Many of these microservices manage resources that require access authentication and authorization. Kaa API security is implemented based on OAuth 2.0 and the User-Managed Access (UMA).

Kaa microservices that require access authorization act as resource servers. The user authentication, access authorization, and resource management is implemented in a separate, OAuth 2.0- and UMA-compliant, auth server. Kaa uses KeyCloak as the default auth server implementation.

To perform an operation on a resource, the requesting user must be authenticated with the auth server, and granted the necessary scopes. All Kaa services support bearer token HTTP authentication scheme on exposed REST APIs.

Resource naming convention

Protected resources have two unique identifiers in auth server: ID and name. By convention, Kaa services do not set resource IDs, allowing the auth server to generate IDs as it sees fit.

To ensure the uniqueness of resource names, the following pattern is applied:

<type>-<handle>

where:

  • type identifies the type of the protected resource (e.g. application, endpoint, dashboard, etc.);
  • handle is a unique handle of the protected resource, chosen at the discretion of the resource server (e.g. application name, endpoint ID, dashboard UUID, etc.).

Examples of the resource names that follow the above pattern: application-building, endpoint-0aaf85d7-da91-4b46-b6da-dd763ee49c4d, etc.

OAuth 2.0 resource types and scopes

Kaa services use several resource types to manage access authorization to corresponding resources. Below is a summary of existing resource types and their associated OAuth 2.0 scopes.

Endpoint resource type

endpoint resource type is used for restricting access to Kaa endpoints. These resources are managed by the Endpoint Register service (EPR).

Endpoint ID is used as a resource handle to construct resource names according to the resource naming convention.

Scope Description
endpoint:read Read access to endpoint and its associated data: tokens, metadata attributes, configuration, time-series, etc.
endpoint:update Write access to endpoint and its associated data.
endpoint:delete Endpoint delete operation.

Application resource type

application resource type is used for restricting access to Kaa applications. These resources are managed by the Kaa Tekton service.

Application name is used as a resource handle to construct resource names according to the resource naming convention.

Scope Description
application:read Read access to application, its associated metadata, and service instance configurations.
application:update Write access to application, its associated metadata, and service instance configurations.
application:delete Application delete operation.
application:endpoint:create Creation of a new Kaa endpoint in a given application.
application:endpoint-filter:read Read access to endpoint filters created in a given application.
application:endpoint-filter:create Creation of endpoint filters in a given application.
application:endpoint-filter:update Update of endpoint filters in a given application.
application:endpoint-filter:delete Delete operation on endpoint filters in a given application.
application:endpoints-metadata-keys:read Read access to all existing endpoint metadata attribute keys in a given application.
application:timeseries-config:read Read access to all existing endpoint time-series configurations in a given application.
application:endpoint-config:read Read access to default endpoint configuration in a given application.
application:endpoint-config:update Write access to default endpoint configuration in a given application.
application:endpoint-config:delete Delete operation on default endpoint configuration in a given application.
application:software:read Read access to over-the-air software definitions in a given application.
application:software:update Write access to over-the-air software definitions in a given application.

Dashboard resource type

dashboard resource type is used for restricting access to web dashboards. These resources are managed by the Kaa Web Dashboard service (WD).

Dashboard UUID is used as a resource handle to construct resource names according to the resource naming convention.

Scope Description
dashboard:read View access to a given web dashboard.

Kaa resource type

kaa resource type is used for restricting platform-wide operations. Only one resource of this type (with name kaa-system) is created per Kaa platform instance by the Kaa installer.

Scope Description
kaa:application:create Creation of a new Kaa application.
kaa:application:update Bulk update of Kaa application configurations.
kaa:client-credentials:read Read access to client username/password credentials.
kaa:client-credentials:create Creation of new client username/password credentials.
kaa:client-credentials:update Client username/password credentials status management.
kaa:client-certificates:read Read access to client certificates.
kaa:client-certificates:create Creation of new client certificates.
kaa:client-certificates:update Client certificates status management.