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}
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
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
.
Thesignature
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 anISO 8601 //complete date plus hours, minutes and seconds//
timestamp when the request was sent x-cr-api-token
containing the API token
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.