Policies

A Policy enables developers to configure fine-grained access control for Things and other entities in an easy way.

The policy concept is only supported for Bosch IoT Thing HTTP API version 2.
Find the API reference at Policies resources.

A specific policy provides someone (called subject), permission to read and/or write at a given resource.

The write permission at the policy root resource (i.e. “policy:/”) allows to manage the policy itself.
Find an example at the end of the page.

Please note, that in most cases it makes sense to grant read permission in addition to a write permission, because write does not imply read.

A subject can be a technical client or a user.

Example

...
"subjects": {
       "iot-things:918904f5-xxxx-xxxx-xxxx-cb73a5ba9dbf:my-client":{
          "type": "iot-things-clientid"},
        "iot-permissions:8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c": {
          "type": "iot-permissions-userid"},
        "bosch:S-1-xxx@ciamids_36xxx": {
          "type": "bosch-id"},
          ...
          } ...

Build-in subject ID pattern

Prefix / Issuer (mandatory) ID (mandatory) Type (informational) Description
iot-things solutionId:your-postfix iot-things-clientid The ID of a technical client
(Java Client and CRS authentication)
iot-permissions UUID iot-permissions-userid
iot-permissions-groupid
iot-permissions-roleid
The ID of a User, Group, Role
managed within Bosch IoT Permissions
bosch UUID of user @ client ID bosch-id The ID of a Bosch Account (CIAM) and the CIAM client ID separated by an at @ character.
Recommended notation.
bosch UUID bosch-id The ID of a Bosch Account (CIAM)
Not recommended any longer. Use the new notation with the client ID for production scenarios.
google UUID google-id The ID of a Google User
integration solutionId:your-postfix hub, amqp, or mqtt The ID of a technical client, used for
receiving or publishing messages
over Connections
iot-suite UUID suite-auth The ID is the client ID of the OAuth2 client managed at Bosch IoT Suite portal.
See https://accounts.bosch-iot-suite.com/oauth2-clients/

The type is offered only for documentation purposes. You are not restricted to any specific types, but we recommend to use it to specify the kind of the subject as shown in our examples.

Custom subject of your OpenID Connect authentication provider

Upon request, the Things service team will configure your custom OpenID Connect authentication provider. See https://openid.net/connect/. We will need to know the specific URL of the issuer.

Prefix / Issuer (mandatory) ID (mandatory) Type (informational) Description
Your will get a custom prefix Your custom IDs will be derived from the value of the external_sub claim e.g. <external_sub>/<scope> The type is offered only for documentation purposes. You are not restricted to any specific types. For each scope of the JWT, a subject with the format
<subject-issuer>:<external_sub>/<scope> will be generated.

As a second step, you will need to register a client to your Bosch IoT Things subscription.
See APIdocs PUT /solutions/{solutionId}/clients.


A Policy can contain access control definitions for several resources:

  • Policy
    Someone who was granted write permission at the policy root resource (i.e. policy:/) is allowed to manage the policy itself.
  • Thing
    The resource can be defined as rough or as fine-grained as necessary for the respective use case: e.g. “thing:/” as top-level resource, or on sub-resources such as “thing:/features”. At runtime, the permissions are propagated down to all Thing sub-entities.
    • In case you grant read permission on top-level and revoke it at a sub-entity, the subject can read the upper part only.
    • In case you omit a subject at top-level but grant permission at a sub-entity, the subject can access the lower part only (and the Thing ID).
  • Message
    The resource can be defined as rough or as fine-grained as necessary for the respective use case: e.g. “message:/” as top-level resource.
  • Topology schema
    • Someone who was granted write permission may administer the schema and might thus:
      • Change its content, or
      • Change the policy reference (i.e. policyId).
    • In order to initialize a Topology, no permission on the schema is required.
  • Topology
    • From the policy point of view, the topology needs to be structured hierarchically.
    • At runtime, the permissions are propagated down to all Topology nodes.
      • In case of a Thing as a remote node, the service would evaluate both policies.
        In case of doubt, the Thing permission is stronger than Topology permission
        (see topology with thing node - example 1 and example 2).
      • In case of working with topology tags, please keep in mind:
        • Creating the tagged version requires write permission.
        • Querying the tagged version requires read permission.
        • Querying the tagged version of a Topology which was deleted meanwhile is not supported.
  • Solution
    Someone who was granted write permission at the solution root resource (i.e. solution:/) is allowed to manage the solution itself. See Policy of a solution.

Policy

The Policy resource (addressable as “policy:/”) defines the access control for the Policy itself.

Please make sure to define at least one user (for which you have the credentials) with top-level read and write permissions on the Policy, otherwise you won't be able to access/change it.

Resource Addressed data, description
policy:/ The Policy itself (top-level)
Applies to the Policy and all of its sub-resources.
policy:/policyId The Policy's ID.
However, such a reference is not recommended because write is not supported anyway,
and read on the ID only, does not provide any benefit.
policy:/entries Applies to all entries of the Policy.
policy:/entries/X Applies to all subjects and resources of the specific entry X.
policy:/entries/X/subjects Applies to all subjects of the specific entry X.
policy:/entries/X/subjects/Y Applies to subject Y of the specific entry X.
policy:/entries/X/resources Applies to all resources of the specific entry X.
policy:/entries/X/resources/Y Applies to resource Y of the specific entry X.

Example: The Things example at the end of the page also defines access control on the policy resource.

Thing

The Thing resource (addressable as “thing:/”) defines the access control for Things.

The access control definitions defined in a Policy's Thing resource will be applied to all Things referencing this Policy.

Note: In case you want to re-use a policy for various things, please make sure to name the Policy ID differently than the Thing ID.

Resource Addressed data, description
thing:/ The Thing itself (top-level).
Applies to the Thing and all of its sub-resources.
thing:/thingId The Thing's ID .
Not recommended, because write is not supported anyway and read on the ID only does not provide any benefit.
thing:/policyId Applies to the Policy ID of the Thing, which implicitly defines its access control.
Please double-check write permissions on this resource.
thing:/attributes Applies to all attributes of the Thing.
thing:/attributes/X Applies to the specific attribute X and its sub-paths.
X may be a nested path such as tire/pressure.

Example: Find a Things example at the end of the page.

Feature

Resource Addressed data, description
thing:/features Applies to all Features of the Thing.
thing:/features/X Applies to the Feature with ID X and all its sub-paths.
thing:/features/X/properties Applies to all properties of the Feature X.
thing:/features/X/properties/Y Applies to the property with path Y (and its sub-paths) of the Feature with ID X .
Y may be a nested path such as tire/pressure.

Example: Find a Things example at the end of the page.

Message

The Message resource (addressable as “message:/”) defines the access control for Messages.

The access control definitions defined in a Policy's Message resource will be applied to all Messages sent to or from Things referencing this Policy.

  • For sending messages to a Thing or its Features write permission is required
  • For receiving messages from a Thing or its Features read permission is required.

Such permissions can be defined at resources of different granularity.

Resource Addressed data, description
message:/ All messages (top-level)
Applies to all messages sent to or from Things referencing this Policy and all messages sent to or from features of these Things.
message:/inbox Applies to all messages sent to a specific Thing (or multiple things referencing this Policy)
message:/inbox/messages/X Applies to all messages on message-subject X, sent to the Things referencing this Policy
message:/outbox Applies to all messages sent from the Things referencing this Policy
message:/outbox/messages/X Applies to all messages on message-subject X, sent from the Things referencing this Policy
message:/features Messages for all Features
Applies to all messages sent to or from all Features of Things referencing this Policy
message:/features/Y Applies to all messages sent to or from Feature Y of the Things referencing this Policy
message:/features/Y/inbox Applies to all messages sent to Feature Y of the Things referencing this Policy
message:/features/Y/inbox/messages/X Applies to all messages on message-subject X sent to Feature Y of the Things referencing this Policy
message:/features/Y/outbox Applies to all messages sent from Feature Y of the Things referencing this Policy
message:/features/Y/outbox/messages/X Applies to all messages on message-subject X sent from Feature Y of the Things referencing this Policy

The resources “message:/inbox” and “message:/outbox” do not address feature-related messages. For providing access to feature-related messages, you have to either grant top-level permission (message:/“) or grant permission to the resource message:/features” (or the required sub-resources).

Example: The Things example at the end of the page also defines access control on messages.

Topology Schema

The Topology-Schema resource (addressable as “topology-schema:/”) defines the access control for Topology Schemas.

The access control definitions defined in a Policy's topology-schema resource will be applied to all Topology Schemas referencing this Policy.

The access control for Topology Schemas is completely separated from the access control for Topologies.

  • A user with access to a specific Topology, does not need any permission on the referenced Topology Schema.
  • A user with no permission at the schema but with read permission on topology:/content is able to retrieve schema data by means of an introspection query.

However, for development purposes it might be useful to grant a developer write permission on both, in case he needs to change the schema and the topology.

Resource Addressed data, description
topology-schema:/ The Topology Schema itself (top-level).
Applies to the Topology Schema and all of its sub-resources.
topology-schema:/schemaId The Topology Schema's ID.
Not recommended, because write is not supported anyway and read on the ID only does not provide any benefit.
topology-schema:/policyId Applies to the Policy ID of the Topology Schema, which implicitly defines its access control.
Please double-check write permissions on this resource.
topology-schema:/content Applies to the content of the Topology Schema, which is a GraphQL schema extended by Templates or Directives.

Topology

The Topology resource (addressable as “topology:/”) defines the access control for Topologies.

The access control definitions defined in a Policy's Topology resource will be applied to all Topologies referencing this Policy.

Resource Addressed data, description
topology:/ The Topology itself (top-level).
Applies to the Topology and all of its sub-resources.
topology:/topologyId The Topology's ID.
Not recommended, because write is not supported anyway and read on the ID only does not provide any benefit.
topology:/policyId Applies to the Policy ID of the Topology, which implicitly defines its access control.
Please double-check write permissions on this resource.
topology:/schemaId Applies to the Schema ID of the Topology, which is a reference to the Topology Schema defining the Topology structure. Please double-check write permissions on this resource.
topology:/content Applies to the content of the Topology, which can be read/write via GraphQL queries/mutations.
* Providing read permission to a user allows him to perform GraphQL queries, but no GraphQL mutations. Hence, he can use GET on the corresponding Topology sub-resource or he can query a topology tag (because Tags are always read-only ).
* Providing write permission to a user allows him to perform GraphQL mutations, i.e. changing the content.

Please note however, that in most cases it makes sense to provide read and write permission, because write does not imply read.
topology:/tags Applies to all Tags of a Topology.
By providing write permission to this sub-resource, you allow creating Tags for a Topology.

Please note, that read permission on this sub-resource is not applied: Read access to Topology Tags is restricted by the “non-tag” Topology Resources.
Currently Tags can only be accessed via the sub-resource topology/X/content, thus read access to Tags can be defined by means of the resource topology:/content
topology:/tags/X Applies to the specific Tag X of the Topology
Not recommended, because it allows to create a Tag with a specific name X only.

The access control for Things is separate from the access control for Topologies.
In case a Thing is referenced from a Topology, a user needs read and write permissions at the Thing and the Topology resources to be able to fully control it.

Topology with Thing node - Example 1

A Thing Policy grants following permission:

  • User A can read Thing T1.
  • User B can read Thing T1.

A policy for a Topology with reference to Thing T1 grants following permission:

  • User A can read the complete Topology.

Result:

  • User A may use both APIs to read Thing T1
  • User B may use the Things API to read Thing T1, but will not be able to query Thing values via the Topology API.

Topology with Thing node - Example 2

A Thing Policy grants following permission:

  • User A can read Thing T1.

A policy for a Topology with reference to Thing T1 grants following permission:

  • User A can read the complete Topology.
  • User B can read the complete Topology.

Result:

  • User A may use both APIs to read Thing T1.
  • User B may not read the Thing, neither via the Topology API nor via Things API.

Solution

The solution resource (addressable as “solution:/”) defines the access control for your Bosch IoT Things service instance.

The access control definitions defined in a solution policy will be applied to the service instance referencing this policy.

Note: The solution policy ID is defined automatically by our service at the time of subscribing the service, thus you will not be able to set a different ID (e.g. like you could do it for a thing entity). Find your solution policy ID at the dashboard's Basic data tab.

Resource Addressed data, description
solution:/ The solution itself (top-level).
Applies to the solution and all of its sub-resources.
solution:/key Applies to the public key of the solution.
solution:/namespaces Applies to all namespaces of the solution.
solution:/connections Applies to all connections of the solution.
solution:/connections/<connectionId> Applies to the specific connection with the given connectionId.
solution:/connections/<connectionId>/status Applies to the status of the specific connection with the given connectionId.
solution:/connections/<connectionId>/metrics Applies to all metrics of the specific connection with the given connectionId.
solution:/connections/<connectionId>/metrics/etc. Applies to specific metrics of the specific connection with the given connectionId.
solution:/connections/<connectionId>/logs Applies to all logs of the specific connection with the given connectionId.
solution:/connections/<connectionId>/logs/etc. Applies to specific log entries of the specific connection with the given connectionId.

Example: Find an example at Policy of a solution.

Change Permission Description
grant READ All subjects named in the section are granted read permission on the resources specified in the path, and all subsequent paths, except they are revoked at a subsequent policy label.
grant WRITE All subjects named in the section are granted write permission on the resources specified in the path, and all subsequent paths, except they are revoked at a subsequent policy label.
revoke READ All subjects named in the section are prohibited to read on the resources specified in the path, and all subsequent paths, except they are granted again such permission at a subsequent policy label.
revoke WRITE All subjects named in the section are prohibited to write on the resources specified in the path, and all subsequent paths, except they are granted again such permission at a subsequent policy label.

The Policy can be edited with a text editor of your choice. Just make sure it is in valid JSON representation, and that at least one valid subject is granted write permission at the root resources.

The easiest way is, to copy the model schema provided at the interactive HTTP API documentation, and adapt it to your needs.

In case of fine-grained access on Things, keep an eye on your actual Thing structure to make sure that all paths will be granted or revoked the permissions your use case is supposed to support.

In case of find grained access on Topologies, we will inform you at this place, as soon as it is implemented.

Given you need to support the following scenario:

  • Owner: The Thing my.namespace:thing-0123 is owned by a user. Thus, he needs full access and admin rights for the complete thing.
    In our example his ID is 8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c
  • Observer of changes at featureX and featureY:
    • Another application needs to be informed on each change at those features.
      In our example its ID is eebbb40e-xxxx-xxxx-xxxx-f79a4653946b:observer-client.
    • There is a group of users who are allowed to read both features.
      In our example the group ID is 93f24210-xxxx-xxxx-xxxx-620a03644e93
  • Privacy
    • The value of the “city” property at “featureY” is confidential and needs to be “hidden” from the group of users.

The correct JSON notation would be as shown in the following code block.

policy-example.json
  {
    "policyId": "my.namespace:policy-a",
    "entries": {
      "owner": {
        "subjects": {
          "iot-permissions:8c36bc60-xxxx-xxxx-xxxx-4ed6ce7ed64c": {
            "type": "iot-permissions-userid"
          }
        },
        "resources": {
          "thing:/": {
            "grant": ["READ", "WRITE"],
            "revoke": []
          },
          "policy:/": {
            "grant": ["READ", "WRITE"],
            "revoke": []
          },
          "message:/": {
            "grant": ["READ", "WRITE"],
            "revoke": []
          }
        }
      },
      "observer": {
        "subjects": {
          "iot-things:eebbb40e-xxxx-xxxx-xxxx-f79a4653946b:observer-client": {
            "type": "iot-things-clientid"
          },
          "iot-permissions:93f24210-xxxx-xxxx-xxxx-620a03644e93": {
            "type": "iot-permissions-groupid"
          }
        },
        "resources": {
          "thing:/features/featureX": {
            "grant": ["READ"],
            "revoke": []
          },
          "thing:/features/featureY": {
            "grant": ["READ"],
            "revoke": []
          }
        }
      },
      "private": {
        "subjects": {
          "iot-permissions:93f24210-xxxx-xxxx-xxxx-620a03644e93": {
            "type": "iot-permissions-groupid"
          },
          "resources": {
            "thing:/features/featureX/properties/location/city": {
              "grant": [],
              "revoke": ["READ"]
            }
          }
        }
      }
    }
  }

Note: The User ID, Group ID and Solution ID from the example above are just example values, and not valid IDs.

The Policy can be found:

  • Via GET request at /api/2/policies/<policyId>, and
  • Via GET request at /api/2/things/{thingId}/policyId
  • At any Thing itself in its JSON representation.
    It is however not included by default, but can be retrieved by specifying the /api/2/things/<thingId>?fields=_policy query parameter.

As soon as a sophisticated policy is described, you will only need to add a further subject entry to have for example a new group of users equally empowered as the initial one.