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 Device Manangement package instead, and use the UI driven approach of provisioning devices in Hub and Things at once. See https://docs.bosch-iot-suite.com/device-management/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, e.g. device-via-hub. Setting a name is required
Provide the tenant ID and password (for ‘messaging’) of your Bosch IoT Hub subscription.
Click Continue.
The next page in the dialog comes with various pre-settings.
- The multiple checkboxes are prepared like for the Device Management package
  See https://docs.bosch-iot-suite.com/device-management/Devices-via-Bosch-IoT-Hub-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.
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 and
- additionally check the openid checkbox, to use your Bosch ID.
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 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 thing:

Open the connection in a new browser tab and copy the Authorization 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": [ ]
    },
    "message:/": {
      "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 Bosch IoT Suite for Device Management instead, and use the UI driven approach of provisioning devices in Hub and Things at once.
See https://docs.bosch-iot-suite.com/device-management/Getting-started.html.