JSON-RPC Tunnel feature of the RM allows external applications to make remote JSON-RPC calls to the Gateway Software/OSGi devices via the RM server.

Conceptual Guide

JavaScript Object Notation – Remote Procedure Call or JSON-RPC defines a handful of data types and commands. The general mechanism consists of two peers establishing a data connection. During the lifetime of a connection, peers may invoke methods provided by the other peer.
The operation of the Remote JSON-RPC Provider is based on the distribution provider role from the OSGi Remote Service Specification. It exports functionality from the OSGi environment by mapping JSON-RPC method calls to services.
JSON requests to the devices are made via the RM alias /remote/json-rpc. This alias may be reconfigured using the system property

The target OSGi device, which a given JSON-RPC request should be forwarded to is determined by the value of a predefined HTTP header.
The following system property should be set in case the default system header is changed:

where the <HTTP_HEADER_NAME> is the name of the http header, containing the device ID. The default value of the property is "GATEWAY-ID". Failing to supply this header to a request will result in errors, unless com.prosyst.mprm.net.tunnel.resolution.DeviceIdResolver is provided (For more information refer to: JSON-RPC Tunnel)
A device running the Bosch Digital OSGi runtime connects to a configured RM server and maintains a persistent messaging connection. The JSON-RPC Tunnel functionality allows applications to use the publicly available RM server to access the JSON-RPC API of the connected OSGi/Gateway Software devices from Internet. All JSON-RPC requests to the /remote/json-rpc (or whatever is configured via the system property) on the RM are redirected to the appropriate end device over the persistent messaging connection and the result of the JSON-RPC call is returned back to the application via the RM. The content of the requests and responses are unmodified, so both the OSGi device and the remote application communicate transparently.

Authorization

By default no authentication or authorization is required (it is turned off). As an authentication option RM provides а possibility for HTTP Basic User Authentication. The JSON-RPC tunnel basic access authentication can be switched on/off via the JSON-RPC Tunnel Configuration:

If this configuration option is turned on, then the Authorization request header becomes mandatory, and access control is being checked. Example:

Where dGVzdDp0ZXN0 is the Base64-encoded value of the string "test:test", which corresponds to user account "test" with password "test"
When the user is authenticated, an extra authorization check is performed: the user is checked for possession of a parametric role Device-Tunnel-Caller(<Device-Path>), parametrized by the path of the device that he is trying to perform the request on. Then the call is either being performed, or declared unauthorized, based on the presence of the role.

OSGi Device Provisioning

There are two ways to enable the JSON-RPC Tunnel on OSGi devices:

• Through enabling the JSON-RPC Agent optional feature in the provisioning.prs file of the OSGi device
• By installing the mprm.osgidm.jsonrpc_http_agent bundle from the RM Software Repository on the OSGi device.