Skip to content

Security and credentials

nRF Cloud device security involves the concepts of authentication and authorization:

  • Authentication means verifying a device's claimed identity.
  • Authorization defines what the device is allowed to do after it has been authenticated.

See the AWS IoT Security Model for more detail.

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
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 consumers of Location Services, devices using the Firmware Update Service must be onboarded to nRF Cloud, which requires an X.509 certificate. This certificate, however, is not used to authenticate REST calls. You must also use a device certificate with the initial REST call to the AWS IoT API if using Just-In-Time Provisioning (JITP) without an MQTT client.

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 the device Write certificates to the device using the CMNG AT command. More secure: 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 Certificate and keys are obtained through the CreateDeviceCertificate endpoint. 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 Nordic Semiconductor's managed CA certificate. Less-secure, private key is exposed: certificate and keys are downloaded from nRF Cloud.

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.

MQTT

MQTT-based authorization is handled by IoT permissions residing in AWS IoT Core policies that are attached to Thing Groups. Devices that are members of these groups inherit these policies.

In the policies that follow, iot:ClientId is the ID you set in the MQTT client used to connect to nRF Cloud. This must always be the same as your device ID.

For example, all devices that are onboarded to nRF Cloud become members of the Provisioned Devices Thing Group with the following policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Condition": {
        "Bool": {
          "iot:Connection.Thing.IsAttached": [
            "true"
          ]
        }
      },
      "Action": "iot:Connect",
      "Resource": "arn:aws:iot:*:${AWSAccountId}:client/${iot:ClientId}",
      "Effect": "Allow"
    },
    {
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/${iot:ClientId}/shadow/get/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/${iot:ClientId}/shadow/update/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/shadow/get/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/shadow/update/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/jobs/*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/shadow/get",
        "arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/shadow/update",
        "arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/jobs/*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": [
        "iot:Receive"
      ],
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": [
        "iot:UpdateThingShadow",
        "iot:GetThingShadow"
      ],
      "Resource": "arn:aws:iot:*:${AWSAccountId}:thing/${iot:ClientId}",
      "Effect": "Allow"
    }
  ]
}

When the device is not only onboarded but also added to a user's account, the device becomes a member of the Associated Devices Thing Group. This group adds more permissions for its member devices. In the following policy, the tenantId is your Team ID.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/m/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/a/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/*",
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/ble/*"
      ],
      "Effect": "Allow"
    },
    {
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/m/*",
        "arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/*",
        "arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/ble/*"
      ],
      "Effect": "Allow"
    }
  ]
}

LTE gateways also receive additional permissions for MQTT topics used for gateway messages:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[teamId]}(see s/${iot:ClientId}/c2g"
      ],
      "Effect": "Allow"
    },
    {
      "Action": "iot:Publish",
      "Resource": [
        "arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[teamId]}(see s/${iot:ClientId}/g2c"
      ],
      "Effect": "Allow"
    }
  ]
}

Note

This policy does not apply to phone gateways, which use an AWS Cognito user-based policy and the /c2g and /g2c topics.

Security violations

If your device attempts to do anything over MQTT that is not supported by the above policies, it is immediately disconnected from the IoT broker. One common problem is attempting to publish or subscribe to a topic not allowed by the policy. If you debug, you can see the device 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 this section on disconnecting from nRF Cloud in the nRF Connect SDK documentation.

REST

While authorization for REST-based operations might also involve IoT security policies, what is permitted depends on whether the JWT signature can be verified and the request allowed to continue. Authorization is highly connected to endpoint access.

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.