Industrial IoT Gateway¶

Introduction¶

Industrial IoT Gateway serves as the interface that connects to the Insights Hub backend for web application clients, agents and edge applications, as well as external and internal app backends and services. Web applications or web services integrated with the Industrial IoT Gateway can be accessed from the internet through an external gateway. Each app or service provider must define the routing in the Gateway Registry. Identity management is integrated with the gateway to support web application OAuth 2.0 authorization code flows and exchange access tokens for interactive or active clients in cross-provider requests.

RFC compliance¶

RFC (Request for Comments) compliance refers to adherence to standards and protocols. This is crucial for defining the protocols, procedures and policies that govern internet and networking practices. For Insights Hub, compliance with these standards ensures compatibility and reliability across diverse platforms and technologies.

Standards¶

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

• RFC 7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
• RFC 7230 - Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing
• RFC 2818 - HTTP Over TLS
• RFC 2817 - Upgrading to TLS Within HTTP/1.1
• RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
• RFC 8615 - Well-Known Uniform Resource Identifiers (URIs)
• RFC 6455 - The WebSocket Protocol
• RFC 8307 - Well-Known URIs for the WebSocket Protocol

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 its own schema, which comes with a different set of reserved characters. Developers should consider this when encoding or decoding URLs. For further information, refer to Section 2 and Section 3 of RFC-3986.

URL Schemes¶

The following defines the URL schemes of public URLs mapped to the Industrial IoT Gateway. Public URLs are accessible from the internet and the Industrial IoT Gateway routes requests from public URLs to registered internal IPs, such as your internal Cloud Foundry app route.

• Curly brackets {}: These are used to define placeholders for mandatory URL parts.
• Square brackets [ ]: These are used to define placeholders required only in defined and 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 direct the user to the appropriate IdP(s) available for that tenant and also allows for the creation of 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 include it to prevent name collisions and maintain a clean core namespace.
• {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 to which the request is issued.
• [{path}] optional path parameters are used to reach sub-content of the web application. The first path parameter needs to be different from /api to avoid conflicts with API routing.

Web Application Client Call to API¶

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

{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 to simplify the URL. Non-core APIs need to append the provider name of the API to avoid name collisions and keep the core namespace clean.
• v{major} indicates the major version of the API.
• {endpoint} identifies an API endpoint and may include a nested path.

Active Client Call to API¶

Active clients are intended to run outside of a web browser. They do not require a tenant or web application identifier in their hostname. The target API is determined in the same way as for web application client calls.

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

Description¶

• {region}[-{env}] and {mindsphere-domain} are according to the Call to Web Application section.
• The path parameters are according to the Web Application Client Call to API section.

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¶

• {region}[-{env}] and {mindsphere-domain} are according to the Call to Web Application section.
• The path parameters are according to the Web Application Client Call to API section.

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: ?, *, **.

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.

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.

Large Request Restrictions¶

If the maximum request or file size is exceeded, typically when uploading files, the Industrial IoT Gateway responds with the 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 is closed.

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. To prevent this, endpoints are greylisted, temporarily blocking access to slow response endpoints if the load of an instance exceeds a certain limit.

When an endpoint is greylisted, requests receive a response with the HTTP status 503 Backend service is 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%.

Gateway Error Content Types¶

Gateway error responses are sent in either XML or JSON format. If a request receives these error responses, it must accept these media types in its Accept header. If the request does not specify these formats and an error occurs, the Industrial IoT Gateway will send an HTTP status 406 Not acceptable.
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 for applying authorization validations to ensure working access control.

Required claims¶

If authentication with a JWT access token is required, the "ten" claim becomes mandatory. In the internal API calls, the gateway uses this for routing. If the claim is missing or malformed, the gateway responds with the HTTP status 403 Forbidden. For more information on claims, refer to 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 the same origin check based on the origin http header.

Content-Security-Policies (CSP)¶

Industrial IoT Gateway enforces a strict Content Security Policy (CSP) header for web applications, which cannot be configurable by third parties. All served resources must be served from the application's URI or the static content URI (static.{region}[-{env}].{mindsphere-domain}).

A web application may employ 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:;

For more information about CSP, refer to the official specification from the W3C or the CSP documentation from MDN web documents.

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 a reflected cross-site scripting (XSS) attack. refer to 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 the following type:

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

This means you have to make sure that your application delivers the proper MIME type for the script and style files. Refer to 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 is configured during the application upload and 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 the 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 the HTTP/1.1 and higher protocols, these 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 the header X-Requested-With: XMLHttpRequest receive the 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 the web client and the server of a web application. 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 a proxy for WebSocket connections, similar to HTTP requests.

Configuring Applications for WebSocket Connections¶

To configure WebSockets, an application requires an endpoint registered with the Industrial IoT Gateway that supports HTTP GET requests and is capable of handling WebSocket connections. When the web client sends a WebSocket Upgrade request to this endpoint, the WebSocket connection is established.

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 it is available at the Industrial IoT Gateway for a tenant, myTenant, such 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 are based on the same mechanisms as for HTTP requests. Web sessions are used between the client and the Industrial IoT Gateway, while Bearer access tokens are used for internally forwarded requests. After establishing a WebSocket connection, the HTTP session and access token are no longer attached to 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 will not restrict the protocols used on top of WebSockets. This allows two applications (communicating through the 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¶

This section provides a comprehensive overview of how a WebSocket connection is established, maintained and terminated, as well as how data and security are managed throughout the lifecycle of the connection.

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, an empty string as a value is not permitted. In this case, the header name must not be present.

• * Possible values can be found on the following webpage: IANA WebSocket Protocol Registries.
• ** The Sec-WebSocket-Protocol header must be completely omitted if the client does not want to use any subprotocol, refer to the usage example.

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 requested 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 the event of success, the client and backend can bidirectionally send messages over the proxied WebSocket.
7. If the connection of the Industrial IoT Gateway to the application backend fails, the Industrial IoT Gateway closes the HTTP connection to the web client with a status of 400 Bad Request.

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

Effects of Autoscaling and Deployment¶

When a new version of the Industrial IoT Gateway is deployed, Websocket connections will be terminated after the blue or green switch. Additionally, autoscaling will shut down instances that have an open Websocket connection.

User applications should expect that the Websocket connection can be dropped at any time and should try to reconnect if this issue occurs.

Ping or Pong messages¶

Currently, no browser exposes the ping or 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. Another solution is for the server 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 are documented in the
HTML (Living Standard): Web sockets.

According to RFC 6455, section 4.2.1, the subprotocol list should be ordered by the client's preference, starting with the most preferred and ending with the least preferred protocol version. Typically, implementations select the first subprotocol they can understand from the list.

`

`

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