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.

Estimated time to go through: 20 minutes.

Before we start, you'll need to get set up with a user profile to identify yourself.
Bosch IoT Things integrates seamlessly with Bosch IoT Permissions and further supports various third-party providers for user authentication. Bosch IoT Permissions offers free evaluation profiles to keep it simple in the beginning.

You can sign up for a free account at Register a user.

Bosch IoT Things provides a free service plan which you can book without any obligations.
Sign up for a free evaluation account (see How to book the service?).

You will receive a link to your solution registration details via email. Among others you will find there the API token, which you will need in the subsequent sections.

For more information on managing your solution, see Manage your solution.

Use your freshly created user credentials and API token to access our interactive HTTP API documentation.

  1. Authenticate in the upper right corner
    1. With the API Token - from step B
    2. With the demo user credentials - from step A
  2. Request your thing creation
    1. Go to section Things PUT /things/{thingId}
    2. Click “Try it out!
    3. Set the Thing ID to com.example:HelloWorldThing01
    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.

The response body of the request from step C 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
    1. Go to section GET /things
    2. Click “Try it out!
    3. Set the ID created at step C in the respective field
    4. Submit the request with “Execute

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

{
  "thingId": "com.example:HelloWorldThing01",
  "policyId": "com.example:HelloWorldThing01"
}

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. Click “Try it out!
    3. Set the ID retrieved at step D in the respective field
    4. Submit the request with “Execute

The response would look similar to the following snippet

{
 "policyId": "com.example:HelloWorldThing01",
 "entries": {
  "DEFAULT": {
    "subjects": {
      "iot-permissions:8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c": {
        "type": "iot-permissions-userid"
      }
    },
    "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.

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 DEAULT 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 G.
  • Create a new policy entity “com.example: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.

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.

Given you have decided to just add a “TEST” policy entry.

  • Create a second demo user as described at Register a user.
  • Authenticate in the upper right corner
  • Update the Policy
    • Go to section put /policies/{policyId}/entries/{label}
    • Click “Try it out!
    • Set the policyId to com.example:HelloWorldThing01
    • Set the label to TEST
    • Set the policyEntry to
      {
        "subjects": {
          "iot-permissions:1e617ccc-xxxx-xxxx-xxxx-49e3e04911f0": {
                "type": "iot-permissions-userid"
          }
        },
        "resources": {
          "thing:/": {
            "grant": [
              "READ"
            ],
            "revoke": [
            ]
          }
        }
      }
  • Submit the request with “Execute
  • Use the dialog at the upper right corner to log out
  • Re-log in with the credentials of the second user
  • Read the Hello World Thing
    • Go to section Things GET /things
    • Click “Try it out!
    • Specify the Thing ID com.example:HelloWorldThing01
    • Submit the request with “Execute

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