Documentation

Mistake on this page? Email us

First-to-Claim by enrollment list

Account assignment options for devices

When a device establishes a connection to Device Management for the first time (see onboarding), the Device Management service connects the device to an account following one of two paths:

  • The manufacturing phase pre-assigned the device to an account. In this case, the factory floor provisioning includes account identification in the bootstrap configuration, which associates the device with a specific account. This option works well when you are manufacturing your own devices and therefore know which account the devices need to connect to.

    For more information, see Bootstrap configuration section of the Pelion Device Management Factory Provisioning documentation site.

  • First-to-Claim by enrollment list manufactures devices without binding them to an account (that is, the device is not provisioned with account identification on the factory floor). Instead, the device is provided with an enrollment identity that it uses in the onboarding phase to associate itself with any account (the "claiming account").

    An unenrolled device can be claimed by anyone who can obtain the device enrollment identity and has the OEM's CA certificate.

Certificates and registration flows for enrolled devices

The process from production to onboarding

Device manufacturing:

  1. In the factory, the device is provisioned to be first-to-claim and the enrollment ID is generated for the device.

    Using FCU to provision a first-to-claim device:

    FCU can configure the device to be First-to-claim and provide the enrollment ID.

    Generating the device enrollment ID without FCU:

    If your factory doesn't use FCU, please follow these steps to provision the device and generate its enrollment ID:

    • Set mbed.FirstToClaim=1, as described on the Pelion Device Management Factory Provisioning documentation site.

    • Configure the Bootstrap server URI without the aid part at the end of the URI, as described on the Pelion Device Management Factory Provisioning documentation site.

      To get the bootstrap URI from the Device Management Portal, navigate to Device identity -> Server (remember to remove the ending: ?aid=01591...000).

      Note: The device is also provisioned with a device certificate. You need to provide the corresponding CA certificate (used to create the device certificate) to the account administrator.

    • To generate the enrollment ID, take a fingerprint from the device certificate and add the version prefix.

      The fingerprint is calculated as SHA256 hash of the DER format of the device bootstrap certificate. The fingerprint is encoded as hexadecimal in ASCII to provide simple integration to existing tools, such as OpenSSL. An example output of fingerprint:

      AD:1E:CE:37:C9:A1:76:6F:C0:13:AD:91:29:41:3E:27:83:97:4A:42:4C:71:B7:F0:A4:B1:72:E4:03:18:B6:30

      Add the version prefix A- to the fingerprint to complete the enrollment ID. See First-to-Claim enrollment ID versioning.

      The final enrollment ID now looks like this:

      A-AD:1E:CE:37:C9:A1:76:6F:C0:13:AD:91:29:41:3E:27:83:97:4A:42:4C:71:B7:F0:A4:B1:72:E4:03:18:B6:30

    The device shipment must contain the following:

    • The device, including the device certificate, and configured with mbed.FirstToClaim=1.

    • The CA certificate the device certificate was created from.

    • The enrollment ID. There are different ways of providing it, such as a QR code on the package.

Account administration:

  1. Upload the CA certificate as one of the trusted CAs, and mark it for enrollment. Note that you only need to do this once for each CA.

    • When using Device Management Portal, navigate to Device identity -> Certificates. Fill in the certificate info and select the certificate file to upload. In the second step of certificate upload, select the certificate usage Enrollment.

    • To upload the certificate using the REST API, set the enrollment_mode to true in TrustedCertificateReq.

  2. Enroll the device using either the Device Management Portal or the /v3/device-enrollments API. You need the device's enrollment ID for this step.

    • When using the portal, navigate to Device directory -> Enrolling Devices. Select Enroll device and enter the device's enrollment identity.

    • Both the portal and the REST API provide bulk handling of the enrollments using a .csv file. See /v3/device-enrollments-bulk-uploads for how to do bulk enrollment and GET /v3/device-enrollments-bulk-uploads/{id} for how to follow the status of the enrollments.

Device onboarding:

  1. Power on the device.

  2. The device connects to the Device Management bootstrap server.

  3. The Device Management bootstrap server gives the device bootstrap credentials, including the account ID.

    Because the device doesn't have a pre-assigned account, the bootstrap server checks the device against the existing enrollments. If it finds a match, it assigns the device to the account. The process also writes the account ID (as aid) to the device, so that following bootstraps will automatically reach the correct account.

    Note: If the server cannot find the device on the enrollment list, it rejects the device (which then fails to complete onboarding). Add the device's enrollment identity to the enrollment list and restart to device to initiate another bootstrap attempt.

  4. The device acknowledges receipt.

  5. The bootstrap server gives the device LwM2M server credentials to complete onboarding.

  6. The device registers with the LwM2M server.

  7. The device is registered to Device Management, and the account that owns the device can use it in every normal cloud workflow.

overviewFirst-to-Claim by enrollment list - user flow

Transferring ownership of First-to-Claim devices

A device that had been manufactured for ownership claiming, and which has already been associated with an account through the onboarding process, can be transferred to a different account:

  1. Remove the enrollment ID of the device from your account's enrollment:

    • To remove using the APIs, call DELETE /v3/device-enrollments/{id}.

    • To remove using the Device Management Portal, navigate to Device Directory -> Enrolling devices. Select the enrollment ID, and in Actions, select Cancel enrollment.

  2. To return the device to the original state (without an assigned account), your device application needs to call factory reset.

  3. Deliver the CA certificate and enrollment identity to the new owner.

The new owner can then claim device ownership by adding its enrollment identity to their Device Management account's enrollment list. Remember that ownership transfer only works on devices that were originally manufactured for ownership claiming.

First-to-Claim enrollment ID versioning

The enrollment ID must contain the version information in front of the fingerprint. The table below describes the available versions. Read more on the enrollment ID notation (Generating the device enrollment ID without FCU).

Version Description
A Initial version of device ownership claiming (First-to-Claim). Supports device ownership claiming and ownership transfer. Currently, the only version supported is "A".

First-to-Claim troubleshooting

For more information on:

Error codes and messages seen on the device side if claiming or enrollment fails:

Error/message Possible reason Corrective action
Secure Connection Failed. The CA certificate has not been uploaded. Upload the OEM provided certificate to your account. See Device manufacturing.
Corresponding trusted certificate not in account. The CA certificate is not a trusted CA on your account. Upload the OEM provided CA certificate to your account as a trusted CA. See Device manufacturing.
Enrollment ID not registered. The enrollment identity is not found in the database. Add the device to your enrollment list. See Account administration.
Account device quota reached. An account-specific device limit has been reached and no more devices can be added to the account. Remove any unneeded devices or upgrade the account.
Duplicated device endpoint name. A device with the same endpoint name exists in system. The endpoint name needs to be unique in the context of an account. In this case, there is a device with the same endpoint name, but with a different certificate. Provision a unique endpoint name. For more information, see Device identity.
Internal error #1 to #10 If issues persist, contact Pelion support and provide the Device Management Client logs and CoAP error code in the issue description.