Skip to content

Provisioning Service

The Provisioning Service allows you to securely provision your Nordic Semiconductor devices over-the-air to nRF Cloud, your own cloud, or another service. This enables you to perform late provisioning after you have identified the deployment target. You do not need to run deployment-specific production batches and you can manufacture generic devices.

Late provisioning

Using the Provisioning Service, you must claim the device as your own. Once you have claimed the device, only authorized members of your team can add the device to provisioning groups, define the device's provisioning configuration, create provisioning rules that apply to the device, and securely provision it.

Late provisioning enables you to provision the device based on its proximity to the nearest service deployment, or if selling devices to a third party, provision the device to the customer's own services. You can also re-provision devices and rotate keys or, for example, redirect devices to a new server deployment.

Note

The Provisioning Service is in beta and under continuing development.

Secure provisioning

Secure provisioning allows you to claim a device as your own and provision the device remotely. It allows you to define a device's provisioning configuration, define rules that apply to multiple devices, control who within your team can provision the device, and block or unclaim the device.

Note

Secure provisioning is separate from onboarding, which provisions the device directly to nRF Cloud services. You can use the Secure Provisioning service to onboard a device to any cloud service, including nRF Cloud.

Requirements

To use the Provisioning Service, you need the following:

Access

Access

The Provisioning Service is available to editor, admin, and owner roles.

All users on a team other than viewers may claim devices. Admins and owners can view and edit configurations for devices claimed by editors.

Devices claimed by an admin or owner are not visible to editors or viewers.

Some operations are also available to viewers. See the API documentation for more information.

Only admins and owners can create and manage provisioning rules. Editors may view which provisioning rules have been created within their teams.

Process

This section describes the general process for claiming and securely provisioning a device. For detailed, step-by-step instructions, see the links in the See next section of this page.

Claim the device in the manufacturing phase. When a device is deployed, the provisioning configuration is set for the device based on the deployment target.

The following sequence describes the process to claim devices and configure them for provisioning:

  1. Create an identity attestation token.
  2. Claim your device.
    • You can claim the device later based on stored tokens or request the token from the device.
  3. Flash firmware that includes the nRF Cloud provisioning library to the device.
  4. Create a provisioning configuration for the device using either the nRF Cloud portal or APIs, or add commands to multiple devices using provisioning rules.
    • You need the device's UUID to set the provisioning configuration for the device. It may be available through a QR code, or by other means depending on the end product.
  5. Activate the rule or configuration.
  6. When the device is powered on, it connects to the nRF Cloud Provisioning Service to check whether there are any commands available. The device gets the commands and executes them.
  7. Monitor device progress and address any errors.

After successful execution of provisioning commands, the device is provisioned and can connect to the cloud service.

Device status during the secure provisioning process

A claimed device may have one of the following statuses:

  • READY: The device has been claimed and is ready to be provisioned.

  • PROVISIONING: The device has connected to the Provisioning Service and the provisioning process is in progress. You can monitor the status of the individual commands.

  • AWAITING: The device has already received all commands defined in its provisioning configuration, but the provisioning process is not yet finished. Add more commands to the configuration, along with the finished command.

  • PROVISIONED: The device has received all commands successfully and acknowledged the last finished command.

  • ERROR: The device has responded to a provisioning command with an error. The provisioning process is suspended and requires the user to intervene manually.

  • BLOCKED: The device is blocked and will not receive any new provisioning commands. Unblock it first if you want it to be provisioned.

Provisioning groups

Provisioning groups work the same as other device groups, but are specific to the Provisioning Service. Add devices to a provisioning group by defining one or more tags during or after device claiming. You can use provisioning groups to organize your claimed devices for secure provisioning and to apply provisioning rules.

Provisioning groups are separate from other device groups in nRF Cloud.

Provisioning configuration

A claimed device can have a provisioning configuration, which is a sequence of commands to execute upon provisioning. These commands define which types of tokens and other authorization mechanisms the device generates and uses to connect to the service. Using provisioning commands, you can set the device up to execute provisioning remotely.

With a provisioning configuration in place, the device receives the commands when it connects to the Provisioning Service. The device executes the commands according to the configuration until there is an error or all commands are executed. If the device encounters an error, you must decide whether to attempt the command again, ignore the error and skip the command, or change the provisioning configuration.

The following illustration shows a simplified example of how a key generation command is added to the device's provisioning configuration and processed further. When the device connects to the Provisioning Service, it gets the command in return. The nRF Device provisioning library carries out the provisioning commands in the device. In a real-life case, there would be more commands to, for example, set the server certificate, create and sign the client certificate, and set the server URL.

Provisioning a device

You can define the provisioning configuration through the nRF Cloud portal or APIs.

Provisioning command status

Each command in the provisioning configuration has its own status. This provides a view to the provisioning process, readiness of commands, and to the provisioning history of the device.

  • PENDING: The command is queued and waiting for the device to connect to the nRF Cloud Provisioning Service.

  • IN_PROGRESS: The device has connected to the service, and requested and received commands.

  • SUCCEEDED: The device has successfully executed the command and reported this to the service.

  • FAILED: Command execution failed on the device. Failure stops the provisioning configuration from continuing to the next command. Failed commands can be updated or skipped.

  • SKIPPED: The command has been skipped by a separate request. The device cannot skip commands by itself: a service technician or your web service must manually skip commands.

Provisioning configuration

A claimed device can have a provisioning configuration, which is a sequence of commands to execute upon provisioning. These commands define which types of tokens and other authorization mechanisms the device generates and uses to connect to the service. You can also pass configurations or key-value pairs to the device during this process.

With a provisioning configuration in place, the device executes the defined commands when it attempts to connect to the Provisioning Service. The device continues to execute commands until there is an error or all commands are executed. If the device encounters an error, you must decide whether to attempt the command again, ignore the error, or change the provisioning configuration.

You can define the provisioning configuration through the nRF Cloud portal or APIs.

Provisioning rules

Creating a provisioning rule allows you to add a target device condition and deploy a provisioning configuration to a provisioning group. This allows you to define the same set of commands for multiple devices by adding tags to create a provisioning group and securely provision devices in bulk. You can create a provisioning rule at any time. Provisioning rules work continuously, adding the provisioning configuration to newly claimed and tagged devices, as well as existing ones. When a device connects, it is checked against existing criteria and eligible rules are applied.

The following diagram shows an overview of the provisioning process when rules are used.

Provisioning rules process overview

Target device conditions

Currently, the supported target device condition is provisioning groups. You can define these groups by assigning provisioning tags to devices, either during the claiming process or after.

Implementation and processing

Provisioning rules are sent to the device and processed according to their createdAt value. Newly created provisioning rules stay in DRAFT status until activated. If you update a rule in DRAFT status, it is still processed according to when it was created, not when it was updated.

Once you create and enable a provisioning rule, claimed devices with compatible application firmware check for new configurations according to a trigger. You can define the trigger manually using the nrf_provisioning_trigger_manually function, or define CONFIG_NRF_PROVISIONING_INTERVAL_S in the application code or provisioning configuration itself to define how often the device checks for applicable configurations and rules.

Since onboarding to nRF Cloud and secure provisioning are separate processes, you can also claim and securely provision devices that you have already onboarded to nRF Cloud. You can automate device provisioning configuration for existing and future claimed devices using provisioning rules.

Once a device has successfully applied a rule and reached the finished command, it does not attempt to apply the rule again. A device uses the rule-id to determine whether it has already applied a configuration through that rule.

Best practices

Plan rules before you create them, and test them with a single device or small batch of development devices. Rules are applied according to the order in which they were created, so keep this in mind if you create multiple provisioning rules that apply to the same devices. If you need to change a command in an older rule, you must either delete all existing rules in the sequence, or add a new command to a later rule to overwrite the result of the earlier command.

The recommended practice for creating and deploying provisioning rules is to apply them to a group of test devices first:

  1. Claim a small batch of development devices.
  2. Create a tag for this development group.
  3. Create a rule that applies to the development group.
  4. Add provisioning commands to the test rule.
  5. Activate the rule and monitor your devices as they process commands. Make sure the devices finish in the expected status.
    • If the end result is different than expected, repeat this process with a new tag and rule. You cannot edit an already activated rule.
  6. Once the test rule succeeds, copy the test rule and change the target device condition to a tag for devices in production.
  7. Change any commands as needed for production devices.
  8. Activate the copied rule when you are ready to apply it to devices in production.

See more on how to identify and recover from errors during the secure provisioning process.

Example

The following example shows how devices are included in a provisioning group in the field, and how the device checks for a provisioning configuration based on a rule.

Provisioning rules example

In this example, the rule's provisioning configuration ends with the device in AWAITING status, as there is no finished command. Once a certificate is generated, the provisioning configuration is then appended with the clientCertificate and finished commands. If a short interval is configured, remember to extend it before finishing.

Note

Provisioning rules are triggered when an eligible device connects to the Provisioning Service. Your service must poll the AWAITING status.

Blocking and unblocking devices

You can block or unblock a claimed device. This does not delete the device or forfeit your device claim, but prevents the device from receiving additional rules and commands.

If the device is running commands in its configuration at the time of blocking, it will report the results of those commands when they finish executing. Commands already received by the device will continue to run. This also applies to commands sent to the device through a provisioning rule.

Unblocking a claimed device allows it to process commands in its provisioning configuration again. Any pending commands in the configuration run the next time the device connects to the service.

See next

See more on how to securely provision Nordic Semiconductor devices:

  • Claiming device ownership explains how to claim devices using the nRF Cloud portal and the APIs.
  • Provisioning configuration explains device provisioning configurations in the APIs and nRF Cloud portal.
  • Using provisioning rules explains how to create, manage, and implement provisioning rules that apply a configuration to multiple devices.
  • Troubleshooting explains how to identify and recover from errors during the secure provisioning process.