Hub Connection

Estimated time to go through: 10 minutes.

To follow this example you will need:

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.

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.

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

  1. Authenticate in the upper right corner
    1. With the API Token
    2. Check the openid checkbox, to use your Bosch ID user credentials.
  2. Request your thing creation
    1. Go to section Things PUT /things/{thingId}
    2. Click “Try it out
    3. Set the Thing ID to your.namespace:HelloWorldThing99
    4. 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.

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
    1. Go to section Policies GET /policies/{policyId}
    2. Set the ID retrieved at step B in the respective field
    3. Submit the request with “Try it out!

The response would look similar to the following snippet

{
 "policyId": "your.namespace:HelloWorldThing99",
 "entries": {
  "DEFAULT": {
    "subjects": {
      "bosch:S-1-5-xxx-110136": {
        "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.

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}.
    • 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 “Try it out!

Congratulations,
you have successfully used the Policy concept to grant writing permission on a Thing.