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 provisioned on 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 provisioning	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 on the nRF9160 DK.

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 provisioned on 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 cloud provisioned 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.