Security and credentials¶
nRF Cloud device security involves the concepts of authentication and authorization:
- Authentication means verifying a device's or user's claimed identity.
- Authorization defines what the device is allowed to do after it has been authenticated.
Authentication¶
Authentication requires the use of verifiable pieces of data (credentials) that only the bearer (person or device) should have. The password you use to log in to the nRF Cloud portal is one example of a credential.
Devices authenticate differently depending upon which nRF Cloud API they are using:
| API | Authentication mechanism | Credentials |
|---|---|---|
| CoAP | JSON Web Token (JWT) over TLS | Tokens signed by the private key of a device's EC prime256v1 (ES256) asymmetric key pair, whose signature is verified by the associated public key stored on nRF Cloud. For the secure Provisioning Service, device's secure identity is used. For nRF Cloud Device management, a separate cloud access key is used. |
| MQTT | Mutual TLS | Requires two X.509 certificates: the AWS Root CA (to allow the device to verify the identity of the AWS MQTT broker) and a device certificate (to allow AWS to verify the identity of the device). |
| REST | JSON Web Token (JWT) over TLS | Tokens signed by the private key of a device's EC prime256v1 (ES256) asymmetric key pair, whose signature is verified by the associated public key stored on nRF Cloud. |
Unlike proxy-connected consumers of Location Services, devices connecting to nRF Cloud Device Management services, for example Firmware Update Service, must be onboarded to nRF Cloud.
Generating key pairs and credentials¶
There are multiple ways to generate the asymmetric key pairs needed in order to subsequently generate credentials (whether X.509 certificates or JWTs):
| Key generation | Credential management | Security level |
|---|---|---|
| On-device: auto-onboarding | The nRF Cloud Provisioning Service requests the device to create a separate cloud access key that is stored in nRF Cloud. | Most secure: Provisioning and device management authentication are separated. Key rotation with the nRF Cloud Provisioning Service. The private key is never exposed. |
| On-device: preconnected | Write certificates to the device using the CMNG AT command. |
More secure: The private key is never exposed. |
| On a computer | Private key and public certificate are written to the device using the CMNG AT command. |
Less secure: private key is generated off-device. Security depends on other factors. |
| On nRF Cloud | The certificate and keys are obtained through the CreateDeviceCertificate endpoint. The private key and certificate (both the Nordic Semiconductor CA and device certificates) are written to the device using the CMNG AT command. Certificate signing requests are generated using a CA certificate managed by Nordic Semiconductor. |
Least secure, private key is exposed: The certificate and keys are downloaded from nRF Cloud. For development purposes only. |
For more information on how to generate these assets and credentials, see Securely generating credentials for nRF91 Series devices.
For more information on service keys for cloud-to-cloud proxy servers, see Proxy server authentication.
Authorization¶
This section covers concepts of authorization in the MQTT and REST APIs.
Authorization allows devices or users to access endpoints or features through the nRF Cloud APIs. All devices in a team are granted the same access to API operations. Devices are visible and usable only within the team to which the devices have been onboarded.
If a device has been onboarded and can connect using MQTT or CoAP, it can use all the features of the APIs. See REST for more on specific authorization mechanisms for the REST APIs.
MQTT¶
MQTT-based authorization is handled by the standard MQTT connection process and IoT policies. MQTT connection requires the server certificate, client certificate, and client key. IoT policies define the topics to which the client can publish and subscribe. The allowed topics are listed in MQTT Topics.
Security violations¶
If your device attempts to do anything that is not supported over MQTT, it is immediately disconnected from the IoT broker. One common issue is attempting to publish or subscribe to a topic that is not allowed by the nRF Cloud policy. When debugging, the device may get a POLLHUP. When using the nRF Cloud library, the event generated is of type NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED with a status value of NRF_CLOUD_DISCONNECT_CLOSED_BY_REMOTE.
For more information, see Disconnecting from nRF Cloud in the nRF Connect SDK documentation.
REST¶
You and your devices can access REST endpoints with either an API key or JWT. Endpoints called directly by onboarded devices usually require a JWT, and endpoints called by the user to interact with services, or for application service integration, generally require an API key. Some endpoints accept either. Check the relevant API documentation for more information on specific endpoints.
If you have roles on multiple teams, you will have a different API key for each team. Applications use API keys for authentication to access nRF Cloud services for all devices in a team, whereas devices use device-specific JWTs for authentication for a more limited set of REST endpoints.
A user's role on a team also determines which operations they are authorized to request.
Proxy server authentication¶
If you use a proxy server to access Location Services, you need a service key.
You can generate a JWT and service key, together forming a service token, through the nRF Cloud portal or REST API. This operation is available only to the team owner. See Managing tokens and keys for more information.
This is a different JWT than the one generated on a device for requests directly to the nRF Cloud APIs.