Policy

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.

Authorization concept

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.

Who can be addressed

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-suite:/service-instance.538258a4-xxx@36d8dba1-xxx": {
        "type": "suite-auth"
      },
      "bosch:S-1-xxx@ciamids_36xxx": {
        "type": "bosch-id"
      }
  }
}             

Build-in subject ID pattern

You can find the subject IDs for your current authentication, using the Who Am I-REST call. See FAQ > How to find the authorization subject IDs that I can use in policies?

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 custom OAuth2 authorization provider

Upon request, the Things service team will configure your custom OAuth2 authorization provider (which needs to be OpenID Connect compliant, see https://openid.net/connect/).

Will need to know the specific URL of the issuer. Find details at the FAQ section.

As a second step, you will need to register a client to your Bosch IoT Things subscription.
See APIdocs - PUT ​/solutions​/{solutionId}​/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.

Which resources can be controlled

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 thingId).
• 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.
• 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.

Example: The 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.

In case you want to re-use a policy for various things, we recommend to name the policyId differently than the thingId.

Example:

{
  "thingId": "org.example:coffee-machine-01",
  "policyId": "org.example:coffee-machine-policy"
}

In case multiple things share the same policy, the settings at the thing:/ resource will be applied to all things referencing this policy.

Example: Find an example at the end of the page.

Feature

Example: Find an example at the end of the page.

Message

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

The access control definitions will be applied to all messages sent to or from a thing 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.

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 example at the end of the page also defines access control on messages.

Solution

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

The solution policy defines the access rules for your solution.

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.

Find an example at Policy of a solution.

Grant and revoke permission

Tools for editing a policy

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.

Example

Given you need to support the following scenario:

• Owner
  The thing my.namespace:thing-0123 is owned by a OAuth2 client. Thus, he needs full access and admin rights for the complete thing.
  In our example his ID is iot-suite:/service-instance.538258a4-xxx@36d8dba1-xxx
• 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.
• Privacy
  • The value of the “city” property at “featureY” is confidential and needs to be “hidden” from the other application.

To accomplish all conditions mentioned above, your policy might look like the following image.

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

{
   "policyId": "my.namespace:policy-a",
   "entries": {
     "owner": {
       "subjects": {
         "iot-suite:/service-instance.538258a4-xxx@36d8dba1-xxx": {
           "type": "suite-auth"
         }
       },
       "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"
         }
       },
       "resources": {
         "thing:/features/featureX": {
           "grant": ["READ"],
           "revoke": []
         },
         "thing:/features/featureY": {
           "grant": ["READ"],
           "revoke": []
         }
       }
     },
     "private": {
       "subjects": {
         "iot-things:eebbb40e-xxxx-xxxx-xxxx-f79a4653946b:observer-client": {
           "type": "iot-things-clientid"
         }
       },
       "resources": {
         "thing:/features/featureX/properties/location/city": {
           "grant": [],
           "revoke": ["READ"]
         }
       }
     }
   }
 }

The IDs from the example above are just example values.

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.
  A common get thing request, does not include the full policy by default, but you can be retrieve it by appending the field _policy as a query parameter e.g. /api/2/things/<thingId>?fields=_policy
  

In case of doubt add for each role an own “label” and later add the subject which you need to empower in the specific section.