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.

Conventions

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.

Scope naming convention

OAuth 2.0 scopes defined in the Kaa IoT platform consist of at least two tokens separated by colon(s) (:). By convention, the first token designates the type of the protected resource, and the last token identifies the operation type (usually create, read, update, delete). Optional intermediary tokens may be used to further clarify the purpose of the scope in question. For example:

  • endpoint:read restricts read access to individual endpoint resources.
  • application:endpoint:create grants the right to create endpoints within a given application.

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). Scopes are enforced by many of the Kaa platform services, including EPR, EPTS, ECR, and others.

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.

Endpoint creation scope

Enforced by the EPR.

Scope Description
application:endpoint:create Creation of a new Kaa endpoint in a given application.

Endpoint filter management scopes

Enforced by the EPR.

Scope Description
application:endpoint-filter:create Creation of endpoint filters in a given application.
application:endpoint-filter:read Read access to endpoint filters created 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.

Endpoint metadata keys access scope

Enforced by the EPR.

Scope Description
application:endpoints-metadata-keys:read Read access to all existing endpoint metadata attribute keys in a given application.

Endpoint commands access scope

Enforced by the CEX.

Scope Description
application:endpoint-command:read Read access to all existing endpoint commands in a given application.

Timeseries configuration access scope

Enforced by the EPTS.

Scope Description
application:timeseries-config:read Read access to all existing endpoint time-series configurations in a given application.

Default endpoint configuration management scopes

Enforced by the ECR.

Scope Description
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.

Software OTA management scopes

Enforced by the OTAO.

Scope Description
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.

Tenant resource type

tenant resource type is used for restricting tenant-wide operations. One resource of this type (with the name tenant-system) is created per KeyCloak authentication realm (created for a Kaa tenant) by the tenant-manager.

Scope Description
tenant:application:create Creation of a new Kaa application.

Basic client credentials management scopes

The following scopes restrict access to basic (username / password) credentials, enforced by the Client Credentials Management service.

Scope Description
tenant:basic-credentials:create Creation of new basic client credentials.
tenant:basic-credentials:read Read access to basic client credentials.
tenant:basic-credentials:update Basic client credentials management.

X.509 client credentials management scopes

The following scopes restrict access to X.509 (TLS certificate) credentials, enforced by the Client Credentials Management service.

Scope Description
tenant:x509-credentials:create Creation of new X.509 client credentials.
tenant:x509-credentials:read Read access to X.509 client credentials.
tenant:x509-credentials:update X.509 client credentials management.

Kaa resource type

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

Application management scopes

The following scopes restrict application management access, enforced by the Kaa Tekton.

Scope Description
kaa:application:create Creation of a new Kaa application.
kaa:application:read Bulk read of Kaa application configurations.
kaa:application:update Bulk update of Kaa application configurations.

Tenant configuration access scope

The following scope restricts tenant-specific configuration access, enforced by the Kaa Tekton.

Scope Description
kaa:tenant:configuration:read Read access to tenant-specific configuration of any tenant in the system.

Tenant management scopes

The following scopes restrict tenant operations access, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:create Creation of a new tenant.
kaa:tenant:read Read access to all tenants.
kaa:tenant:update Write access to all tenants.
kaa:tenant:delete Tenant delete operation.

Tenant user management scopes

The following scopes restrict tenant user management access, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:tenant-user:create Creation of a new tenant user.
kaa:tenant:tenant-user:read Read access to tenant users.
kaa:tenant:tenant-user:update Write access to tenant users.
kaa:tenant:tenant-user:delete Tenant user delete operation.

Tenant backend client template management scopes

The following scopes restrict management access for backend client templates for tenant realm, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:realm-backend-client-template:create Creation of a new backend client template version.
kaa:tenant:realm-backend-client-template:read Read access to backend client template version.
kaa:tenant:realm-backend-client-template:update Write access to backend client template version.
kaa:tenant:realm-backend-client-template:delete Backend client template version delete operation.

Tenant frontend client template management scopes

The following scopes restrict management access for frontend client templates for tenant realm, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:realm-frontend-client-template:create Creation of a new frontend client template version.
kaa:tenant:realm-frontend-client-template:read Read access to frontend client template version.
kaa:tenant:realm-frontend-client-template:update Write access to frontend client template version.
kaa:tenant:realm-frontend-client-template:delete Frontend client template template version delete operation.

Tenant default resource management scopes

The following scopes restrict management access for tenant default resources, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:default-resource:create Creation of a new tenant default resource.
kaa:tenant:default-resource:read Read access to tenant default resource.
kaa:tenant:default-resource:update Write access to tenant default resource.
kaa:tenant:default-resource:delete Tenant default resource delete operation.

Tenant default resource scope mapping management scopes

The following scopes restrict management access for tenant default resource scope mappings, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:default-resource-scope-mapping:create Creation of a new tenant default resource scope mapping.
kaa:tenant:default-resource-scope-mapping:read Read access to tenant default resource scope mapping.
kaa:tenant:default-resource-scope-mapping:update Write access to tenant default resource scope mapping.
kaa:tenant:default-resource-scope-mapping:delete Tenant default resource scope mapping delete operation.

Tenant default resource version management scopes

The following scopes restrict management access for tenant default resource versions, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:default-resource-version:create Creation of a new tenant default resource version.
kaa:tenant:default-resource-version:read Read access to tenant default resource version.
kaa:tenant:default-resource-version:update Write access to tenant default resource version.
kaa:tenant:default-resource-version:delete Tenant default resource version delete operation.

Tenant default resource version mapping management scopes

The following scopes restrict management access for tenant default resource version mappings, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:default-resource-version-mapping:create Creation of a new tenant default resource version mapping.
kaa:tenant:default-resource-version-mapping:read Read access to tenant default resource version mapping.
kaa:tenant:default-resource-version-mapping:update Write access to tenant default resource version mapping.
kaa:tenant:default-resource-version-mapping:delete Tenant default resource version mapping delete operation.

Tenant identity provider management scopes

The following scopes restrict management access for tenant identity providers (IDPs), enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:idp:create Creation of a new tenant identity provider.
kaa:tenant:idp:read Read access to tenant identity provider.
kaa:tenant:idp:update Write access to tenant identity provider.
kaa:tenant:idp:delete Tenant identity provider delete operation.

Tenant realm template management scopes

The following scopes restrict management access for tenant realm templates, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:realm-template:create Creation of a new tenant realm template version.
kaa:tenant:realm-template:read Read access to tenant realm template version.
kaa:tenant:realm-template:update Write access to tenant realm template version.
kaa:tenant:realm-template:delete Tenant realm template version delete operation.

Tenant role management scopes

The following scopes restrict management access for tenant roles, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:role:create Creation of a new tenant role.
kaa:tenant:role:read Read access to tenant role.
kaa:tenant:role:update Write access to tenant role.
kaa:tenant:role:delete Tenant role delete operation.

Tenant role to scope mapping management scopes

The following scopes restrict management access for tenant role to scope mappings, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:role-scope-mapping:create Creation of a new tenant role to scope mapping.
kaa:tenant:role-scope-mapping:read Read access to tenant role to scope mapping.
kaa:tenant:role-scope-mapping:update Write access to tenant role to scope mapping.
kaa:tenant:role-scope-mapping:delete Tenant role to scope mapping delete operation.

Tenant role version management scopes

The following scopes restrict management access for tenant role versions, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:role-version:create Creation of a new tenant roles version.
kaa:tenant:role-version:read Read access to tenant roles version.
kaa:tenant:role-version:update Write access to tenant roles version.
kaa:tenant:role-version:delete Tenant roles version delete operation.

Tenant role version mapping management scopes

The following scopes restrict management access for tenant role version mappings, which used for tenant creation, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:role-version-mapping:create Creation of a new tenant role version mapping.
kaa:tenant:role-version-mapping:read Read access to tenant role version mapping.
kaa:tenant:role-version-mapping:update Write access to tenant role version mapping.
kaa:tenant:role-version-mapping:delete Tenant role version mapping delete operation.

Tenant scope management scopes

The following scopes restrict management access for tenant scopes, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:scope:create Creation of a new tenant scope.
kaa:tenant:scope:read Read access to tenant scope.
kaa:tenant:scope:update Write access to tenant scope.
kaa:tenant:scope:delete Tenant scope delete operation.

Tenant scope version management scopes

The following scopes restrict management access for tenant scope versions, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:scope-version:create Creation of a new tenant scope version.
kaa:tenant:scope-version:read Read access to tenant scope version.
kaa:tenant:scope-version:update Write access to tenant scope version.
kaa:tenant:scope-version:delete Tenant scope version delete operation.

Tenant scope version mapping management scopes

The following scopes restrict management access for tenant scope version mappings, which used for tenant creation, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:scope-version-mapping:create Creation of a new tenant scope version mapping.
kaa:tenant:scope-version-mapping:read Read access to tenant scope version mapping.
kaa:tenant:scope-version-mapping:update Write access to tenant scope version mapping.
kaa:tenant:scope-version-mapping:delete Tenant scope version mapping delete operation.

KeyCloak server management scopes

The following scopes restrict management access for Keycloak servers, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:keycloak-server:create Creation of a new KeyCloak server.
kaa:tenant:keycloak-server:read Read access to KeyCloak server.
kaa:tenant:keycloak-server:update Write access to KeyCloak server.
kaa:tenant:keycloak-server:delete KeyCloak server delete operation.

Tenant subscription management scopes

The following scopes restrict management access for tenant subscriptions, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:tenant-subscription:create Creation of a new tenant subscription.
kaa:tenant:tenant-subscription:read Read access to tenant subscription.
kaa:tenant:tenant-subscription:update Write access to tenant subscription.
kaa:tenant:tenant-subscription:delete Tenant subscription delete operation.

Package type management scopes

The following scopes restrict management access for packages types, enforced by the Kaa Tenant Manager.

Scope Description
kaa:tenant:package-type:create Creation of a new package type.
kaa:tenant:package-type:read Read access to package type.
kaa:tenant:package-type:update Write access to package type.
kaa:tenant:package-type:delete Package type delete operation.

UI settings management scope

The UI settings management scope is enforced by Kaa Web Dashboard.

Scope Description
kaa:ui:update Management of UI settings for all tenants (banner, logos, etc).