Authentication

The Rollouts server can be accessed in several ways:

  • Direct Device Integration (DDI) API by IoT devices
  • Artifact downloads by targets
  • Management API by 3rd party applications
  • Device Management Federation (DMF) API by 3rd party applications through AMQP.
  • Management UI by users

Note: Access URLS are listed here

DDI API authentication modes

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

Certificate-based authentication

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.

Header Authentication

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 System Configuration view and add the certificate fingerprint of your intermediate or root CA.

Enable Certificate Authentication

Note: It is possible to enter multiple certificate fingerprints separated by semicolon. 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 in the guide How to set up client certificate-based authentication for devices. The guide also elaborates on the differences between the EU-1/US-1 and EU-2 regions.

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

Target security token authentication

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

GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
Host: device.eu1.bosch-iot-rollouts.com
Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY

The target security token is provided in DMF 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 in the target details.

Needs to be enabled for your account:

Enable Target Token

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 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 /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
Host: device.eu1.bosch-iot-rollouts.com
Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW

Needs to be enabled for your account:

Enable Gateway Token

Anonymous download (EU-2 only)

For download only it is also possible to enable anonymous access. That includes even un-encrypted data transport (e.g. HTTP without TLS). This option has to be used with care! It might be useful for scenarios where the artifact itself is already encrypted. However, a tenant that has this configuration enabled cannot protect itself from random downloads by anyone. That traffic will be charged by Rollouts on its account.

Needs to be enabled for your account:

Enable Anonymous Download

Artifact download authentication

The artifact download authentication differs between AWS (EU-1/US-1) and BIC (EU-2).

Download artifacts on AWS (EU-1/US-1)

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.

Download artifacts on BIC (EU-2)

The Bosch IoT Cloud offers two ways of downloading artifacts for Bosch IoT Rollouts. Either by using one of the provided authentication mechanisms (Target security token, Gateway security token or certificate authentication) or by allowing anonymous download.

DMF API

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

Management API

Option 1 (default): Bosch IoT Rollouts Cloud User

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

Option 2: Bring your own Bosch IoT Permissions instance (supported on EU-2 only)

  • Basic Auth
  • IM API key header field
  • IM Context ID header field
  • IM Javascript Support API Cookie

Note: check out Bosch IoT Permissions developer guide for further information.

Option 3: Authenticate with a CIAM Access Token

3rd party applications using or connecting to Bosch IoT Rollouts can also authenticate via a CIAM Access Token. Please note, that in contrast to the other two options, the tenant needs to be part of the URL.

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

Management UI

Option 1 (default): Bosch IoT Rollouts Cloud User

  • Generated Rollouts root user credentials (tenant, username, password) as provided after booking
Root User Login
  • Or as alternative sign in with Bosch account (can be added to your instance in user management view in the Management UI).
Bosch User Login

Option 2: Bring your own Bosch IoT Permissions instance (supported on EU-2 only)

  • Bosch IoT Permissions tenant, username, password into Login dialog