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.
Table of contents:
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:
Once logged in your Bosch Account, click the My account icon, OAuth2 Clients, and then select +New OAuth2 Client.
Type in your client name and client secret, and under Client scope select the service instances, which will be accessible by the new client.
Then click Create to add them within your client scope:
Once your ClientID and Client Secret fields have been populated you can copy them, as you will need them in the next configuration steps.
(Optional) То get a test authentication token, select Use and then Copy to clipboard.
By default, the lifetime of the access token is 720 minutes (i.e. 12 hours).
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 Bosch IoT Suite UI as well.
Configure the OAuth2 client via REST
Go to Bosch IoT Manager's Authentication Context REST API documentation and select Authorize.
Paste a token associated with the same ClientID (such as the test token) in the bearerAuth field and select Authorize.
Find the following method under Authentication and send the appropriate REST request.
POST 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:
Providing a dedicated REST endpoint
If the ClientID and Client Secret generated from the Suite portal is not an option for your solution, a third-party application should provide a dedicated REST endpoint, which ensures ways of authentication 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 instance. The configured-client-Id and 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=xxxxxxxxxxxThe 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 service instance 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 instance 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}Organization scope
When using the APIs of Bosch IoT Device Management you should select the service instances which will be accessible by the new client under Client scope. However, for some additional use cases, such as accessing models from a private Vorto repository, you should also select an Organization scope. This is the scope granted to the newly created OAuth2 client containing the role within the current organization.
Each member of your organization has a specific role, which grants specific access rights:
|
Role |
Access rights |
|
Auditor |
Read-Only role. Can access organization, team members and subscriptions, but cannot change anything. |
|
Developer |
The default role. Can create and terminate free instances. Has read access to paid instances. |
|
Manager |
Inherits permissions of role Developer. Can manage team members and paid subscriptions of an organization. |
|
Owner |
Inherits permissions of roles Manager and Developer. Can manage the account including its organization, team members and subscriptions. |
To change the role of any member of your organization visit https://accounts.bosch-iot-suite.com/team.
For more information on accessing a private Vorto repository see Configure your OAuth2 client.