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.

• 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

• Certificate authorities:

  • You can use your own.
  • If you are using factory configurator utility (FCU), you can use it as a CA. If you are not using FCU and would like to learn more, please contact us.

  More information for both options is available in the Certificate sources section.

• The device must use production credentials. Developer credentials are not supported.

• The device must be configured for bootstrapping. The direct LwM2M flow is not supported.

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.

   • Provision the device with the configuration 'first-to-claim=true'. The configuration affects the provisioning process:

     • FCU returns an enrollment ID for the device.

     • The device's provisioned bootstrap URL does not contain an account ID (aid). This means the device cannot be used without being claimed.

   • You need to provide the account administator the following items:

     • The device enrollment ID you received from FCU.

     • The CA certificate you used to create the device certificate. The CA certificate allows the device to connect to the bootstrap server (which it must do before it can be claimed).

   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:

   • Provision the device with the configuration first-to-claim=true.

   • Configure the Bootstrap server URI without the aid part at the end of the URI.

     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 first-to-claim = true.

   • 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:

2. 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.

3. 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 elrollment and GET /v3/device-enrollments-bulk-uploads/{id} for how to follow the status of the enrollments.

Device onboarding:

4. Power on the device.

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

6. 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.

7. The device acknowledges receipt.

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

9. The device registers with the LwM2M server.

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

First-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).

First-to-Claim troubleshooting

For more information on:

• Uploading a certificate: see POST /v3/trusted-certificates
• Using the Enrollment API: see POST /v3/device-enrollments.

The following table lists the error codes and messages seen on the device side if claiming or enrollment fail.