Set up OAuth2 client for third-party applications

When working with the Bosch IoT Manager web console, the remote service takes care to get all required access tokens for uninterrupted work. However, when a third-party application accesses the Bosch IoT Device Management APIs remotely, this application needs to be authorized separately in order to access all the needed remote services and resources. This is performed by setting up an OAuth2 client. In this page you will learn how to create and configure an OAuth2 client and what are the options to refresh tokens.

Create OAuth2 client

A new OAuth2 client can be created for every subscription through the bosch-iot-suite.com portal as shown in the steps below:

  1. Once logged in your Bosch Account, click the My account icon, OAuth2 Clients, and then select +New OAuth2 Client.

    images/confluence/download/attachments/1379512265/create_oauth2Client1.gif
  2. Type in your client name, select the service instances, which will be accesible by the new client and select Create:

    images/confluence/download/attachments/1379512265/create_oauth2Client2.png
  3. Once your ClientID and Client Secret fields have been populated you can copy them, as you will need them in the next configuration steps.

    images/confluence/download/attachments/1379512265/create_oauth2Client3.png
  4. (Optional) То get a test authentication token, select Use and then Copy to clipboard.

    images/confluence/download/attachments/1379512265/create_oauth2Client4.png

    On thе Use OAuth2 client step you will also find an HTTPS request to create a token in your application, a cURL example and a Java example with Spring security OAuth2 boot.


As an alternative you can get your authentication token through the Developer Console as well.

Configure the OAuth2 client via REST

  1. Go to Bosch IoT Manager's REST API documentation and select Authorize.

  2. Paste a token associated with the same ClientID (such as the test token) in the bearerAuth field and select Authorize.

  3. Find the following method under Authentication and send the appropriate REST request.

    POST <host>/auth/ctx/config/{serviceInstanceId}/{clientId}

    The body of the request should follow the pattern:

{
"refreshURL": "string",
"credentials": {
"clientId": "string",
"clientSecret": "string"
},
"grantType": "refresh_token", // or "grantType": "client_credentials"
"authMethod": "client_secret_basic", // or "authMethod": "client_secret_post"
"refreshTokenValidityPeriodSec": <period-in-sec-the-refresh-token-is-valid>
}

Configure the OAuth2 client via gRPC

Use the following code snippet to configure the OAuth2 client for your Java application:

import com.bosch.iot.auth.Credentials;
import com.bosch.iot.auth.RefreshConfig;
import com.bosch.iot.auth.RefreshConfig.GrantType;
import com.bosch.iot.auth.ctx.manager.remote.AuthCtxEntry;
import com.bosch.iot.auth.ctx.manager.remote.AuthCtxManagerRemote;
import com.bosch.iot.dm.grpc.sa.GRPCClient;
import com.bosch.iot.dm.grpc.sa.Token;
 
public void configure(String serviceInstanceId, String clientId, String token) {
GRPCClient client = GRPCClient.getInstance(SSL, HOST, PORT, vertx);
 
AuthCtxManagerRemote authManager = client.service(AuthCtxManagerRemote.class, new Token(token));
 
String refreshURL = "https://access-int.bosch-iot-suite.com/v2/oauth2/token";
 
RefreshConfig ccConfig = RefreshConfig.newBuilder().refreshURL(refreshURL).grantType(GrantType.CLIENT_CREDENTIALS)
.credentials(Credentials.newBuilder().clientId("clientId").clientSecret("clientSecret").build()).build();
 
authManager.storeRefreshConfiguration(serviceInstanceId, clientId, ccConfig);
}

Refresh tokens from third-party clients

Longer usage of the Bosch IoT Device Management APIs and time-consuming jobs, such as rule execution or listening for events, require setting up a mechanism for acquiring refresh tokens for the third-party application.

When it comes to usage with third-party authentication clients, tokens can be refreshed following two main approaches. As part of the first approach the client can provide a specific 'user' and 'password' for a dedicated third-party REST callback endpoint, that could be a proxy to its own OAuth provider. The second approach includes exchanging the ClientID and Client Secret used for authentication to the SuiteAuth service and to the third-party application . See approach 1 (green) and approach 2 (blue) in the graph below for better understanding:

images/confluence/download/attachments/1379512265/dm_dev_thirdPartySuiteAuth.png

Providing a dedicated REST endpoint

When providing the ClientID and Client Secret, generated from the Suite portal, is not an option, the third-party application should provide a dedicated REST endpoint, which ensures ways of autentication to the Bosch IoT Device Management APIs. This REST Endpoint should be always online as the remote service will send REST requests to it. In this case the third-party application should take care of all refreshing of tokens.

The important difference between this and the second approach is that here the ClientID and Client Secret generated by the Suite portal are not shared with the Bosch IoT Device Management package. The configured-client-Id и configured-client-secret exchanged between the third-party application and the service differ from the originally created ones ones, and are used only in this purpose for security reasons.

The dedicated REST endoint can support the following grant types:

  • Refresh_token grant type

When using this grant type the third-party endpoint should support the POST <configured-refresh-URL> REST method with the following body:

grant_type=refresh_token
&client_id=<configured-client-Id>
&client_secret=<configured-client-secret>
&refresh_token=xxxxxxxxxxx

The valid response should follow the format:

ContentType: application/json
{
"access_token":"<valid-access-token>",
"refresh_token":"<valid-refresh-token>",
...

To use this dedicated REST endpoint mechanism for token refresh, the initial configuration must include:

{
"refreshURL": "<configured-refresh-URL>",
"credentials": {
"clientId": "<configured-client-Id>",
"clientSecret": "<configured-client-secret>"
},
"grantType": "refresh_token", // or "client_credentials"
"authMethod": "client_secret_post",
"refreshTokenValidityPeriodSec": <period-in-sec-the-refresh-token-is-valid>
}

The refreshURL is the address of the third-party application, which will not provide the original ClientID and Client Secret.

Another specific when using this refresh mechanism, is that the third-party application needs to ensure that the refresh token is provided to Bosch IoT Device Management. This includes informing the package until when the token is valid and requesting a new token on its own.

  • Client_credentials grant type

When using this grant type the third-party endpoint should support the POST <configured-refresh-URL> REST method with the following body:

grant_type=client_credentials
&client_id=<configured-client-Id>
&client_secret=<configured-client-secret>
&scope=<scope-from-access-token>

While the response should follow the pattern:

ContentType: application/json
{
"access_token":"<valid-access-token>",
...
}

To use this mechanism for client credentials, the initial configuration must include:

{
"refreshURL": "<configured-refresh-URL>", // for example "https://access-int.bosch-iot-suite.com/token"
"credentials": {
"clientId": "<configured-client-Id>",
"clientSecret": "<configured-client-secret>"
},
"grantType": "client_credentials",
"authMethod": "client_secret_post",
"refreshTokenValidityPeriodSec": 0 // the value does not matter as the refresh token is not used
}

Providing the Suite-generated ClientID and Client Secret

This refresh manner involves direct communication with an existing OAuth2 provider endpoint, such as the SuiteAuth one, and does not require the creation of a dedicated REST endpoint. See approach 2 (blue) in the graph. It exchanges the original ClientID and Client Secret generated by the Bosch IoT Suite portal, as shown in the Create OAuth2 client section.

Again, like in the first option, the OAuth client can support both the refresh_token and client_credentials grant types. If this refresh mechanism is selected, once the OAuth2 client is configured in Bosch IoT Device Management, the service package will request the new tokens when needed, as it directly connects to the SuiteAuth.

To use this mechanism for client credentials, the initial configuration must include:

{
"refreshURL": "<SuiteAuth-URL>", // for example "https://access.bosch-iot-suite.com/token"
"credentials": {
"clientId": "<SuiteAuth-client-Id>",
"clientSecret": "<SuiteAuth-client-secret>"
},
"grantType": "client_credentials",
"authMethod": "client_secret_post",
"refreshTokenValidityPeriodSec": 0 // the value does not matter as the refresh token is not used
}