Authentication and authorization
The Bosch IoT Things service protects your digital twin’s functionality and data by using::
- Authentication to make sure the requestor is the one he states
- Authorization to make sure the requestor is allowed to see, use or change the information he wants to access
- Identification of your Solution whenever an API is called
In general, we encourage our customers to use an OAuth2 authorization provider (with OpenID Connect compatible tools and flows). Coming from the Bosch IoT Suite perspective, of course our favorites are tokens issued by our Suite Auth service.
In case you have not started yet, we encourage you to book a Bosch IoT Suite for Asset Communication package, as for such packages you automatically get access to the Suite Auth functionality. Find an example at Create a Suite Auth client.
Bosch IoT Things service makes sure that ALL requestors who need to interact with the service are authenticated. Users and technical clients might interact either directly (e.g. get thing HTTP request) or via a connection (e.g. device updating its data via a persistent AMQP connection to Bosch IoT Hub), and might want to act either in their own context or in the context of a solution.
Authentication is done via a JSON Web Token (JWT). The JWT can be issued by one of the following providers:
- Suite Auth – service of the Bosch IoT Suite
- Used mainly for other Suite services e.g. Bosch IoT Hub
- Bosch ID
- This is the provider you have used already for subscribing our services
- Bosch ID can be also used for other on end-users of your IoT solution
- Used mainly for end-users
- Custom OAuth2 authorization provider
- Can be used for end-users / technical users or technical clients alike
- Must be OpenID Connect compliant
- You can register clients for your solution via API
See Create or update all authorized Clients of a specific Solution.
- Authentication of a technical client by a handshake using an asymmetrical key-pair has been deprecated as of February 2020. The public key of this handshake needs to be configured at the Things service for a solution. The private key must be kept secret by the Solution.
- Bosch IoT Permissions has been deprecated as of March 2020.
Authorization is implemented with a policy.
Each thing is related to a policy, which controls who can see or even change a thing.
The “subjects” are derived from the authentication provider. Find a detailed table with examples on how the derived subjects look like at Policies.
The policy can grant access to itself, the complete thing, or optionally
even revoke permissions very fine-grained at any thing sub-resource like
Find details at Policies.
The service subscription itself and its sub-resources like namespace, connections, clients and usage, is protected via a separate solution policy.
Solution identification on API access
Regardless which API you use or which objects you work with, you have to identify your solution when accessing the APIs. This identification is used to generally make sure that only authorized solutions can access the service.
When the service is booked, a solution ID and an API token are generated during registration. Both are used to identify the solution when the service is called via its APIs.
However, the API token and the solution ID are not sufficient to grant access to any information about data (which your solution manages within the Things service). It just grants general access to use the APIs of the service.
To prevent abuse of your service subscription treat the API token information securely and do not expose it publicly anywhere.
Depending on the authentication mechanism, the identification of your solution happens as follows:
- When using the things-client your solution is identified implicitly based on the provided clientId.
- When using a Suite authorization token your solution is implicitly identified by the service instance id contained in the access token.
- When using basic authentication with solution ID and solution secret, your solution is already identified by the provided solution ID.
- For all other authentication mechanisms you need to provide a HTTP
x-cr-api-tokenwith the value of your API token on each HTTP request.