Skip to content

MindSphere Gateway

Introduction

MindSphere Gateway acts as gateway to the MindSphere cloud 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 MindSphere 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

URL Schemes

In the following, the URL schemes of public URLs mapped to MindSphere Gateway are defined. Public URLs are callable from the internet. MindSphere 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 MindSphere Web Application

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

1
{tenant}-{webapp}[-{provider}].{region}[-{env}].mindsphere.io/[{path}]

Description

  • {tenant} 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. MindSphere 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.
  • [{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-fleetmanager.eu1.mindsphere.io: a user of tenant abc loads content from the MindSphere Fleet Manager web application in region eu1, production environment.
  • abc-fleetmanager-xyz.eu1.mindsphere.io/index.html: a user of tenant abc loads the index page from the Fleet Manager web application of provider xyz in region eu1, production environment.
  • xyz-fancyfleetmanager-xyz.eu1.mindsphere.io/images/icon.jpg: a user of tenant xyz loads an icon from the Fleet Manager web application of provider xyz in region eu1, production environment.

Web Application Client Call to MindSphere API

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

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

Description

  • {webAppHost} is according to the Call to MindSphere 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-fleetmanager.eu1.mindsphere.io/api/iot/v2/assets: a user of tenant abc uses the MindSphere Fleet Manager web application client in region eu1, to access the IoT core API v2, endpoint assets.
  • abc-fleetmanager.eu1.mindsphere.io/services/fleetmanager/v3/fleets: a user of tenant abc uses the MindSphere Fleet Manager web application client in region eu1, to access the fleetmanager UI mashup (core) API v3, endpoint fleets.
  • abc-fleetmanager-xyz.eu1.mindsphere.io/services/iot-xyz/v3/assets/46b55e6f: a user of tenant abc uses the xyz Fleet Manager web application client in region eu1, to access the xyz IoT Services v3, endpoint assets/46b55e6f.

Active Client Call to MindSphere 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.

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

Description

Examples

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

Device Agent Call to MindSphere agents or edge API

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

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

Description

Examples

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

Restrictions

The following restrictions are enforced when making requests to either your own registered applications or MindSphere APIs. These are only MindSphere Gateway limitations, individual limitations of MindSphere 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 MindpShere 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 MindSphere Gateway instance.
Cache invalidation timeout 15 minutes MindSphere 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 request.
Maximum header size 16 kB Maximum size of headers in a request.

Connection Idle Timeout

MindSphere 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, MindSphere Gateway closes the connection and the client needs to retry the request or reconnect to the WebSocket.

gateway

Security

Authorization

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

Cross-Site-Request-Forgery

MindSphere 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)

MindSphere 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.io).

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, MindSphere Gateway adds a CSP header for web applications:

1
Content-Security-Policy: default-src 'self' static.eu1.mindsphere.io; style-src * 'unsafe-inline'; script-src 'self' 'unsafe-inline' static.eu1.mindsphere.io; img-src * data:;

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

Cache Control

MindSphere 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.

The default value for Cache-Control header:

1
Cache-Control: no-cache, no-store, max-age=0, must-revalidate

In case when the no-cache option is used MindpShere Gateway will automatically add Pragma: no-cache and Expires: 0 headers.

WebSockets

The WebSocket communication protocol allows for full-duplex communication over a TCP connection. MindSphere 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. MindSphere 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 MindSphere 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.

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 MindSphere 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 MindSphere 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 don't 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.
MindSphere Gateway will keep the HTTP session alive internally, if there is traffic on the WebSocket connection.

Supported WebSocket Protocols

MindSphere Gateway does not restrict the protocols used on top of WebSockets. This allows applications to freely choose their "language", with the premise that both MindSphere Gateway and the application support the same protocol. MindSphere Gateway forwards every WebSocket message as binary, without interfering with the used protocol. For example, the following protocols are possible: 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 headers are necessary for an Upgrade request. The header names and values are case-insensitive.

header name header value
Cookie: SESSION=<session-id>; REGION-SESSION=<region-session-id>
Connection: Upgrade
Upgrade: WebSocket
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: <generated websocket key>
Sec-WebSocket-Extensions (optional): permessage-deflate; client_max_window_bits

Communication flow

  1. The web client performs a WebSocket protocol Upgrade HTTP request to an endpoint of the application registered at MindSphere Gateway.
  2. MindSphere Gateway evaluates the session headers and the called application endpoint.
  3. On successful validation, MindSphere Gateway responds with HTTP status code 101 and the necessary headers for a WebSocket Upgrade.
  4. After the connection is established, MindSphere Gateway creates a WebSocket web client connection to the targeted endpoint.
  5. MindSphere Gateway performs a new WebSocket protocol Upgrade HTTP request to the registered application backend.
  6. In case of success, client and backend are able to bidirectionally send messages over the proxied WebSocket.
  7. In case the connection of MindSphere Gateway to the application backend fails, MindSphere Gateway closes the WebSocket connection to the web client with status SERVER_ERROR (code: 1011). The current implementation does not allow to return information on a failed backend connection during the Upgrade request of the web client.

WebSocket Communication Example

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

gateway

Any questions left?

Ask the community


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