Device Authentication

Devices connect to protocol adapters in order to publish telemetry data or events. Downstream applications consuming this data often take particular actions based on the content of the messages. Such actions may include simply updating some statistics, e.g. tracking the average room temperature, but may also trigger more serious activities like shutting down a power plant. It is therefore important that applications can rely on the fact that the messages they process have in fact been produced by the device indicated by a message’s source address.

Bosch IoT Hub relies on protocol adapters to establish a device’s identity before it is allowed to publish telemetry data or send events. Conceptually, Bosch IoT Hub distinguishes between two identities

  • an identity associated with the authentication credentials (termed the authentication identity or auth-id), and
  • an identity to act as the device identity or device-id.

A device therefore presents an auth-id as part of its credentials during the authentication process which is then resolved to a device identity by the protocol adapter on successful verification of the credentials.

In order to support the protocol adapters in the process of verifying credentials presented by a device, the Credentials API provides means to look up secrets on record for the device and use this information to verify the credentials.

The Credentials API supports registration of multiple sets of credentials for each device. A set of credentials consists of an auth-id and some sort of secret information. The particular type of secret determines the kind of information kept. Based on this approach, a device may be authenticated using different types of secrets, e.g. a hashed password or certificates, depending on the capabilities of the device and/or protocol adapter.

The HTTP Protocol Adapter supports the following credential types:

  • Password credentials
  • Device Certificates

The MQTT Protocol Adapter supports the following credential types:

  • Password credentials
  • Device Certificates

Once the protocol adapter has resolved the device-id for a device, it uses this identity when referring to the device in all subsequent API invocations, e.g. when forwarding telemetry messages downstream to the Bosch IoT Hub Messaging component.

Username and Password based device authentication

In case of username and password device authentication, the password can be provided to the IoT Hub Credentials API as a field of the secrets array field in the 2 following formats:

  1. Plaintext password (password field): this format is recommended to use. Provide the plaintext password string in the password field. Bosch IoT Hub will add salt and hash it. An example for plaintext password is given below:
    {
     "device-id": "4711",
     "type": "hashed-password",
     "auth-id": "little-sensor",
     "enabled": true,
     "secrets": [
       {
         "password": "plaintextPassword"
       }
     ]
    }
    
  2. Base64 encoded password: (password-base64 field): 1 provide the base64 encoded password in the password-base64 field. Bosch IoT Hub will add salt and hash it. This format should be used for real world scenarios if the passwords contain special characters. An example for Base64 encoded password for plaintext password “hub123” is given below:
    {
     "device-id": "4711",
     "type": "hashed-password",
     "auth-id": "little-sensor",
     "enabled": true,
     "secrets": [
       {
         "password-base64": "aHViMTIz"
       }
     ]
    }
    

X.509 Certificate based device authentication

In case of device certificate, the auth-id property will be the subject-dn of the client certificate in the format defined in RFC 2253.

To create a certificate credentials, the details of the certificate can be provided to the IoT Hub Credentials API as a field of the secrets array field in the following format:

{
  "device-id": "4711",
  "type": "x509-cert",
  "auth-id": "CN=device-1,O=ACME Corporation",
  "enabled": true,
  "secrets": [{}]
}

Once you have created device credentials as shown above, your devices can then authenticate using those device certificates.

The example above does not contain any of the not-before and not-after properties. The not-before and not-after properties should be omitted if the validity period is the same as the period indicated by the client certificate’s corresponding properties. It is still necessary to provide a (empty) JSON object in the secrets array, though.

Pre-requisite:

For any device certificate to be recognized, the CA certificate with which the device certificate was signed has to be uploaded to your tenant.

Disclaimer:

Currently it is not possible to upload the device CA to IoT Hub. In case you want to use device certificates, please contact the IoT Hub support and provide the CA certificate and the tenant ID. We will setup your tenant for you. This is just a temporary measure and in the future customers will be able to upload the device CA certificate to their tenants themselves.