Hello World

How possibly could a tutorial start without saying Hello World
Well, to be more precise, as we provide a Things service, in the course of this tutorial part you will create a Hello World thing and learn to appreciate the access control settings via an entity called policy.

A: Book a free service plan

Bosch IoT Things provides a free service plan which you can book without any obligations.
Sign up for a free account of the Bosch IoT Suite for Asset Communication package.

B: Create an OAuth2 client

Go to OAuth2 Clients and create a client with the scope of Bosch IoT Things booked before.

oauth-client

C: Create a namespace

All things associated to your account will be created in this namespace. However the namespace needs to be set only once.

namespace

D: Create a thing

Use your client to access our HTTP API documentation.

  1. Use your OAuth2 client to create a token via the “Use” button.
  2. Paste the token to the bearerAuth authentication.
  3. Request your thing creation
    • Go to section Things PUT /things/{thingId}
    • Click “Try it out!”
    • Set the thing ID to your.namespace:HelloWorldThing01
    • 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.

E: Learn to read the thing notation

The response body of the request from step D already shows the thing you have created.
However, generally you can read each of your things with a GET request.

  1. Authenticate in the upper right corner
  2. Request your thing
    • Go to section GET /things
    • Click “Try it out!*”
    • Set the ID created at step C in the respective field
    • Submit the request with “Execute”

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

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

Find detailed info about the concept at Basic concepts > Things and features.

F: 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 D in the respective field
    • Submit the request with “Execute”

The response would look similar to the following snippet

{
   "policyId": "your.namespace:HelloWorldThing01",
   "entries": {
     "DEFAULT": {
       "subjects": {
         "iot-suite:/service-instance.538258a4-xxx@36d8dba1-9f3c-43cb-bc4b-8376b659537a": {
           "type": "suite-auth"
         }
       },
       "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 a subject generated from your OAuth2 client and all “root” paths of your Thing.
So far this means that you are empowered to read and write on these resources.

G: Empower another user to read your Hello World thing

As you have read and write permission on the thing’s policy, there are several ways how you can grant other users or applications permission on your entity:

  • Add a new user ID at the DEFAULT entry of the current policy
    put /policies/{policyId}/entries/{label}/subjects
    However, this is only recommended, if you want the user to get all permissions on all resources.
  • Add a new entry to the current policy
    put /policies/{policyId}/entries/{label}
    The complete example will be shown in step H.
  • Create a new policy entity your.namespace:test-policy-01 via put /policies/{policyId},
    and afterwards assign your thing this new policy via put /things/{thingId}/policyId.
    This alternative is feasible for example if you need to completely change the permissions for testing or productive use.

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 Basic concepts > Policies.

Example with Bosch ID

Given you have decided to just add a “TEST” policy entry to make the HelloWorldThing01 visible on the Things dashboard.

  • Update the Policy

    • Go to section put /policies/{policyId}/entries/{label}
    • Click “Try it out!”
    • Set the policyId to “your.namespace:HelloWorldThing01”
    • Set the label to “TEST”
    • Set the policyEntry

      {
        "subjects": {
          "bosch:<S-x-x-your-bosch-ID-xxx>@ciamids_3692D578-A9D4-406A-8675-0964925256AA": {
          "type": "bosch-id"
           }
         },
        "resources": {
          "thing:/": {
          "grant": [
            "READ"
          ],
          "revoke": [
          ]
          }
        }
      }
  • Replace the placeholder <S-x-x-your-bosch-ID-xxx> with your Bosch ID.
    Tip: Your Bosch ID is visible in the Suite portal. Open in a new browser tab the page https://accounts.bosch-iot-suite.com/account/myaccount

    • Make sure to keep the @ciamids_3692D578-A9D4-406A-8675-0964925256AA with the client ID of the Things service, as our Things dashboard will expect this client.
      Example: bosch:S-1-2-3@ciamids_3692D578-A9D4-406A-8675-0964925256AA
    • Submit the request with “Execute”.

Check your work

At the second browser tab, with the subscription page (https://accounts.bosch-iot-suite.com/subscriptions/) click “Go to Dashboard”, and finally click the Things tab. In case the policy has been changes successfully, your thing with ID your.namespace:HelloWorldThing01 should be listed there.

HelloWorld

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

Imprint Legal info Privacy statement