nRF Cloud Access Provisioning

Please note that some information on this page may be outdated due to ongoing improvements in nRF Cloud. For the most current details on provisioning services, refer to the nRF Cloud Security Services documentation.

nRF Cloud is a major element of Nordic Semiconductor's long-term and committed plans for cellular IoT solutions. It can be accessed by users or devices through different methods for different purposes. Provisioning access to nRF Cloud for different targets is the first step that cellular IoT developers need to tackle in order to use the comprehensive services provided by nRF Cloud. For this step, some knowledge about encrypted internet communication would be advantageous. As this could be a challenge for beginners or embedded engineers who do not have a lot of experience in this field. There are several Nordic official documentation pages related to nRF Cloud including the official nRF Cloud documentation, nRF Connect SDK documentation and samples related to nRF Cloud, and the nRF Cloud REST API documentation. These pages all have detailed information explaining what you need to do for different provisioning methods.

This guide aims at helping developers with this processing, by explaining how the different protocols work and the reason why they need to conduct specific steps to finish connection provisions to nRF Cloud. This guide is divided into three main sections that answer the questions "Why?", "What?", and "How?". 

The "Why?" section explains the detailed security requirements for each nRF Cloud connection method. They are the reasons why we need to do authentication for the targets to build secure connections with nRF Cloud. The "What?" section lists authentication certificates that your targets should have after the provisioning is done.
And lastly, the "How?" section provides a detailed flowchart to guide you on how to get the authentication certificates for your targets.

Warm Up

Most of the application protocols used by nRF Cloud are related to the TLS (Transport Layer Security) protocol. If you are new to TLS or want to refresh your knowledge, please spend around 30 minutes watching the following videos to learn the basic concepts related to Asymmetric Encryption, Public and Private Keys, Signatures, Certificates, CA, and so on. Thanks for the great Practical TLS lessons from Ed Harmoush!

• Encryption - Symmetric Encryption vs Asymmetric Encryption - Cryptography - Practical TLS - YouTube
• Public and Private Keys - Signatures & Key Exchanges - Cryptography - Practical TLS - YouTube
• Public Key Infrastructure - What is a PKI? - Cryptography - Practical TLS - YouTube

Why?

The nRF Cloud offers three methods to interact: a web portal, a REST API, and an MQTT API. These methods can be used by different targets for simultaneous connections to access the nRF Cloud services. HTTPS is also used by devices to download new firmware during the FOTA (firmware-over-the-air) process. The targets here can either be users or devices. The users can access the nRF Cloud through the web portal or the REST API via a REST client on a PC or a cloud server. The devices are any nRF91 Series devices and can access the nRF Cloud through the REST API or the MQTT API. 

For the user, accessing the nRF Cloud web portal is pretty straightforward and can be done by registering and logging in. When it comes to the REST API, users can use it through REST clients e.g. Postman, a proxy server, or another cloud server. An API key (also called a Simple Token) is used as AUTHORIZATIONS by the REST client and it can be accessed from the web portal through your User Account -> Teams Details -> API Key. To access different location services provided by nRF Cloud, users need a dedicated JSON Web Token for the corresponding service.

For the device, provisioning means connecting the device to nRF Cloud and registering its device certificate. This allows the device to use the MQTT API and REST API to access services provided by nRF Cloud. 

The following table gives an overview with more details about targets and services they can access with different methods.

MQTT: Two-way TLS Authentication

The MQTT communication between the device and nRF Cloud uses two-way TLS authentication, also known as TLS with client certificate authentication or mutual TLS (mTLS). The server and client will verify the identity of each other before they build an encrypted TLS connection. Figure 1 shows how it works step by step.

Figure 1: Mutual TLS process

REST API: JWT Authentication

The REST API has three kinds of authentication methods: API key (or Simple Token), Service Evaluation Token (valid for 30 days), and JSON Web Token (JWT). The usage of Simple Token and Service Evaluation Token is pretty straightforward. Meanwhile, JWT provides higher security for the REST API, so some of the REST API endpoints require JWT authentication. 

FOTA: HTTPS Connection

One-way TLS is mostly used in a scenario where the client needs to figure out if the server is trustable. For example, a web server that provides HTTPS secure connections needs to apply for an X.509 server certificate from a CA. The browser client can then trust and communicate with the HTTPS web server based on the Public Key Infrastructure (PKI).

On nRF Cloud, a FOTA job can be managed either by the MQTT API or the REST API. But the FOTA files will be downloaded via the HTTPS protocol. This uses one-way TLS when a client device needs to verify the server identity, the same as the web server and browser HTTPS connection. nRF Cloud provides FOTA service for nRF91 devices and the HTTPS one-way TLS uses the same certifications used by the MQTT client to verify the server identity.

What?

For MQTT and FOTA services, the device and nRF Cloud should have the following authentication certificates ready after provisioning is done. In the case of the MQTT two-way TLS connection, the blue part is used by the server to verify client identity, and the green part is used by the client to verify server identity. If both sides are ok, an encrypted connection is built for the MQTT connection. When the device downloads firmware from nRF Cloud with the FOTA service, it is as mentioned using the HTTPS protocol, so only the green part of the authentication certificates is used by the client to verify that the server is trustable and download the new firmware through encrypted data traffic.

• Device (client)
  • nRFCloud CA (AWS RooT CA)
  • Device certificate with Public Key
  • Device Private Key for decryption (MQTT/FOTA)
• nRF Cloud (server)
  • Device CA from providers / Device certificate (MQTT/FOTA)
  • nRF Cloud certificate with Public Key
  • nRF Cloud Private Key for decryption

For the REST API service, the API Key and Service Evaluation Token can be generated directly from the nRF Cloud web page. When a JWT is used to authenticate the device or user REST client that needs to communicate with nRF Cloud, a public and private key pair needs to be generated and deployed into devices or clients.

• Device or user through REST client (client)
  
  • Private Key for JWT signing(Device Key for device and Service Key for client)
• nRF Cloud (server)
  • Public Key for JWT Signature Verification

The device Private Key for decryption and the device Key for JWT signing can be the same private key stored in the nRF91 modem firmware with a specific security tag. However, they can also be different.

How?

The following flowchart summarizes the decision flow you can follow when you want to use the nRF Cloud service as a user or start provisioning nRF91 devices to nRF Cloud. The flowchart is drawn with microboard, click on the image below to see more details and access links. 

Figure 2. Decision flow for nRF Cloud Provisioning

The flowchart covers two targets and their connection to nRF Cloud: 

• User connection provisioning to nRF Cloud
• Device connection provisioning to nRF Cloud

For user connection to nRF Cloud, the flowchart shows that users can access cloud services through either the web portal or the REST API through clients. Users can use different REST API authentication methods including Simple Token, Service Evaluation Token, and JWT signed by Service Key to access endpoints for specific nRF Cloud services.

For device connection to nRF Cloud, the device can choose either REST API or MQTT depending on their application needs. For commercial products based on the nRF9160 SiP, it is common for developers to do a preconnect provision for their devices with their own CA, and then the device would be ready for MQTT and FOTA services, and also generate JWT with Device Key for REST API communication.

Conclusion

This guide explains why and what we need for provisioning users or nRF91 Series devices to connect with nRF Cloud through different application protocols. By following the decision flow for nRF Cloud provisioning, developers can easily decide how to choose the correct provisioning methods for their development.