{"id":24761802,"url":"https://github.com/cumulocity-iot/cumulocity-remote-access-cloud-http-proxy","last_synced_at":"2026-02-27T12:41:00.788Z","repository":{"id":219496608,"uuid":"749162624","full_name":"Cumulocity-IoT/cumulocity-remote-access-cloud-http-proxy","owner":"Cumulocity-IoT","description":"A Cumulocity IoT microservice that allows to proxy HTTP requests through the cloud to an HTTP server running on a Cumulocity IoT connected device.","archived":false,"fork":false,"pushed_at":"2026-02-05T15:20:45.000Z","size":4163,"stargazers_count":5,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T23:59:34.000Z","etag":null,"topics":["c8y","cumulocity","cumulocity-extension","cumulocity-iot","cumulocity-package","cumulocity-webapp","extension","iot-analytics","microservice","webapp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cumulocity-IoT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-27T19:02:15.000Z","updated_at":"2026-02-05T15:31:12.000Z","dependencies_parsed_at":"2024-02-22T22:29:53.448Z","dependency_job_id":"411381ff-ee0b-44be-98c6-0dcd1229fd50","html_url":"https://github.com/Cumulocity-IoT/cumulocity-remote-access-cloud-http-proxy","commit_stats":null,"previous_names":["softwareag/cumulocity-remote-access-cloud-http-proxy","cumulocity-iot/cumulocity-remote-access-cloud-http-proxy"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/Cumulocity-IoT/cumulocity-remote-access-cloud-http-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-remote-access-cloud-http-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-remote-access-cloud-http-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-remote-access-cloud-http-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-remote-access-cloud-http-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cumulocity-IoT","download_url":"https://codeload.github.com/Cumulocity-IoT/cumulocity-remote-access-cloud-http-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cumulocity-IoT%2Fcumulocity-remote-access-cloud-http-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29895348,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T12:09:13.686Z","status":"ssl_error","status_checked_at":"2026-02-27T12:09:13.282Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c8y","cumulocity","cumulocity-extension","cumulocity-iot","cumulocity-package","cumulocity-webapp","extension","iot-analytics","microservice","webapp"],"created_at":"2025-01-28T19:19:33.199Z","updated_at":"2026-02-27T12:41:00.779Z","avatar_url":"https://github.com/Cumulocity-IoT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Remote access cloud HTTP proxy\n\nA Cumulocity IoT microservice that allows to proxy HTTP requests through the cloud to a (local) HTTP server running on a Cumulocity IoT connected device or in the accessible network of the device.\nThis project contains a backend microservice and a UI plugin. Both must be installed to your tenant in order to use this functionality.\n\nA sample usecase might be to access a configuration UI on your device or to e.g. access an instance of [Node-RED](https://nodered.org/) running on your device:\n![Demo Node-Red](images/demo-node-red.png)\n\n## Prerequisits \u0026 Limitations\n\nThis functionality is heavily relying on the [Cloud Remote Access feature of Cumulocity](https://cumulocity.com/docs/cloud-remote-access/cra-general-aspects/).\n\n- The shell application that you are installing the UI plugin to should use at least version 1017+ of the Web SDK.\n\n- **PASSTHROUGH endpoint:** To use the proxy you need a remote access `PASSTHROUGH` endpoint configured on each of your devices you want to connect to. See [this guide](https://tech.forums.softwareag.com/t/how-to-get-started-with-cloud-remote-access-for-cumulocity-iot/258446#step-by-step-guide-to-setup-a-passthrough-connection-16) for further details.\n\n- **Tenant Authentication Method:** The desired tenant must be configured to use the [`OAI Secure` Authentication](https://cumulocity.com/docs/authentication/basic-settings/#login-settings)\n\n- **Disable XSRF-Token validation**: The XSRF-Token validation of Cumulocity needs to be disabled for the tenant. Please check on your own if this might be a security concern for you: [Cross-site request forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery). To do this, the corresponding tenant option (category: `jwt`, key: `xsrf-validation.enabled`) must be set to `false`. The microservice will take care of disabling this on subscribed tenants automatically.\n\n- Requests through the proxy can be made via both HTTP and HTTPS. For requests made to an HTTPS server, the certificate of the server is not actually validated.\n\n- The web server you are trying to access must be compatible with being served behind a reverse proxy with another path (which is in this case: `/service/cloud-http-proxy/\u003cdeviceId\u003e/\u003cremoteAccessConnectConfigId\u003e/`). This might be something you can configure as part of your application, but not all applications support this.\n\nIn case you are reaching the limits of this tool, you can also give [remote-access-local-proxy](https://github.com/Cumulocity-IoT/cumulocity-remote-access-local-proxy) a try. This requires an application be to executed locally, but is not limited to just the HTTP protocol.\n\n## Microservice\n\nThe microservice is written in nodeJS.\n\nIt's functionality can be described in the following steps:\n\n1. Accept incoming requests on path: `/service/cloud-http-proxy/\u003cdeviceId\u003e/\u003cremoteAccessConnectConfigId\u003e/**/*` and `/service/cloud-http-proxy/s/\u003cdeviceId\u003e/\u003cremoteAccessConnectConfigId\u003e/**/*` (in case of HTTPS)\n2. The authentication details and the connection details included in the path are taken from the incoming request.\n3. The authentication information is used to create a new remote access connect session. The device ID and remote access connect configuration Id is also required to establish this connection.\n4. After the remote access connect Websocket connection was established successfully, it will send the HTTP request through the Websocket connection to the web server running on the device. The corresponding response is also forwarded.\n\n## UI Plugin\n\nThe UI plugin adds tabs on device level to the application it has been installed to.\nThe UI detects remote access connections available for the device that have been prefixed with `http:` and use the `PASSTHROUGH` protocol.\n\nFor instructions on how to install an UI plugin, please check [here](https://cumulocity.com/docs/standard-tenant/ecosystem/#extensions).\n\n### Configuring a new connection\n\nA new connection can be configured on devices supporting the remote access connect feature.\nThe default UI of the remote access connect feature can be used for that.\n\nThe name of the configuration should be prefixed with either `http:` or `https:` depending on the server you are trying to connect to. This is used by the UI Plugin to identify endpoints that are compatible with it.\n\nThe protocol should be set to `PASSTHROUGH`. In case this is not available, please contact your platform administrator to make it available.\n\nYou can then just enter the host and port that you would like to connect to with this configuration.\nBelow you can find a sample configuration for Node-RED.\n![Configure Node-RED](images/configuring-node-red.png)\n\nOnce you saved the new connection, an new tab will show up on the device.\nIt might be required to reload the page once for the tab to show up.\n\nIn case the tab does not show up, check the browsers console logs. In case you've missed to set a tenant option, you should see a warning there.\n\nIn case the http server you are trying to access needs some sort auf authorization, you can set an `authorization` header via the UI, which will be attached by the proxy microservice to all request.\n\nIn case you want to set some other header as well, you can do so by setting a tenant option per header:\n\n- Category should be `cloud-http-proxy`\n- Key should follow this syntax: `credentials.rca-http-header-\u003cheaderKey\u003e-\u003cdeviceId\u003e-\u003cconnectionId\u003e`\n- Value: the header value to be set\n\n  ```\n  c8y tenantoptions update --category cloud-http-proxy --key credentials.rca-http-header-\u003cheaderKey\u003e-\u003cdeviceId\u003e-\u003cconnectionId\u003e --value \u003cheaderValue\u003e\n  ```\n\n## How to demo this\n\n1. Setup a device with an agent that supports remote access connect, e.g. [thin-edge.io](https://thin-edge.github.io/thin-edge.io/install/)\n2. Install e.g. Node-RED via [their install script](https://github.com/node-red/linux-installers/#debian-ubuntu-raspberry-pi-os)\n3. Create an remote access endpoint like described above.\n4. Reload the page once and you should see a new tab on device level with the name that you have used for the connection.\n\n## Ideas for future improvements:\n\n- ~~**Connection Pools:** As of now a remote access connect session is used per request. This does mean that per HTTP request sent, an operation for the device is created to establish the remote access connect session. This adds a certain delay to every request and creates a bunch of operations in Cumulocity. This could be improved by having a connection pool per device, to reuse remote access connect sessions.~~ **`implemented`**\n\n- ~~**Authorization:** Currently any sort of authorization to the target HTTP server is not supported since the `Authorization` headers would be interpreted by Cumulocity and the access would be probably denied (as the user you are using against the device is probably not existing inside of Cumulocity). In theory an authorization header could be added to the requests as part of the http proxy that is running inside of the microservice.~~ **`implemented`**\n\n------------------------------\n\nThese tools are provided as-is and without warranty or support. They do not constitute part of the Cumulocity product suite. Users are free to use, fork and modify them, subject to the license agreement. While Cumulocity welcomes contributions, we cannot guarantee to include every contribution in the master project.\n_____________________\nFor more information you can Ask a Question in the [community Forums](https://community.cumulocity.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fcumulocity-remote-access-cloud-http-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcumulocity-iot%2Fcumulocity-remote-access-cloud-http-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcumulocity-iot%2Fcumulocity-remote-access-cloud-http-proxy/lists"}