For managing device access rights, you can use the Bosch IoT Insights Swagger UI to invoke the Bosch IoT Insights API. The benefit of this approach is that the API documentation provides hints and authentication/authorization is much simpler.

If you access the Bosch IoT Insights API from your Bosch IoT Insights' project, no special authentication is needed. You perform all API calls on behalf of your user that is logged in to Bosch IoT Insights. However, ensure that your user has admin rights for the particular project.

Besides the Bosch IoT Insights Swagger UI, you can also use every REST client to perform your API requests. This is the right approach if you like to integrate the Bosch IoT Insights API in your management and administration scripts or if you want to manage your project via your custom tool chain. If you are not using the Bosch IoT Insights Swagger UI (e.g. because you prefer curl or Postman), you need an API user that is equipped with admin rights.

To create an API user, refer to Creating an API user or Creating an API user via API. To assign the admin role to the API user, refer to Editing a user.

The code blocks in the following steps contain example values which need to be replaced by project-specific values.

Entity	Value
Project	test-project
Role	test_role
User	test_user
User email	test@user.com
User ID	11111111-2222-3333-4444-555555555555
Device	test-device
Device ID	test_project:test-type_test-device
Policy ID	test_project:test-type_test-device
Thing ID	same as Device ID
Subject	iot-suite:/ext-iam.insights.test-project.test_role

Creating a role with Swagger UI

First, you need to create a role via the Project Management Service API.

Proceed as follows

Open the Project Management Service API.
Open Roles: Manage project roles.
→ A list of requests is displayed.
Open the POST /v1/{project}/roles request.
1. In the Parameters pane, enter the project name in the project field.
2. In the role box, paste the following code block and replace the values with your project-specific values:
  
  {
  
  "description": "A Role for Test purpose",
  
  "roleDisplayName": "Test Role",
  
  "roleName": "test_role"
  
  }
Click the Try it out! button to create the role.
→ The response code 200 is returned and the role is created.

If you are using a different REST client, perform the following POST request:

https://bosch-iot-insights.com/project-management-service/v1/<test-project>/roles

You have to setup the request with Basic Auth using the credentials of the API user you created.

Assigning a user to the role

A user is assigned to a role by using the role name and the user ID (technical ID). As a first step, the user ID of the respective user has to be determined with a GET request in the Project Management Service API.

Proceed as follows

Open Users: Manage project's users.
→ A list of requests is displayed.
Open the GET /v1/{project}/users request.
1. In the Parameters pane, enter the project name in the project field.
2. In the searchTerm field, enter for instance the email address of the user.
Click the Try it out! button to determine the user ID.
→ The user object that contains the user ID is returned.

If you are using a different REST client, perform the following GET request:

https://bosch-iot-insights.com/project-management-service/v1/<test-project>/users?searchTerm=test%40user.com

The role can now be assigned to the user.

Proceed as follows

Open the POST /v1/{project}/users/{userId}/role-mappings request.
In the Parameters pane, enter the project name in the project field.
1. In the userId field, enter the user ID that was returned with the GET /v1/{project}/users request.
2. In the roles field, enter the role you just created.
  
  {
  
  "projectRoles": ["test_role"]
  
  }
Click the Try it out! button to assign the role.
→ All roles the user is assigned to are returned as well as the role you just created.

If you are using a different REST client, perform the following POST request:

https://bosch-iot-insights.com/project-management-service/v1/<test-project>/users/<11111111-2222-3333-4444-555555555555>/role-mappings

Determining the policy ID of the device

Generally, in the context of device access rights context the policy ID is the same as the device ID, e.g.

Device ID: test_project:test-type_test-device

Policy ID: test_project:test-type_test-device

To ensure that this is true for the respective device, you can inspect it via the Bosch IoT Things HTTP API.

Proceed as follows

Open the Service API: IoT Things.
Open Things: Manage every thing.
→ A list of requests is displayed.
Open the GET /iot-things-api/{project}/2/things/{thingId} request.
1. In the Parameters pane, enter the project name in the project field.
2. In the thingId field, enter the device ID.
Click the Try it out! button to display the policy ID.
→ The policy ID of the device is returned.

If you are using a different REST client, perform the following GET request:

https://bosch-iot-insights.com/iot-things-api/<test-project>/2/things/<test_project%3Atest-type_test-device>

This is verified via the Bosch IoT Things policy endpoint. Inspect the policyId field of the response body to ensure that the convention thingId==policyId is met.

Adding the role as policy subject of the device

As a next step, the policy subject has to be adjusted.

This is the most critical part in context of managing device access rights. If you do it wrong, the device (or the devices) that belongs to the modified policy may no longer be accessible at all (e.g. if you accidentally remove all existing authorization subjects with your modification).

Because of a known issue with Swagger UI (it escapes slashes in url parameters which Bosch IoT Things does not support), it is not possible to do a fine-grained update on subject level. Instead, the update needs to be performed on entry level. That way, the subjects are no longer part of the url parameters but of the body. In practice this means, you need to inspect the subjects first on the entry that should be modified and use these subjects as well as your additional subject as input for your modification request.

Bosch IoT Things policies that are compliant with the Bosch IoT Insights device management, include two entries: [see] and [manage]. If you intent to just give read access for a role, it has to be added as subject to the [see] entry. If you also want to grant write access, the [manage] entry is the right choice.

In this example, the subject for the [manage] entry will be added.

Therefore, collect the subjects that are currently assigned to the [manage] entry. This is also done via the Bosch IoT Things HTTP API.

Proceed as follows

Open Things: Control access to your things.
→ A list of requests is displayed.
Open the GET /iot-things-api/{project}/2/policies/{policyId}/entries/{label}/subjects request.
1. In the Parameters pane, enter the project name in the project field.
2. In the policyId field, enter the policy ID.
3. In the label field, enter the manage label to grant read and write access to the device.
Click the Try it out! button to receive the policy subjects.
→ The policy subjects are returned. The result looks like this:

{

"iot-suite:/ext-iam.insights.test-project.power_user": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.test-project.manager": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.test-project.admin": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.admin": {

"type": "iot-insights-role"

}

}

Each subject is prefixed with iot-suite:/ext-iam.insights.

Project roles use the prefix extended by the project name (iot-suite:/ext-iam.insights.test-project. in this example).
Copy the result from the response body to an editor and extend it with the role you created in the beginning.

It is important that you only remove or modify something, if you are familiar with this. Otherwise, your device may break.
Add the new role in the prefixed style to the list of subjects like this:

{

"iot-suite:/ext-iam.insights.test-project.power_user": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.test-project.manager": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.test-project.admin": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.admin": {

"type": "iot-insights-role"

},

"iot-suite:/ext-iam.insights.test-project.test_role": {

"type": "iot-insights-role"

}

}

Remember to also replace the <test-project> with your project ID.
Open the PUT /iot-things-api/{project}/2/policies/{policyId}/entries/{label}/subjects request to modify the policy.
1. In the Parameters pane, enter the project name in the project field.
2. In the policyId field, enter the policy ID.
3. In the label field, enter the manage label to grant read and write access to the device.
4. In the body box, paste the modified policy subjects.
Click the Try it out! button to adjust the policy.
→ The policy is adjusted and the response code 204 is returned.

If you are using a different REST client, perform the following PUT request with the iot-suite:/ext-iam.insights.test-project.test_role subject for the [manage] label:

https://bosch-iot-insights.com/iot-things-api/<test-project>/2/policies/<test_project%3Atest-type_test-device>/entries/manage/subjects/iot-suite/<iot-suite%3A/ext-iam.insights.test-project.test_role

In the body, specify the iot-insights-role type:

{"type": "iot-insights-role"}

You can verify if your role <test_role> is added successfully to the [manage] entry, by invoking the Policies endpoint with the following GET request:

https://bosch-iot-insights.comm/iot-things-api/<test-project>/2/policies/<test_project%3Atest-type_test-device

Verifying the device access rights

You can verify the result in your Bosch IoT Insights' project.

Proceed as follows

Log out of Bosch IoT Insights and log in again.
Open Devices > All Devices.
Select the device to which you added the access rights.
→ The Access rights button is displayed.
Click the Access rights button to verify that the new role has been added.