Security
The ClearBlade Platform has multiple levels of Accounts with each level having different scopes:
- System Level Accounts - System level scope
- Developer Account - Developer Account level scope
Admin Account - Instance level scope
System Level Accounts
2 types of accounts fall under System Level Accounts:
The user or device can have the following CRUD access capabilities:
- Code
- Collections
- Adapters
- Portals
- Roles
- Users
- Devices
- Edges
Message
User Account
Scope: System-Level
This is an account for a user and requires using an e-mail account as a primary method for identification. A user in a system has system-level access. The user or device can have the following capabilities:
- CRUD Access for Code, Collections, Adapters, Portals, Roles, Users, Devices, Edges, Message
User Authentication
The following are required for a User to authenticate:
Key | Value | Example |
---|---|---|
Username | E-mail of user | example@clearblade.com |
Password | Password | SX93f7f+ |
System Key | Unique autogenerated key for your system | bd97e7a40bdcc597baf6adfc867e |
System Secret | Secret value for your IoT System | BD97E7A40BC0B587BCAFFFA9A005 |
Device Account
Scope: System-Level
This is an account for a machine enabling M2M (Machine-to-Machine) communication. In place of an e-mail account, a device has a device name
that unique within a given System.
Device Authentication
The following are required for a Device to authenticate:
Key | Value | Example |
---|---|---|
Device Name | E-mail of user | example@clearblade.com |
Device Key | Single Key, Rotating Key, or Certificate | k9IOtxWPEWVOyJ+rt1jvNYDg |
System Key | Unique autogenerated key for your system | bd97e7a40bdcc597baf6adfc867e |
System Secret | Secret value for your IoT System | BD97E7A40BC0B587BCAFFFA9A005 |
Service Account
A Service Account is a dedicated account with unique token attributes. The token is autogenerated by a developer, and the token has a custom time-to-live, set to infinite by default. This allows an adapter, a program, or an integration to connect with an appropriately token lifecycle. Both 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. Upon providing user or device credentials, a token is generated for use with subsequent requests.
Protocols
Authentication is available via
System Level Credentials
ClearBlade Platform is multi-tenanted, meaning there are more than one IoT Systems running in a given platform. As a result, all authentication requires:
Key | Value | Example |
---|---|---|
System Key | Unique autogenerated key for your system | bd97e7a40bdcc597baf6adfc867e |
System Secret | Secret value for your IoT System | BD97E7A40BC0B587BCAFFFA9A005 |
JWT Tokens
When a user/developer goes through the authentication process, JWT tokens are returned as a default token.
Authentication Override
In order to support integrations with a pre-existing identify management system, Authentication Override allows for 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 directly to a user or device. Each user and device can have multiple roles.
Roles
A developer assigns permissions to a role for each of the following 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.
Note: If there is a problem accessing certain assets or performing functions, make sure the role as permissions
Default Roles
There are three default roles that have special permissions:
Role | Behavior |
---|---|
Authenticated | All new users and devices are auto-assigned this role |
Anonymous | All anonymous users are auto-assigned this role |
Administrator | No one is auto-assigned. It is an empty, customizable role |
Sessions
There is a log of active sessions 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 either set a predefined value as the anon token TTL or set it ‘infinite’.
Developer Account
Scope: Developer Account
A developer-level account has one or more systems on an instance of ClearBlade platform. This account has the following capabilities: - Modify system and its assets - Modify list of developer collaborators who can modify system - Update one’s own password - Create Support Tickets
Now, let’s address your curiosity by answering the following:
> How to become a developer
> Authentication for developer
How to become a developer?
A normal developer working on https://platform.clearblade.com
can create a free account by signing up without any registration key. A ClearBlade customer working on their own instance requires the user to know the Registration Key
for that instance in order to signup and create an account.
Authentication for Developer
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 the following additional capabilities atop Developer Account:
- Add/Remove developers for a system
- Update a developers’ password
- Update Owner of a System
- Enable/Disable a System
- Access to a system’s analytics
- Update the license key of the instance
- Update Admin Account for an instance
Now, let’s address your curiosity by answering the following:
> How to become an Admin?
> Authentication for Admin
How to become an Admin?
A developer working on https://platform.clearblade.com
cannot get admin-level access. Though, a ClearBlade customer can submit a support desk ticket for admin-level access to their respective instance. Also, if an admin exists for that instance, then the respective admin can grant any developer admin-level access.
Authentication for Admin
Authentication is same as Developer Account
FAQ
How do I add a developer to a system?
- Click on “Info” in the side navigation
- Choose “System Settings”
- Click the “Access” Tab
- Click the “+” icon next to “Developers”
- Type in the developer’s valid e-mail address
- Click “Update”
Can users manage roles and change passwords of other users?
Yes - in version 8.0.0 and newer. Users with a role configuration, which includes User Management Permissions, can perform this task.
Resetting the password for the current user also resets the UserToken
to prevent the user to make subsequent requests until the ClearBlade instance is re-initialized with a new user token that can then get set for the user within the portal.
- If a user has an MQTT client connected with a device token and that device token expires while the connection is open, what is the expected behavior?
The client stays connected.
- What if the user attempts to publish with the 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.