Skip to content

Self checkin

By default, Kamea targets a use case in which users must be invited by already existing users in order to use the platform. But many use cases requires users to create their own accounts without any external intervention, and to claim devices from a set of available devices.

Example: John buys a connected lightbulb from the ACME company. John then goes on the ACME website, fills a form to create his user account by providing his credentials (email and password), and enters the serial number of his connected lightbulb in the website to declare that it's now in it possession. Finally, John can control his lightbulb through the ACME cloud.

Kamea covers this use case with the self checkin feature.

Note: All the API endpoints mentioned in this page are fully documented in the API Swagger documentation. This page will not describe all their parameters, behaviors and return codes in detail.

Claimable folder

The end goal of users self registering on the platform is to claim a device as their own. Obviously, when a device has been claimed by a user, it must be impossible to claim it again, whether it is from the same user or from another one.

Consequently, devices must be marked as available in Kamea in order to be claimed by users. If a device is not available, it cannot be claimed. When a Tenant is configured to allow self-checkin, it must contain a Folder dedicated to containing all of the available devices. Being put in this folder is what marks the device as available. Devices in other folders cannot be claimed.

The expected workflow for customers is to create and provision their devices in Kamea during or just after the manufacturing. The devices should then be moved to the claimable folder once they can be bought by customers.

User check-in & personal folder

Check-in can be done in two different ways, which depends on the expected user experience: - Through the API: use the [...]/checkin endpoint. It is expected that users will do that through a custom mobile application or a dedicated front-end. Among all the expected parameters, an email address and a password are expected. This approach has a drawback: it forces the user to input their credentials twice. First, in the client application to provide it the required parameters for the endpoint, and then on the identity provider login page. Since the IDP has its own domain name, it's not possible to provide it the user's credentials. - Through the identity provider (if supported): use the designated sign-up page. In that case, after having completed the sign-up, the user will be redirected to the client app, and obtain an access token. At this stage, Kamea is not aware of the user's existence. Consequently, the client application has to register the newly created user by calling the [...]/authenticated-checkin endpoint with the access token in the request headers. If the user isn't registered on the API, they'll receive 401/403 (access denied) errors on all API calls, because they won't have any access right.

In both cases, the API creates the user in Kamea's database. In the first case ony, it also creates their account on the linked identity provider (Azure Active Directory B2C by default, but others can be used).

A folder is also created in the specified tenant, named after the user unique ID. It is the user's personal folder, and will contain all the devices claimed by the user. Unless the user is later given additional access rights, they will only see the devices that are in their personal folder.

Finally, the user is given access rights to the claimable folder and to its personal folder through two role assignments. Check this section for more details.

Claiming devices

To claim a device, the user must call the API [...]/claim endpoint. A device ID or serial number must be passed as parameter to identify the claimed device. If the device is available, it is removed from the claimable folder and added to the user's personal folder. The only way to make it available again is to move it back to the claimable folder.

In the default scenario, there is no way to prove that the user is in possession of the claimed device. Consequently, the value used to retrieve the devices, whether it is the serial number or the ID, must be unpredictable. If it is not the case, nothing prevents a malicious user from claiming devices that are not theirs. Rate limiting is used in the API to limit brute-forcing on the claim endpoint. To significantly reduce the risks, a good solution would be for instance to prove the physical ownership of the device through a manual action or a cryptographic challenge. That requires the firmware and hardware to handle this scenario.

Users can return devices to the claimable folder by calling the API [...]/devices/return endpoint.

Technical

Activation / deactivation

Self-checkin is disabled by default, and must be enabled by tenant. Before enabling it, create the claimable folder. Its name is not important, but its ID must be noted. To enable this feature, call the endpoint PUT [...]/checkin/configuration. The claimable folder ID is expected in the parameters. To disable this feature, call the endpoint DELETE [...]/checkin/configuration.

Access rights

Enabling the feature also creates the Personal folder owner role in the platform if it does not already exist. Note that if it already exists, it will not be updated. Since roles are shared among all tenants, it means that if self-checkin has been enabled on a tenant, and if a user has manually modified the create role, enabling the feature on another tenant will not reset the role to its initial configuration. It will keep its current set of permissions.

The Personal folder owner is given to checked in users on their personal folder. It includes those permissions by default:

-   `Device.Read`
-   `Device.Update`
-   `Device.Move Folder`
-   `Device Configuration.Read`
-   `Device Configuration.Write`
-   `Device Configuration.Write-on-behalf`
-   `Device Metadata.Read`
-   `Device Metadata.Write`
-   `Device.Send command`
-   `Folder.Read`
-   `Folder.Read event`

By default, users have limited permissions on their devices. For instance, they cannot (de)provision the device. This might be an issue if Kamea is used in a situation where the device is sold without being provisioned. In that case, it is advised to modify the permissions of the Personal folder owner role.

Limitations

Here are the known limitations of the feature that are prone to change in future releases:

  • Deleting a user does not delete their personal folder.
  • Deactivating the self checkin feature on a tenant does not remove the claimable folder.
  • Returning a device to the claimable folder keeps the device history. Meaning that the next user to claim it will have access to all of its data.