Hub-to-Things

This example assumes you have booked Things and Hub separately, and need to create a managed connection.

tip Please consider booking a Bosch IoT Suite for Asset Communication package instead, and use the UI driven approach of provisioning devices in Hub and Things at once. See https://docs.bosch-iot-suite.com/asset-communication/Getting-started.html

Pre-requisites

To follow this example you will need:

A Bosch IoT Things service subscription
A Bosch IoT Hub service subscription

Navigate to your list of subscriptions https://accounts.bosch-iot-suite.com/subscriptions/

Scroll to your Hub instance, and click Show Credentials
Copy them to a local file as you will need them later.
Scroll to your Things instance, and click Show Credentials
Copy them to a local file as you will need them later.

When using the word 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.

Create a Hub-to-Things connection

Click Go to Dashboard in the row of your Things instance, which will manage the connection
On the Things dashboard open the tab Connections/Integrations
Click Create your first connection (or Add in case you have one already)
- Select “Bosch IoT Hub” from the categories
- Give the connection a name (required) - e.g. device-via-hub
Provide the tenant ID and password (for ‘messaging’) of your Bosch IoT Hub subscription.
The next page in the dialog comes with various pre-settings
- The multiple checkboxes are prepared like for the Asset Communication package
  See https://docs.bosch-iot-suite.com/asset-communication/Hub-to-Things-connection.html.
  In case you need to change any, you can do that later on.
- Complete the authorization subject. e.g hub
  - Use the defaults integration:<your-things-solution-id>:hub
    Note: The complete subject needs later to be used within the policy of each thing.
  - You can even set multiple subjects at a later point in time, if your user case would require it.
Click Test connection section.
Upon success, the message “Testing the connection was successful.” should appear.
Click Create to persist the connection.
- From now on the connection in open. However, you can close and re-open it anytime, without losing the values you have entered so far.
- If you need to adjust any of the values, start with Edit.

Create a Hello World thing

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

Authenticate in the upper right corner
- With the API Token
- Check the openid checkbox, to use your Bosch ID user credentials.
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“

note 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.

Add the authorization subject of the connection to the policy

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

Read the policy

Authenticate in the upper right corner, as you did before
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:xxx-your-bosch-id-xxx@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.

Update the policy

tip 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:

Open the connection in a new browser tab and copy the subject from “Sources”
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-hub
  - Set the policyEntry to grant write permission on the thing
    (don’t forget to replace the real values within the authorization subject copied form the connection.
```
{
"subjects": {
  "integration:yourSolutionId:hub": {
      "type": "hub"
}
},
"resources": {
"thing:/": {
  "grant": [
      "READ",
      "WRITE"
      ],
  "revoke": [
  ]
}
}
}
```
- Submit the request with “Execute“

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

tip From the Bosch IoT Hub perspective you would now need to additionally register the “Hello World” as a device, and provide credentials (i.e. two further requests per device).
Therefore, again please consider booking a Bosch IoT Suite for Asset Communication package instead, and use the UI driven approach of provisioning devices in Hub and Things at once.
See https://docs.bosch-iot-suite.com/asset-communication/Getting-started.html