MQTT Broker for IoT

For the Internet of Things (IoT) features of BlueRange an MQTT Broker can be integrated. When this is set up, both BlueRange and your IoT devices get integrated and exchange data efficiently. Required configuration depends on your environment.

AWS IoT Integration

Firstly the AWS environment needs to be set up. Afterwards required cloud server locations and access keys are configured in the BlueRange server. Once done, enrolled IoT devices get their configuration data automatically.

When using the AWS IoT broker configuration described below, IoT devices such as the BlueRange Mesh Gateways must be connected by native MQTT directly. This setup does not allow use of an HTTP proxy! The limitation does not apply to browser clients but to devices only.

Browser clients may obtain temporary broker access from the BlueRange server making transparent use of AWS Cognito services under the hood.

Setup of AWS IoT

In the following the AWS management console is used for performing these steps:

  • An IAM account is configured as an identity throughout the system,

  • an IoT client certificate is obtained for broker access by devices,

  • a Cognito Identity Pool is created supporting online users, and

  • a RelutionOrganizationAccess role is set up limiting their rights.

Please choose a region of AWS depending on your needs and server locations and carefully follow the instructions given below.

IAM Account

For BlueRange an IAM account is needed. It is recommended to create a dedicated account for the server. The IAM account needs the following rights, granted by attaching mostly managed permission policies in AWS console IAM Service/Users/Summary/Permissions:

  • AWSIoTDataAccess for allowing MQTT broker connections,

  • AWSIoTConfigAccess for managing IoT devices and policies,

  • AmazonCognitoDeveloperAuthenticatedIdentities for managing mobile users accessing IoT data,

  • AmazonCognitoPowerUser for providing configuration capabilities keeping manual steps to a minimum, and

  • iam:GetRole for retrieval of RelutionOrganizationAccess Role below.

Also, for BlueRange to allow using the account, create an access key and secret key in the IAM user Summary/Security credentials tab, button Create access key. Please keep both the key information save as this needs to be configured in BlueRange later on.

IoT client certificate

Go to the AWS IoT service of the region and choose Security/Certificates, then press Create to set up a new client certificate for BlueRange to use. In Create a certificate screen use a One-click certificate creation (recommended) by pressing the button Create certificate next to it. Please download and keep save all the certificates and keys. Once downloaded, press Attach policy.

On the Add authorization to certificate screen Create new policy. Name the policy as desired, RelutionIotAccess, for example. At the moment BlueRange does not make use of Thing Shadows, so that the Actions iot:Connect, iot:Subscribe, iot:Publish and iot:Receive are enough. For simplicity choose * as ARN, or limit the scope to the particular region.

The policy created should look like this, for example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Connect",
        "iot:Publish",
        "iot:Subscribe",
        "iot:Receive"
      ],
      "Resource": "*"
    }
  ]
}

Unfortunately, AWS takes you to the policy now. In order to attach the policy to the certificate just created, go back and choose Security/Certificates. Click on the certificate just created, should be an inactive one. In the details screen go to tab Configurations and choose Action Attach policy. Select and attach the policy configured above. Finally, choose Action Activate to complete this part of configuration.

For obtaining the endpoint of the MQTT broker URL required for BlueRange configuration please go back to AWS Iot/Settings. The information is displayed as endpoint and looks something like a1syk38q47ovpy-ats.iot.eu-west-1.amazonaws.com.

Cognito Identity Provider

Next, go to the Cognito service of the region, and choose Manage Federated Identities. Create new identity pool and enter a name of your choice: RelutionIdentityPool, for example. Currently Enable access to unauthenticated identities is not required. As Authentication providers choose Custom. The Developer provider name is very important and can not be changed later on. The name given needs to be the host name component of the external server URL of the BlueRange server. For example, if your external server URL is https://relution.mycompany.com so that BlueRange end-users can access the server UI by entering this URL in the browser, then the required name is relution.mycompany.com. Then press Create identity pool.

On the next screen, AWS asks to create IAM roles. Please accept the defaults. Afterwards the identity pool id is displayed: eu-west-1:8be50a51-6c1d-4024-99af-e7882f4ac748, for example. Make sure to write this down as it is required in the next step.

The identity provider is required for mobile app users to access IoT data. When necessary, BlueRange will create and configure temporary user accounts using this pool. The identity pool is detected automatically by BlueRange based on the Developer provider name configured as host name of the external server URL.

Keep in mind, that the identity pool needs to be recreated and the role setup below reconfigured when the external server URL is changed!

RelutionOrganizationAccess Role

Go back to IAM service, under Roles choose Create new role. Select Role for identity provider access and Grant access to web identity providers. On the next screen use Amazon Cognito as Identity Provider and enter the identity pool id of the pool just created. Add a condition StringEquals for key cognito-identity.amazonaws.com:amr using prefix For all values and value authenticated so that only authenticated users can make use of the role. Do not forget to confirm with Add condition.

On the next screen the trust policy document should look like this example, with a different identity pool id, of course:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Principal": {
        "Federated": "cognito-identity.amazonaws.com"
      },
      "Condition": {
        "ForAllValues:StringEquals": {
          "cognito-identity.amazonaws.com:amr": "authenticated"
        },
        "StringEquals": {
          "cognito-identity.amazonaws.com:aud": "eu-west-1:8be50a51-6c1d-4024-99af-e7882f4ac748"
        }
      }
    }
  ]
}

Advancing to the next view the AWS managed policy AWSIoTDataAccess needs to be attached. At the time of writing it’s not possible to select the policy on this view. As a workaround, you can attach it by editing the role after it has been created.

Finally, in the wizard step Set role name and review enter RelutionOrganizationAccess as role name. BlueRange will detect the role created automatically based on the name.

Configuration of BlueRange

At the BlueRange server side, edit the <INSTALL_DIR>/application.yml.

Client Certificate

Add a new key store identified by a unique name, e.g. AWS IoT Keystore, underneath the keyStores key as demonstrated in the following example.

keyStores:
  # Key store name
  AWS IoT Keystore:
    _keystorePassword:
    _privateKeyWithCertificates_1_decryptPassword:
    _privateKeyWithCertificates_1_pem_urls:
      - /etc/opt/relution/aws.iot.crt.pem
      - /etc/opt/relution/aws.iot.key.pem
    provider: BC
    type: PKCS12
    warnBeforeExpirationPeriod: 30

Make sure the paths provided in _privateKeyWithCertificates_1_pem_urls point to a valid certificate and private key.

MQTT Connector

Additionally the MQTT connector needs to be configured as follows.

mqtt:
  enabled: true
  # URIs of the MQTT server(s).
  server_uris: 'ssl://<SERVER_URI>,wss://<SERVER_URI>'
  # Leave client_id empty to generate automatically
  client_id:
  # Login credentials
  username:
  _password:
  # Previously created Key Store
  keyStore: AWS IoT Keystore
  _keyPassword:
  # AWS IAM account details
  _aws_accessKey: <AWS_ACCESS_KEY>
  _aws_secretKey: <AWS_SECRET_KEY>

Replace <SERVER_URI> with the endpoint displayed in the AWS IoT part of the AWS management console under Settings, e.g. a1syk38q47ovpy-ats.iot.eu-west-1.amazonaws.com, and replace <AWS_ACCESS_KEY> and <AWS_SECRET_KEY> with the key information of the IAM account to be used by BlueRange. The value of the keyStore field, AWS IoT Keystore in this example, should match the name of the previously configured key store. If you chose another name you have to update it here accordingly.