Authenticate as a technical client

Prepare

The Bosch IoT Suite portal offers a very convenient way to create your solution for trying out our service.

See https://developer.bosch-iot-suite.com/service/things/#serviceplans.

OAuth authentication

Bosch IoT Things provides the possibility to use OAuth to authenticate on API calls.

In case you have booked Bosch IoT Things within the Bosch IoT Suite for Asset Communication package, you can use the OAuth2 clients - section in the Suite portal and directly use these clients afterwards for authentication.

For a custom OAuth2 authorization provider you can register your client (OpenID Connect compliant) in your solution, so that tokens issued by this OAuth client can be used for API calls for your solution.

The first step is detailed in our FAQ section.

After the Things team has registered your custom OAuth2 authorization server, you can configure authorized clients for your solution, by using the HTTP API for solution management:

PUT /solutions/{solutionId}/clients
GET /solutions/{solutionId}/clients/{clientId}
PUT /solutions/{solutionId}/clients/{clientId}

tip See https://apidocs.bosch-iot-suite.com > HTTP API 2 > Solutions resources

Clients registered there are authorized to make requests in the context of your solution, which is identified by the solutionId path parameter.

To authenticate requests with a REST client you will need to provide the Authorization HTTP header containing an issued Json Web Token (JWT) Bearer ${JWT} with each request.

Example

For creating a new thing with PUT on HTTP path
/api/2/things/com.bosch.example.namespace:example-thing-4711
at the Things service, you need the following data to authenticate the request.

JWT-token  := eyJhbxxxxx

tip An example implementation using a ditto-client to retrieve a JWT-token from a “Suite OAuth2” client and authenticate with it, is available at https://github.com/eclipse/ditto-examples/blob/master/java-client/src/main/java/org/eclipse/ditto/examples/common/ExamplesBase.java.

In case you have booked a Suite package, you can manage your “Suite OAuth2” clients respectively at https://accounts.bosch-iot-suite.com/oauth2-clients/.

Public key authentication - deprecated

The process to authenticate as a technical client is similar to SSH Public Key Authentication. The public and private keys of the solution are used to authenticate a client.

To authenticate requests with a REST client you will need to provide the following HTTP headers with each request:

Authorization containing the custom authentication string:
CRS clientId;algorithm;signature.
The signature consists of the subsequent fields, separated by a semicolon and Base64 encoded:
- HTTP method e.g. PUT
- HTTP header Host e.g. things.eu-1.bosch-iot-suite.com for AWS
- HTTP path e.g. /api/2/things/com.bosch.example.namespace:example-thing-4711
Host if not already provided by e.g. the browser
HTTP header x-cr-date containing an ISO 8601 //complete date plus hours, minutes and seconds// timestamp when the request was sent
x-cr-api-token containing the API token

tip Find the technical endpoints for your specific environment in our FAQ section How to find the endpoints for my subscription?

Example

For creating a new Thing with PUT on HTTP path /api/2/things/com.bosch.example.namespace:example-thing-4711 at the Things service, you need the following data to authenticate the request.

apiToken    := eebbb40edd4544828f25f79a465xxxxx
solutionId  := eebbb40e-xxxx-xxxx-xxxx-f79a4653946b
clientId    := solutionId:frontend
algorithm   := SHA256withECDSA
timestamp   := 2018-01-27T16:11:30+01:00
method      := PUT
host        := things.eu-1.bosch-iot-suite.com
path        := /api/2/things/com.bosch.example.namespace:example-thing-4711
data        := method;host;path;timestamp
signature   := Base64Encode(SHA256withECDSA(data, algorithm))

The request must then contain the HTTP headers listed below.

Authorization: CRS clientId;algorithm;signature
Host: host
x-cr-date: timestamp
x-cr-api-token: apiToken

For a migration to OAuth 2 token authentication you can have a look at the Java client examples: https://github.com/eclipse/ditto-examples/tree/master/java-client.