Authentication and authorization

You can integrate your solutions with the Bosch IoT Things service in two ways:

  • Via the HTTP API, or
  • Via a Java API by using a Java client that communicates to our service via WebSocket.

On all APIs the service protects 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

Authentication

User authentication at the HTTP API

A user who calls the HTTP API can be authenticated by using:

  • HTTP BASIC Authentication by providing username (with tenant information) and password of users managed within the Bosch IoT Permissions service.
  • The Identity Context of a currently logged in user managed within the Bosch IoT Permissions service.
  • A JSON Web Token (JWT) issued by Bosch IoT Permissions, Bosch ID or Google.

See Authenticate as a user for more details.

Technical client authentication at the HTTP API

When technical clients use the HTTP API each request must be authenticated by using an OAuth token. The solution must provide the signature of defined HTTP headers which are concatenated and signed with the private key of the solution client. This signature must be sent with each request in the HTTP header: Authorization: CRS clientId;algorithm;signature.

Within the Authorization HTTP header, the clientId must also be sent, and it identifies the Solution that is executing the request.
See Authenticate as a technical client for more details.

Authentication within the Java client

When the Things service is used with the Java client, the client must be identified and authenticated. The client is identified by its clientId.
To be able to recognize, which solution is calling the Things service, the Client ID consists of:

  • The ID of the Solution which is using the Java client,
  • And a custom suffix to support the usage of multiple clients per solution.

clientId = <solutionId> + ":" + <suffix>

The client authentication is implemented by either OAuth2 or a handshake using an asymmetrical key-pair. The public key of this handshake has to be configured at the Things service for a solution. The private key must be kept secret by the Solution.
See Things-Client instantiation and usage for details.

Authorization

Authorization is implemented with a Policy. The Policy description is located at Thing level, however it can optionally grant or revoke permissions very fine-grained at any Thing sub-resource like thing:/features/featureX/properties/propertyN.

tip Find details at Policies.

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 header x-cr-api-token with the value of your API token on each HTTP request.

Schematic view

authorization example

[1] Authenticate a user

  • Bosch JWT → Bosch ID can be used as authorized subject
  • Bosch IoT Permissions → user ID, group ID, role ID, can be used as authorized subject
    • Basic authentication
    • Identity-context ID
    • JSON Web Token (JWT)
  • Google JWT → Google account ID can be used as authorized subject

[2] Authenticate a technical client

  • OAuth2 token authentication
  • Cryptographic challenge - deprecated

[3] Identify a solution

  • API Token (HTTP header)
  • Client ID
  • Solution ID
  • Suite authorization token
Imprint Legal info Privacy statement