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:
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:
Key | Value | Example |
---|---|---|
Username | User email | |
Password | Password | SX93f7f+ |
System Key | Your system’s unique autogenerated key | bd97e7a40bdcc597baf6adfc867e |
System Secret | Your IoT system’s secret value | BD97E7A40BC0B587BCAFFFA9A005 |
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:
Key | Value | Example |
---|---|---|
Device Name | Device name | my-device |
Device Key | Single key, rotating key, or certificate | k9IOtxWPEWVOyJ+rt1jvNYDg |
System Key | Your system’s unique autogenerated key | bd97e7a40bdcc597baf6adfc867e |
System Secret | Your IoT system’s secret value | BD97E7A40BC0B587BCAFFFA9A005 |
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:
Key | Value | Example |
---|---|---|
System Key | Your system’s unique autogenerated key | bd97e7a40bdcc597baf6adfc867e |
System Secret | Your system’s secret value | BD97E7A40BC0B587BCAFFFA9A005 |
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:
Role | Behavior |
---|---|
Authenticated | All new |
Anonymous | All |
Administrator | No one is auto-assigned. It is an empty, customizable role |
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:
Go to your systems.
Click the system you wish to view.
Click Secrets on the left menu.
Click Add Secret.
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?
Click Info in the side navigation.
Choose System Settings.
Click the Access Tab.
Click the + icon next to Developers.
Type in the developer’s email.
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.