Things-Client instantiation and usage

Bosch IoT Things provides a Java client, which enables integration of things and their features at the service from a Java virtual machine (JVM). The API is designed to easily create, retrieve, update and delete things and features and to register for changes made to things and features by other clients, or via our HTTP API.

A client must authenticate itself at Bosch IoT Things to successfully establish a connection. This can either be done using Basic Authentication (e.g. Register a user) or using a private/public key pair. The latter requires the client to maintain a private key. This private key is the private counterpart of the public key provided when registering a new solution (see Manage your private and public key).
Currently EC (elliptic curve) is the only supported security provider (see Oracle's info regarding Key Generator Algorithms).

In short the private/public key authentication works as follows:

  • The client requests access to the Bosch IoT Things service
  • The Things service responds with a challenge (a random string)
  • The challenge must be signed by the client with its private key
  • The signed challenge and the client ID are sent back to the Things service.
  • Finally, the Things service validates the signed challenge with the public key (provided during solution registration) and accordingly accepts or rejects the authentication.

For instructions on how to generate a private/public key pair which can be used to connect a Client see section Manage your private and public key.

Using basic authentication

Data required to instantiate a things-client:

  • apiToken: the API token of your service instance (solution)
  • username: your username for WebSocket authentication
  • password: your password for WebSocket
  • TwinConfiguration or LiveConfiguration

Example:

    private ThingsClient initializeThingsClient() {
        final CredentialsAuthenticationConfiguration credentialsAuthenticationConfiguration =
                CredentialsAuthenticationConfiguration
                        .newBuilder()
                        .username(username)
                        .password(password)
                        .build();
 
        final ThingsWsMessagingProviderConfiguration thingsWsMessagingProviderConfiguration = MessagingProviders
                .thingsWebsocketProviderBuilder()
                .authenticationConfiguration(credentialsAuthenticationConfiguration)
                .build();
 
        final TwinConfiguration twinConfiguration =
                ThingsClientFactory.configurationBuilder()
                        .apiToken(apiToken)
                        .providerConfiguration(thingsWsMessagingProviderConfiguration)
                        .build();
 
        return ThingsClientFactory.newInstance(twinConfiguration);
    }

Using private/public key authentication

Data required to instantiate a things-client:

  • apiToken: the API token of your service instance (solution)
  • solutionId: the ID of your solution
  • clientId: the client ID consists of your solutionId (see Manage your solution) and a custom suffix, separated by a colon, e.g.
    <solutionId>:<suffix>
  • keystoreLocation: the location of your keystore e.g. in the file system
  • keystorePassword: the password required to access the keystore
  • keystoreAlias: the alias of the private key inside the keystore
  • keystoreAliasPassword: the password required to access the private key
  • TwinConfiguration or LiveConfiguration

Example:

    private ThingsClient initializeThingsClient() {
 
      	final PublicKeyAuthenticationConfiguration publicKeyAuthenticationConfiguration =
                PublicKeyAuthenticationConfiguration
                        .newBuilder()
                        .clientId(clientId)
                        .keyStoreLocation(keystoreLocation)
                        .keyStorePassword(keystorePassword)
                        .alias(keystoreAlias)
                        .aliasPassword(keystoreAliasPassword)
                        .build();
 
        final ThingsWsMessagingProviderConfiguration thingsWsMessagingProviderConfiguration = MessagingProviders
                .thingsWebsocketProviderBuilder()
                .authenticationConfiguration(publicKeyAuthenticationConfiguration)
                .build();
 
        final TwinConfiguration twinConfiguration =
                ThingsClientFactory.configurationBuilder()
                        .apiToken(apiToken)
                        .providerConfiguration(thingsWsMessagingProviderConfiguration)
                        .build();
 
        return ThingsClientFactory.newInstance(twinConfiguration);
    }