Security

The ClearBlade Platform has multiple account levels, with each having different scopes:

• System level accounts: System level

• Developer account: Developer account level

• Admin account: Instance level

System level accounts

Two account types fall under system-level accounts:

• User account

• Device account

The user or device can have these CRUD access capabilities:

• Code

• Collections

• Adapters

• Portals

• Roles

• Users

• Devices

• Edges

• Message

User account

Scope: System-level

This is a user account and requires using an email as a primary method for identification. A user in a system has system-level access.

User authentication

The following are required for a user to authenticate:

Device account

Scope: System-level

This is an account for a machine enabling M2M (machine-to-machine) communication. In place of an email account, a device has a unique device name within a given system.

Device authentication

The following are required for a device to authenticate:

Service account

A service account is a dedicated account with unique token attributes. A developer autogenerates the token with a default time-to-live set to infinite. This allows an adapter, program, or integration to connect with an appropriate token lifecycle. User and device accounts can be configured as service accounts.

Mark the Service Account? box when adding or editing a user or device to create the service account. The token should appear in the user or device grid.

System-level authentication

Authentication is built upon an OAuth 2 model. A token is generated for use with subsequent requests upon providing user or device credentials.

Protocols

Authentication is available via REST and MQTT.

System-level credentials

The ClearBlade Platform is multi-tenanted, meaning more than one IoT system runs in a given platform. As a result, all authentication requires:

JWT tokens

When a user/developer goes through the authentication process, JWT tokens are returned as a default token.

Authentication override

To support integrations with a pre-existing identity management system, authentication override allows custom logic to define whether or not a user should be granted an OAuth token.

System-level authorization

Role-based authorization is available for all user and device accounts. Permissions are applied to roles rather than to a user or device. Each user and device can have multiple roles.

Roles

A developer assigns permissions to a role for each of these assets:

• Code

• Collections

• Adapters

• Portals

• Roles

• Users

• Devices

• Edges

• Messages

Each role has CRUD permissions for these assets.

For example, an administrator role may have CRUD access to a code service called EnablePremiumFeatures that is not accessible by an authenticated user.

A developer can create any number of custom roles.

If there is a problem accessing certain assets or performing functions, update roles within Permissions.

Default roles

Three default roles have special permissions:

Sessions

There is an active session log to keep track of users and devices. Users are tracked with user IDs, and devices are tracked with device keys. The log also includes a timestamp of when the session token is issued.

Refresh tokens

Refresh tokens give new access tokens without a username and password. Their expiry is twice the access token expiry. If your instance is set to infinite expiry for user/device/developer tokens, refresh tokens become unavailable for security purposes.

Refresh tokens workflow

Anonymous session

This feature allows users to set a separate token TTL for anon tokens. Users can set a predefined value as the anon token TTL or infinite.

Secrets

Secrets allow for a secure way to store private information. Code services can use secrets to securely integrate with third-party APIs without disclosing your credentials. To learn more, check out the docs.

Follow these steps to add secrets within the console:

1. Go to your systems.

2. Click the system you wish to view.

3. Click Secrets on the left menu.

4. Click Add Secret.

5. Fill out the information and click Create.

Developer account

A developer-level account has one or more systems on a ClearBlade Platform instance. This account has these capabilities:

• Modify the system and its assets

• Modify the list of developer collaborators who can modify the system

• Update one’s password

• Create support tickets

Becoming a developer

A developer working on https://platform.clearblade.com can create a free account by signing up without a registration key. A ClearBlade customer working on their instance requires the user to know the registration key for that instance to sign up and create an account.

Developer authentication

A user can be authenticated as a developer by

• Logging into the web console, such as platform.clearblade.com

• Using REST API

Admin account

Scope: Instance level

A developer account can be granted admin-level access with these additional capabilities:

• Add/remove system developers

• Update a developer's password

• Update system owner

• Enable/disable a system

• Access to a system’s analytics

• Update the instance’s license key

• Update the instance’s admin account

Becoming an admin

A developer working on https://platform.clearblade.com cannot get admin-level access. A ClearBlade customer can submit a support desk ticket for admin-level access to their respective instance. If an admin exists for that instance, the respective admin can grant any developer admin-level access.

Admin authentication

Authentication is the same as a developer account.

FAQ

• How do I add a developer to a system?

  1. Click Info in the side navigation.

  2. Choose System Settings.

  3. Click the Access Tab.

  4. Click the + icon next to Developers.

  5. Type in the developer’s email.

  6. Click Update.

• Can users manage roles and change other users' passwords?

Yes, in version 8.0.0 and newer. Users with a role configuration, which includes User Management permissions, can perform this task.

Resetting the current user’s password also resets the UserToken to prevent the user from making subsequent requests until the ClearBlade instance is re-initialized with a new user token that can be set for the portal’s user.

• What is the expected behavior if a user has an MQTT client connected with a device token that expires while the connection is open?

The client stays connected.

• What if the user attempts to publish with an open connection with an expired token?

If they already have an open MQTT connection, the publish should succeed. The platform only checks the token on the connect packet.