Skip to content

Industrial IoT Gateway

Introduction

Industrial IoT Gateway acts as gateway to Insights Hub backend for web application clients, agents and edge applications, as well as all external and internal app backends and services. Web applications or web services integrated with Industrial IoT Gateway can be reached from the internet using the external gateway access. The routing has to be defined by every provider of apps or services using Gateway Registry. The identity management is integrated with gateway to support web application OAuth 2.0 authorization code flows and to exchange access tokens of interactive or active clients in cross-provider requests.

gateway

RFC compliance

Standards

Industrial IoT Gateway complies with the following standards, and expects compliance with these standards from each client which intends to interact with Insights Hub via Industrial IoT Gateway.

Note

Industrial IoT Gateway does not support any behavior which violates these standards.
In case if any violation of standards is discovered, it will be fixed immediately without further notification, in favor of general system availability, stability and reliability.

Example of a typical violation of the standard

The following URL has a common mistake:

Non-RFC compliant URL:

https://example-application.eu1.mindsphere.io/getDataByIds?idList=[1,2,3,4,5,6]

RFC compliant version:

https://example-application.eu1.mindsphere.io/getDataByIds?idList=%5B1,2,3,4,5,6%5D

Explanation: As per RFC-3986, the characters [ and ] belong to the gen-delims set, which are not allowed in the query string part of the URL. However, the query string may contain characters belonging to the pchar set, which includes the sub-delims set. As the comma character is part of this set, it does not need to be encoded.
Percent-encoding the comma characters too would be within the boundaries of the standard.

Using reserved characters in the URL

Every part of the URL has it's own schema, which come with a different set of reserved characters. Developers need to take this into consideration when encoding or decoding the URLs. For further information, please read Section 2 and Section 3 of RFC-3986.

URL Schemes

In the following, the URL schemes of public URLs mapped to Industrial IoT Gateway are defined. Public URLs are callable from the internet. Industrial IoT Gateway routes requests to public URLs to registered internal IPs like your internal Cloud Foundry app route.

Curly brackets {} are used to define placeholders for mandatory URL parts and square brackets [ ] to define placeholders required only in defined specific cases.

Call to Web Application

A web application hosted in Insights Hub can be exposed at the gateway under the following hostname:

{tenantName}-{webApp}[-{provider}].{region}[-{env}].{mindsphere-domain}/[{path}]

Description

  • {tenantName} identifies the tenant accessing the web application. It helps to direct the user to the IdP(s) available for that tenant and also allows creating tenant-specific bookmarks in the browser.
  • {webapp}[-{provider}] identifies the web application uniquely. Insights Hub core web applications omit the provider part, while other web applications need to include this part to avoid name collisions and in order to keep the core namespace clean.
  • {region}[-{env}] identifies the data center region the request is issued to. The env part identifies the environment (e.g. preview) and is only appended for the preview environment.
  • {mindsphere-domain} identifies the domain of the data center the request is issued to.
  • [{path}] optional path parameters, to reach sub-content of the web application. The first path parameter needs to be different from /api to avoid conflicts with API routing.

Examples

  • abc-assetmanager.eu1.mindsphere.io: a user of tenant abc loads content from the Asset Manager web application in region Europe 1, production environment.
  • abc-assetmanager-xyz.eu2.mindsphere.io/index.html: a user of tenant abc loads the index page from the Asset Manager web application of provider xyz in region Europe 2, production environment.
  • xyz-assetmanager-xyz.cn1.mindsphere-in.cn/images/icon.jpg: a user of tenant xyz loads an icon from the Asset Manager web application of provider xyz in region China 1, production environment.

Web Application Client Call to API

The web application client calls Insights Hub APIs under the same hostname that it was retrieved. The URL path parameter determines the target of the call.

{webAppHost}/api/{apiName}[-{apiProvider}]/v{major}/{endpoint}

Description

  • {webAppHost} is according to the Call to Web Application section.
  • {apiName}[-{apiProvider}] uniquely identifies the API. Core APIs omit the apiProvider part for URL simplicity. Non-core APIs need to append the provider name of the API to avoid name collisions and keep the core namespace clean.
  • v{major} identifies the major version of the API.
  • {endpoint} identifies an endpoint of the API. Can be a nested path.

Examples

  • abc-assetmanager.eu2.mindsphere.io/api/iot/v2/assets: a user of tenant abc uses the Asset Manager web application client in region Europe 2, to access the IoT core API v2, endpoint assets.
  • abc-assetmanager.eu1.mindsphere.io/services/assetmanager/v3/fleets: a user of tenant abc uses the Asset Manager web application client in region Europe 1, to access the assetmanager UI mashup (core) API v3, endpoint fleets.
  • abc-assetmanager-xyz.eu2.mindsphere.io/services/iot-xyz/v3/assets/46b55e6f: a user of tenant abc uses the xyz Asset Manager web application client in region Europe 2, to access the xyz IoT Services v3, endpoint assets/46b55e6f.

Active Client Call to API

Active clients are supposed to be running outside of a web browser. They don't require a tenant or web application identifier in the hostname. The target API is determined in the same way as for web application client calls, though.

gateway.{region}[-{env}].{mindsphere-domain}/api/{apiName}[-{apiProvider}]/v{major}/{endpoint}

Description

Examples

  • gateway.region123.mindsphere.io/api/iot/v3/assets: a client calls region region123, to access the IoT core API v3, endpoint assets.
  • gateway.region123.mindsphere.io/api/assetmanagement/v3/assets: a client calls region region123, to access the Asset Management API v3, endpoint assets.

Device Agent Call to agents or edge API

Device agents call Insights Hub in the same way as general northbound clients, but use a different subdomain name.

southgate.{region}[-{env}].{mindsphere-domain}/api/{apiName}[-{apiProvider}]/v{major}/{endpoint}

Description

Examples

  • southgate.eu1.mindsphere.io/api/service/v3/serviceEndpoint: an agent calls region Europe 1, production environment to access the service API v3, endpoint serviceEndpoint.

URL Patterns

Industrial IoT Gateway supports Ant-style path pattern matching.

Path Pattern Matching and Wildcard Support

Users can register their API endpoint paths using the following wildcards: ?, *, **.

Character Description
? matches exactly one character
* matches zero or more characters
** matches zero or more directories in a path

Examples

  • /? pattern matches "/e", "/b" paths, but does not match "/endpoint" path, etc.
  • /en?po?nt pattern matches "endpoint", "enbpoent" paths, etc.
  • /?ndpoint pattern matches "endpoint", "andpoint" paths, etc.

  • /* pattern matches "", "/", "/endpoint", "/epoint" paths, etc.
  • /*/endpoint pattern matches "/api/endpoint", "//endpoint" paths, but does not match "/api//endpoint", "/api/andpont" paths, etc.
  • public/*.jsp pattern matches all ".jsp files" in the public directory.

  • /** pattern matches basically every path, not just the following examples: "", "/", "/endpoint", "/public/endpoint", "///endpoint", etc.
  • /**/endpoint pattern matches "/endpoint", "//endpoint", "/public/endpoint", "/public/directory/in/path/endpoint" paths, but does not match "/public/directory/noendpoint" path, etc.
  • /**/endpoint/** pattern matches "/endpoint", "/endpoint/directory", "/public/endpoint/directory/in/path" paths, but does not match "/public/directory/noendpoint" path, etc.

  • /*/end?oint/** pattern matches "/directory/endpoint/directories/in/path", "//endpoint/" paths, but does not match "/directories/in/path/andpoint/directories/in/path" path, etc.

Restrictions

The following restrictions are enforced when making requests to either your own registered applications or Insights Hub APIs. These are only Industrial IoT Gateway limitations, individual limitations of Insights Hub API endpoints may be stricter.

Option Value Description
Connection idle timeout 60 seconds Timeout when forwarding request to a backend service. If there is no data traffic for this amount of time, then Industrial IoT Gateway (and/or the ALB) closes the connection. Services could theoretically keep alive WebSocket connections indefinitely, by sending at least 1 byte every minute.
Parallel connection count 400 Maximum number of simultaneous connections per Industrial IoT Gateway instance.
Cache invalidation timeout 12 hours Industrial IoT Gateway internal cache timeout (Invalidation of data loaded from dependent services such as Gateway Registry).
Session timeout 12 hours Maximum lifetime of a user session. Users must re-login after this time.
Session inactive timeout 30 minutes Maximum lifetime of a session without user activity.
Session cookie timeout Infinite Maximum lifetime of the session cookie.
Access token expiration 30 minutes Expiration time of an access token.
Refresh token expiration 12 hours Expiration time of a refresh token.
Maximum request size 150 MB Maximum size of a request that can be sent.
Maximum file size 100 MB Maximum size of files that can be attached to a multi part request.
Maximum header size 16 kB Maximum size of headers in a request.

Connection Idle Timeout

Industrial IoT Gateway imposes an idle timeout restriction on both HTTP and WebSocket connections.

A connection is kept alive by sending at least one byte per minute. Otherwise, Industrial IoT Gateway closes the connection and the client needs to retry the request or reconnect to the WebSocket.

gateway

Large Request Restrictions

If the maximum request or file size is exceeded, typically when uploading files, the Industrial IoT Gateway responds with HTTP status 413 Payload Too Large and then immediately closes the connection. Clients should always monitor the network connection for an error response, because they will not be able to read it after the connection was closed.

Examples

Scenario Content-Type HTTP Status Message
Request with 1 file less than 100 MB multipart/form-data 200 OK {Service specific message}
Request with 1 file more than 100 MB multipart/form-data 413 Payload Too Large Request content length limit exceeded
Request with 2 files, each less than 100 MB, summed up less than 150 MB multipart/form-data 200 OK {Service specific message}
Request with 2 files, each less than 100 MB, summed up more than 150 MB multipart/form-data 413 Payload Too Large Request content length limit exceeded
Request less than 150 MB non multipart/form-data 200 OK {Service specific message}
Request more than 150 MB any type 413 Payload Too Large Request content length limit exceeded

Temporary Blocking of Slowly Responding Endpoints

When requests are sent to endpoints faster than they can be processed, pending requests could overload Industrial IoT Gateway instances. This is prevented by greylisting the endpoints, where access to slowly responding endpoints is blocked temporarily if the load of an instance exceeds a limit.

When an endpoint is greylisted, requests receive a response with HTTP status 503 Backend service too slow. Currently, endpoints count as slow when their response time is longer than 30 seconds, and greylisting lasts for 5 minutes. During this period requests are only forwarded to the endpoint, if the concurrent connection count is below 80%.

Info

Slowly responding endpoints are currently not blocked but just reported.

Gateway Error Content Types

Gateway error responses are sent in XML or JSON format. If a request shall receive error responses, it must accept these media types. Otherwise, Industrial IoT Gateway sends HTTP status 406 Not acceptable, if an error occurs.
Example header:

Accept: application/json, application/xml

Security

Authorization

Though Industrial IoT Gateway applies security measures to protect web applications and services in the Insights Hub backend, every web application and service is responsible to apply authorization validations to ensure working access control.

Required claims

In case authentication with JWT access token is required, the "ten" claim becomes mandatory. In the internal API calls, gateway uses this for routing. If the claim is missing or malformed, gateway responds with HTTP status 403 Forbidden. For more information on claims refer Construction of Self-Signed JWT and Payload Validation.

Cross-Site-Request-Forgery

Industrial IoT Gateway requires web applications to use the provided CSRF token mechanism, including a same origin check based on the origin http header.

Content-Security-Policies (CSP)

Industrial IoT Gateway applies a strict Content Security Policy header for web applications, which is not configurable for 3rd parties. All served resources must come from the application uri or the static content uri (static.{region}[-{env}].{mindsphere-domain}).

A web application may employ the use of CSP by including one of the following HTTP headers in the response:

  • Content-Security-Policy
  • Content-Security-Policy-Report-Only

By default, Industrial IoT Gateway adds a CSP header for web applications:

Content-Security-Policy: default-src 'self' static.{region}.{mindsphere-domain}; style-src * 'unsafe-inline'; script-src 'self' 'unsafe-inline' static.{region}.{mindsphere-domain}; img-src * data:;

parties. For more information about CSP read the official specification from the W3C or the CSP documentation from MDN web docs.

Additional HTTP-Headers set by Industrial IoT Gateway

Industrial IoT Gateway includes two additional HTTP-Headers X-XSS-Protection and X-Content-Type-Options. The X-XSS-Protection is provided for compatibility reasons for users of older browsers and is used to prevent the loading of the pages when they detect reflected cross-site-scripting (XSS) attack. See also the corresponding documentation about the X-XSS-Protection header.

The X-Content-Type-Options header is set to nosniff. This directive blocks the request if the request destination is of type:

  • "style" and the MIME type is not text/css or
  • "script" and the MIME type is not a JavaScript MIME Type

This means that you have to make sure that your application delivers the proper MIME-type for the script and style files. See also the corresponding documentation about the X-Content-Type-Options header.

Cache Control

Industrial IoT Gateway can use the specified Cache-Control header values of web applications for caching mechanisms in both requests and responses. The configuration value is the Cache-Control directive list that contains the cache configuration rules in compliance with the Cache-Control header specification.

  • If the Cache-Control header is provided in the HTTP response, Industrial IoT Gateway forwards it to the client application.
  • If the Cache-Control header in the HTTP response is blank or not available, Industrial IoT Gateway adds the Cache-Control header configured during the application upload.
  • If the Cache-Control header configured during the application upload is blank, the following default value is added to the response:
Cache-Control: no-cache, no-store, max-age=0, must-revalidate

If the client application uses HTTP/1.0 protocol and the response contains a Cache-Control header with the value no-cache, Industrial IoT Gateway appends Pragma: no-cache and Expires: 0 headers to the response. For HTTP/1.1 protocol and above those headers are omitted.

AJAX Requests

Non AJAX HTTP requests are redirected to the login page, if no valid session is available.
AJAX HTTP requests with header X-Requested-With: XMLHttpRequest receive HTTP status 401 Unauthorized, if no valid session is available.

WebSockets

The WebSocket communication protocol allows for full-duplex communication over a TCP connection. Industrial IoT Gateway supports WebSocket connections between web client and server of a web application. In order to enable WebSockets, the web client and the backend server must be able to establish and drive the WebSocket connection using the secured wss scheme. Industrial IoT Gateway acts as proxy for WebSocket connections, similar as for HTTP requests.

Configuring Applications for WebSocket Connections

To configure WebSockets, an application requires an endpoint registered at Industrial IoT Gateway, which allows for HTTP GET requests and is capable of WebSocket. When the web client sends a WebSocket Upgrade request to this endpoint, the WebSocket connection is established it.

Note

Currently, websocket access through southgate is not supported.

Example: The application myApp with the internal URL myApp.apps.eu1.mindsphere.io has an endpoint capable of WebSocket at path /videostream. The application is provided by an operator tenant myOperator and available at Industrial IoT Gateway for a tenant myTenant as myTenant-myApp-myOperator.eu1.mindsphere.io. The web client of myApp can establish a WebSocket connection to its backend via wss://myTenant-myApp-myOperator.eu1.mindsphere.io/videostream, which is forwarded to wss://myApp.apps.eu1.mindsphere.io/videostream.

Authentication and Authorization

Authentication and authorization for WebSocket connections is based on the same mechanisms as for HTTP requests. Web sessions are used between client and Industrial IoT Gateway, while Bearer access tokens are used for internally forwarded requests. After establishing a WebSocket connection however, the HTTP session and access token are no longer attached in the communication between the web client and the server, because WebSocket messages do not have a header part.

If the HTTP session expires or the user of the web client logs out, the session and consequently the WebSocket connection will be closed.
Industrial IoT Gateway will keep the HTTP session alive internally, if there is traffic on the WebSocket connection.

Supported WebSocket Protocols

Industrial IoT Gateway does not restrict the protocols used on top of WebSockets. This allows two applications (communicating through Industrial IoT Gateway using WebSockets) to freely choose their "language", with the premise that both support the same protocol. Industrial IoT Gateway forwards every WebSocket message as binary, without interfering with the chosen protocol. For example, the following protocols can be used: STOMP, Socket.IO, MQTT, or custom protocols *.

WebSocket Connection Details

Headers

WebSocket connections start with a regular HTTP request, the so-called Upgrade request. The web client and server must negotiate which version and extensions to use. After successful negotiation, the server returns an HTTP 101 status code and the TCP socket is kept open for WebSocket communication.
The following table contains the usual headers for an Upgrade request. The header names and values are case-insensitive.
For optional headers, empty string as a value is not permitted. In this case, the header name must not be present.

header name header value required
Cookie: SESSION=<session-id>; REGION-SESSION=<region-session-id> yes
Connection: Upgrade yes
Upgrade: WebSocket yes
Sec-WebSocket-Version: 13* yes
Sec-WebSocket-Key: <generated websocket key> yes
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits * no
Sec-WebSocket-Protocol: <comma separated list> * ** no

Communication Flow

  1. The web client performs a WebSocket protocol Upgrade HTTP request to an endpoint of the application registered at Industrial IoT Gateway.
  2. Industrial IoT Gateway evaluates the session headers and the called application endpoint.
  3. Industrial IoT Gateway creates a WebSocket web client connection to the targeted endpoint.
  4. Industrial IoT Gateway performs a new WebSocket protocol Upgrade HTTP request to the registered application backend.
  5. Industrial IoT Gateway responds with HTTP status code 101 and the necessary headers for a WebSocket Upgrade.
  6. In case of success, client and backend are able to bidirectionally send messages over the proxied WebSocket.
  7. In case the connection of Industrial IoT Gateway to the application backend fails, Industrial IoT Gateway closes the HTTP connection to the web client with status 400 Bad Request.

The following sequence diagram shows an example communication between a web client (browser) and its backend, with Industrial IoT Gateway as proxy. gateway

Effect of Autoscaling and Deployment

When a new version of Industrial IoT Gateway is deployed, websocket connections will be terminated after the Blue/Green switch. Also, autoscaling will shut down instances which may have an open websocket connection.

User applications should expect that the websocket connection can be dropped at any time, and in this case they should try to reconnect.

Ping/Pong messages

Currently, no browser exposes the ping/pong message API for JavaScript. This means that the applications in the browser cannot send a low-level ping message every minute. Using other protocols like STOMP or Socket.IO, you can work around this issue by sending a high-level ping message. The other solution is that the server needs to send a periodic ping message to the browsers and all modern browsers will respond with a pong message.

WebSocket usage example in JavaScript

'use strict';
function connectWebsocket (url, protocols) {
  var socket;
  if (typeof protocols !== 'undefined' && protocols.length > 0) {
    // the array is defined and has at least one element
    socket = new WebSocket(url, protocols);
  } else {
    socket = new WebSocket(url);
    /*  
    *  The second parameter must be completly omitted in this case.
    *  If it is present, then an empty Sec-WebSocket-Protocol header will be added in most browsers,
    *  which will result in a connection error.
    *  The following code examples will produce an error:
    *  socket = new WebSocket(url , []);
    *  socket = new WebSocket(url , "");
    *  socket = new WebSocket(url , null);
    */
  }
  return socket;
}
// Example: using this function with ocpp subprotocol
var wsUrl = 'wss://tenant-application.eu1.mindsphere.io/websocket/example';
var subProtocols = [ 'ocpp2.0', 'ocpp1.6', 'ocpp1.5', 'ocpp1.2' ];
var webSocket = connectWebsocket(wsUrl, subProtocols);

The format of the websocket URL and the returned WebSocket object is documented in the
HTML - Living Standard - Web sockets.

As per the RFC 6455, section 4.2.1, the subprocotol list should be ordered by the client's preference, starting from most preferred towards the least preferred protocol version. The typical implementations usually choose the first one they can understand from the list.


Last update: December 11, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.