Hub-to-Things
This example assumes you have booked Things and Hub separately, and need to create a managed connection.
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.
- Use the defaults
- The multiple checkboxes are prepared like for the Asset Communication package
- 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“
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
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.
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