Bosch IoT Rollouts

Authentication

Bosch IoT Rollouts can be accessed in several ways:

  • Management UI by users

  • Management API by 3rd party applications

  • Direct Device Integration (DDI) API by IoT devices

  • Artifact downloads by targets

  • Device Management Federation (DMF) API by 3rd party applications through AMQP

  • Service Integration Event (SIE) API by 3rd party applications through AMQP

The DDI, DMF, and SIE APIs are available for users of Bosch IoT Rollouts as a standalone service only.

They are not applicable if you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription because there the device connectivity layer is implemented by Bosch IoT Hub. For such a scenario, please read here.

Access URLs are listed at Introduction > Service plans and regions.


Table of contents:

Management UI

You need a user account to be able to use a Bosch IoT Rollouts. Navigate to the website of Bosch IoT Suite, click the My Account icon images/confluence/download/thumbnails/1680491227/my-account-version-1-modificationdate-1697803587000-api-v2.png and then the Sign in button.

Login with one of the available options:

  • Bosch Employee - the SSO login for all Bosch employees

  • SingleKey ID - the login option for externals

images/confluence/download/attachments/1680491227/roUI-concepts-auth1-version-1-modificationdate-1697804985000-api-v2.png

If you are logging in for the first time see the Create an account guide.

If you already have an account with Bosch IoT Suite, you will be redirected to https://console.bosch-iot-suite.com/.

Currently, SuiteAuth is the default authentication provider for Bosch IoT Rollouts and does not provide support for multi-factor authentication (MFA). However, the underlying identity provider (IDP) - SingleKey ID provides MFA login, where you can use your phone as a second authentication factor.

Management API

Option 1: Bosch IoT Rollouts Cloud User

  • Rollouts Basic Auth as provided after booking
    User: "TENANT\USERNAME"
    Password: "PASSWORD"

If you are using Bosch IoT Rollouts as part of your Bosch IoT Device Management subscription, Option 1 is not recommended. For details, see Differences when using Bosch IoT Rollouts standalone and within Bosch IoT Device Management.

Therefore, please apply Option 2, as described below.

Option 2: Authenticate with OAuth2

3rd party applications using or connecting to Bosch IoT Rollouts can also authenticate via OAuth2.

Two official grant types are currently supported, authorization code and client credentials. Please see RFC-6749 for detailed information.

Please note, that the tenant is always required as part of the URL, regardless of the grant type.

GET /<TENANT_ID>/rest/v1/users HTTP/1.1
Host: api.eu1.bosch-iot-rollouts.com
Authorization: Bearer <ACCESS_TOKEN>

Authorization code

An access token issued by SingleKey ID or Bosch IoT Suite is accepted.

Client credentials

An access token issued by an OAuth2 client of Bosch IoT Suite is accepted. For more details on managing clients, see Bosch IoT Suite OAuth2 clients.


In order to register your client successfully with a Rollouts instance, it is important to be able to request the tenant-related service instance ID as scope. This can be defined when creating the Suite Client, but can also be modified at a later point in time.

The first successful call against the Management API that has the necessary scopes, will receive a 403 response - Forbidden Status Code.

With this initial request, the client will be registered and listed in the User Management. The ClientID will be used as the username. The administrator or operator can then configure the still empty permission set and assign the necessary rights.



Direct Device Integration API

Bosch IoT Rollouts supports multiple ways to authenticate a target against the server. The different authentication modes can be individually enabled and disabled within Bosch IoT Rollouts.

Certificate-based authentication

Bosch IoT Rollouts allows the authentication based on X.509 certificates. This is the preferred authentication mode. In this case, the target (device) needs to send a complete (self-contained) certificate chain along with the request which is then validated by a trusted reverse proxy. The certificate chain can contain multiple certificates, e.g. a target-specific client certificate, an intermediate certificate, and a root certificate.

After terminating the TLS connection, the proxy validates the certificate chain and, provided the chain is valid, retrieves the fingerprint of each certificate. The fingerprints as well as the common name of the client certificate are then forwarded to the DDI server using special HTTP headers. Note that the common name of the client certificate needs to match the ID of the addressed target. To establish trust with the client certificate of the target, the fingerprints of the root and intermediate certificate are then matched against the certificate fingerprints that are stored in the system configuration of your account.

images/confluence/download/attachments/1680491227/authentication_reverse_proxy-version-1-modificationdate-1618840927000-api-v2.png


X-SSL-ISSUER-HASH-1: 2e:24:d0:ce:31:9c:9c:fd:5b:88:0f:b4:67:6c:2e:2a
X-SSL-ISSUER-HASH-2: 0e:da:70:c8:e1:e1:fb:79:80:cd:dd:69:e4:0c:ca:79

If you want to use this authentication mode, you need to enable it for your account in the Configuration UI feature:

  1. Enter edit mode via the Edit icon on the top right of the view.

    images/confluence/download/thumbnails/1680491227/roUI-configuration-editMode-version-1-modificationdate-1700574795000-api-v2.png
  2. Enable the Allow targets to authenticate via a certificate authenticated by a reverse proxy.

  3. Аdd the certificate fingerprint of your intermediate or root CA.

images/confluence/download/attachments/1680491227/roUI-configuration-authViaCertificateReverseProxy-version-1-modificationdate-1700573865000-api-v2.png

Note: It is possible to enter multiple certificate fingerprints separated by semicolon. Bosch IoT Rollouts verifies that at least one of the provided fingerprints matches one of the incoming issuer hash headers. This is useful for certificate migration.

Find more details about this authentication mode including step-by-step instructions based on OpenSSL and cURL at Set up client certificate-based authentication for devices.

For a dedicated certificate management for embedded devices, please have a look at CycurV2X-PKI by ESCRYPT.

Target security token authentication

There is a 32 alphanumeric character security-token for each created target within Bosch IoT Rollouts. This token can be used to authenticate the target at Bosch IoT Rollouts through the HTTP-Authorization header with the custom scheme TargetToken.

GET /<TENANT_ID>/controller/v1/<CONTROLLER_ID> HTTP/1.1
Host: device.eu1.bosch-iot-rollouts.com
Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY

The target security token is provided in Device Management Federation API as part of the update message in order to allow DMF clients to leverage the feature or it can be manually retrieved per target by Management API or in the Management UI (Classic) in the target details.

Needs to be enabled for your account from the Configuration UI feature:

images/confluence/download/attachments/1680491227/roUI-configuration-authViaTargetSecurityToken-version-1-modificationdate-1700574779000-api-v2.png

Gateway security token authentication

Often the targets are connected through a gateway which manages the targets directly and as a result are indirectly connected to the Bosch IoT Rollouts update server.

To authenticate this gateway and allow it to manage all target instances under its tenant there is a GatewayToken, to authenticate this gateway through the HTTP-Authorization header with a custom scheme GatewayToken. This is of course also handy during development or for testing purposes. However, we generally recommend to use this token with great care as it allows to act “in the name of” any device.

GET /<TENANT_ID>/controller/v1/<CONTROLLER_ID> HTTP/1.1
Host: device.eu1.bosch-iot-rollouts.com
Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW

Needs to be enabled for your account from the Configuration UI:

  1. Enable the Allow a gateway to authenticate and manage multiple targets through a gateway security token configuration.

  2. Click Show and copy the token via the icon on its right.

images/confluence/download/attachments/1680491227/roUI-configuration-authViaGatewaySecurityToken-version-1-modificationdate-1700574876000-api-v2.png

Artifact download authentication

Download artifacts

Within Bosch IoT Rollouts the artifact download is done by signed URLs. This means that there is no device authentication necessary (DDI credentials) when downloading an artifact. However, to get the download URL by deployment base the device has to be authenticated. Furthermore, the received download URL has a validity expiration of 1 month. This means that devices might have to re-call deployment base if access is denied. Artifacts are delivered through a worldwide Content Delivery Network (CDN) to provide high availability and performance for downloads.

Device Management Federation (DMF) API and Service Integration Event (SIE) API

Authentication is provided by the Bosch IoT Rollouts service broker interface with a separate RabbitMQ vhost and user credentials per service binding.