Hub connection and policy

In case you use the Bosch IoT Suite for Asset Communication package, the connection is established already as a result of the subscription. Your devices registered using the Device Provisioning default settings will also enable the Hub to send telemetry data, events and other messages for command and control scenarios. See https://docs.bosch-iot-suite.com/asset-communication/Getting-started.html

However, in case you have booked Things and Hub separately, please continue reading.

Pre-requisites

To follow this example you will need:

• A Bosch IoT Things service subscription (see FAQ > How to book the service?)
• A Bosch IoT Hub service subscription

When using the wording Device in this example, it refers to a device inside the context Bosch IoT Hub. The term Thing refers to a digital twin in the context of Bosch IoT Things.

A: Create a Connection

Use the user interface as described at Manage your connections to create a connection to Bosch IoT Hub.

1. Click Add
   • Select “Bosch IoT Hub” from the categories
   • Give the connection a name (required)
   • Continue
2. All data is now in the “General” section, which you can collapse for now.
3. In the Coordinates section, set the credentials, which you have received by booking the Bosch IoT Hub service
   • From section “messaging” you will need the “username” and “password”.
   • The endpoint and port number is pre-configured in the UI.
4. In the Sources section set
   • telemetry/<hub-tenant-ID>
5. At the Authorization section, create an authorization subject for the Device.
   • Use the placeholder {{header:device_id}} The real value is to be used at step D.
   • You can even set multiple subjects, for example a technical username “my-technical.user”.
6. Click Test connection section.
   Upon success, the message “Testing the connection was successful.” should appear.
7. Click Create to persist the connection.
   • From now on the connection in open. However you can close and re-open it anytime, without loosing the values you have entered so far.
   • Click Edit if you need to adjust the values.

B: Create a Hello World Thing

Use your Things API token and your Bosch ID to access our interactive HTTP API documentation.

1. Authenticate in the upper right corner
   • With the API Token
   • Check the openid checkbox, to use your Bosch ID user credentials.
2. Request your thing creation
   • Go to section Things PUT /things/{thingId}
   • Click “Try it out“
   • Set the Thing ID to “your.namespace:HelloWorldThing99”
   • Submit the request with “Execute“

Please note, that your Thing ID must be unique. In case it already exists, you will need to alter the Thing ID.

Result
Your Hello World Thing will most probably look like the following snippet.

{
  "thingId": "your.namespace:HelloWorldThing99",
  "policyId": "your.namespace:HelloWorldThing99"
}

Find detailed info about the thing concept at Things and features.

C: Learn to read the Policy notation

Now that you know the policy ID, try to get familiar with its content.

1. Authenticate in the upper right corner

2. Request your policy

   • Go to section Policies GET /policies/{policyId}
   • Click “Try it out“
   • Set the ID retrieved at step B in the respective field
   • Submit the request with “Execute“

The response would look similar to the following snippet

{
 "policyId": "your.namespace:HelloWorldThing99",
 "entries": {
  "DEFAULT": {
    "subjects": {
      "bosch:S-1-5-xxx-110136@ciamids_3692D578-A9D4-406A-8675-0964925256AA": {
        "type": "bosch-id"
      }
    },
    "resources": {
      "policy:/": {
        "grant": [
          "READ",
          "WRITE"
        ],
        "revoke": []
      },
      "thing:/": {
        "grant": [
          "READ",
          "WRITE"
        ],
        "revoke": []
      },
      "message:/": {
        "grant": [
          "READ",
          "WRITE"
        ],
        "revoke": []
      }
    }
  }
 }
}

The automatically generated policy shows a DEFAULT entry with your own user ID as the subject and all “root” paths of your Thing.
So far this means that you are empowered to read and write on these resources.

D: Empower a Device to update the Hello World Thing

The write permission at the policy root resource (i.e. “policy:/”) allows to manage the policy itself. Make sure to always grant your user this permission to not lock yourself out.
Find the full concept description at Policies.

As you have read and write permission on the thing’s policy you can grant other users or applications permission on your entity:

• Copy the authorization subject from step A
• Add a new entry to the current policy
• Go to section put /policies/{policyId}/entries/{label}.
  • Click “Try it out“
  • Set the policyId to your.namespace:HelloWorldThing99
  • Set the label to device-app

  • Set the policyEntry to grant write permission on the thing
    (don’t forget to replace the real solution ID and device ID within the authorization subject integration:yourSolutionId:yourDeviceID

    {
      "subjects": {
        "integration:yourSolutionId:yourDeviceID": {
              "type": "hub"
        }
      },
      "resources": {
        "thing:/": {
          "grant": [
            "WRITE"
          ],
          "revoke": [
          ]
        }
      }
    }

• Submit the request with “Execute“

Congratulations,
you have successfully used the policy concept to grant writing permission on a thing.