Control who may access your XDK as a Thing

At this point we assume you already managed to go through the Hello World tutorial and are familiar with our policy concept.

While registering your XDK the Things service automatically generates a default Policy for you. This policy protects access to all Things you registered with your account. The ID of your policy is returned as property “policyId” whenever you retrieve the data of your Thing.

The policy contains the following entries:

  • owner - empowering you as the device owner with all privileges - even to disable other entries
  • connector - empowering the software stack (you have flashed the device with) to communicate the sensor values to our cloud service
  • admin - empowering an administrative user at Bosch IoT Things to read and write all resources - just for the case you need support
{
  "policyId": "bosch.xdk:S-1-5-21-xxx",
  "entries": {
    "admin": {
      "subjects": {
        "iot-permissions:41c83f16-e0a3-49cc-89d5-f7c9fdc406d9": {
          "type": "iot-permissions-userid"
        }
      },
      "resources": {
        "policy:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        },
        "thing:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    },
    "owner": {
      "subjects": {
        "bosch:<S-x-x-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": []
        }
      }
    },
    "connector": {
      "subjects": {
        "iot-things:363b0bdc-e13c-4b26-ab79-ef3859d102b2:lwm2m-connector": {
          "type": "iot-things-clientid"
        }
      },
      "resources": {
        "thing:/": {
          "grant": [
            "READ",
            "WRITE"
          ],
          "revoke": []
        }
      }
    }
  }
}

In case your app implements Basic Authentication, the easiest way would be to use an evaluation user. Find a detailed description at Register a user. As you are creating a technical user for your application, you can omit optional personal information (like first name, last name) in the registration form.

Store the email, as it contains your technical user ID.

In a second step you would need to add the technical user ID at your XDK's policy.
At each request to read, update or delete a specific Thing entity, the Things service will check if the subject has such permission.

Given your desired App is an Illumination-App that only needs to read values of the that feature.

The Basic Authentication will work with your technical user ID (just replace 8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c with your own).

Create a new Policy entry

  • Section Policies PUT /policies/{policyId}/entries/{label}
  • Click “Try it out
  • Set policyId: bosch.xdk:S-1-5-21-xxx
  • Set label: Illumination-App
  • Set policyEntry:
    {
          "subjects": {
            "iot-permissions:8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c": {
              "type": "iot-permissions-userid"
            },
            "bosch:<S-x-x-your-bosch-ID-xxx>@ciamids_3692D578-A9D4-406A-8675-0964925256AA": {
              "type": "bosch-id"
            },
          },
          "resources": {
            "thing:/features/IlluminanceSensor.0": {
              "grant": [
                "READ"
              ],
              "revoke": []
            }
          }
    } 
  • Execute

To make sure it is your technical ID which may now read the values, proceed as follows:

  • Open the Authorize dialog
    • At section “OAuth2.0” click Logout
  • Re-open the Authorize dialog
    • At section “Basic authentication” set your credentials for the technical user
    • Click Authorize
  • Make sure the API token is still set
  • Select section “Things”
    • GET /things/{thingId}
    • Click Try it out
    • Set the thingId: bosch.xdk:xxx
    • Execute

Response Body:

{
  "thingId": "bosch.xdk:xxx",
  "features": {
    "IlluminanceSensor.0": {
      "properties": {
        "status": {
          "minMeasuredValue": 120960,
          "minRangeValue": 0,
          "units": "mlx",
          "maxMeasuredValue": 198720,
          "sensorValue": 195840,
          "maxRangeValue": 188000000
        }
      }
    }
  }
}