Managing Security for Remote Access
To run remote sessions with the ThingWorx Edge agent devices for which they are responsible, end users need permissions and visibility to execute the remote access services available on their Things that have the RemoteAccessible Thing Shape. For Axeda eMessage agent devices used with Axeda GAS v.6.9.2/v.6.9.3 or ThingWorx GAS v.7.0.x, the Axeda Things must have the GASRemoteAccessible Thing Shape assigned to them. If eMessage agent devices are used with ThingWorx GAS v.7.1.0 and you want the remote sessions to be offloaded from ThingWorx Platform and the eMessage Connector, the Things must have the RemoteAccessible Thing Shape assigned to them.
The system administrator is responsible for setting up the security entities that require permissions and visibility, such as non-admin users, user groups, and organizations. Administrators are also responsible for executing the services that grant permissions and visibility for remote access.
The ThingWorx Remote Access Extension v.3.0.0 provides the RemoteAccessible and GASRemoteAccessible Thing Shapes as well as the RemoteAccessPermissionServices Thing, from which you can run the services to set up security for remote access.
 |
If your assets are running Axeda eMessage Agents (Axeda Gateway and Axeda Connector), refer to Security for Remote Sessions in the Axeda Compatibility Package Help Center.
|
Creating Security Entities
To set up security for remote access, you need to create at least one each of these entities:
• A non-administrative ThingWorx user. For example, raUser.
• A ThingWorx user group. For example, raUserGroup. Add the non-admin user to this group.
• A ThingWorx organization. For example, raOrg. Add the raUserGroup to this organization.
For details about users, user groups, organizations, as well as visibility and permissions to Things and Thing Templates for these entities, see these topics in the ThingWorx Platform Help Center:
• Users
Once you have created the security entities, you can run services to grant permissions and visibility to the users for remote access to Things and Things derived from a specified Thing Template. When running the services, you will need the names of the user groups and organization that you have created.
Permissions and Visibility Granting Services in RAE v.3.0.0
The RemoteAccessPermissionServices Thing provides the following services, which are called by other permissions services.
Service Name | Description |
|---|---|
GrantPermissions | Grants common remote access permissions. This service takes the following parameters: organization, templateName (name of a Thing Template), thingName, and userGroup. |
GrantPermissionsThingworxInternal GrantPermissionsThingworxInternalForThing GrantPermissionsThingworxInternalForTemplate | Grant remote access permissions for assets running an Edge application written using a ThingWorx Edge SDK, a ThingWorx WebSocket-based Edge MicroServer (WS EMS), or a Lua Script Resource (LSR). Use the GrantPermissionsThingWorxInternalForThing or GrantPermissionsThingWorxInternalForTemplate methods as appropriate for the desired entity type. These services both take the organization and userGroup parameters . The and . The GrantPermissionsThingWorxInternalForTemplate service also takes the templateName parameter (name of a Thing Template), while the GrantPermissionsThingWorxInternalForThing service takes the thingName parameter. |
GrantGlobalAccessServerPermissions | Grants permissions required for running a Global Access Server. This service takes the following parameters: organization and userGroup. |
GrantRemoteAccessPermissionsGAS GrantRemoteAccessPermissionsGASForThing GrantRemoteAccessPermissionsGASForTemplate | Grants remote access permissions for assets using remote sessions managed by a Global Access Server. Use the GrantRemoteAccessPermissionsGASForThing or GrantRemoteAccessPermissionsGASForTemplate methods as appropriate for the desired entity type. Each service also takes the parameter for the corresponding entity type, thingName or templateName (name of Thing Template). |
Running Services to Grant Visibility and Permissions for Remote Access Using RAE Versions Prior to v.3.0.0
The ThingWorx Remote Access Extension (RAE) and ThingWorx Axeda Compatibility Extension (ACE) provide services that automate the setting of permissions and visibility for remote access. The following Things provide these services:
• ThingworxInternalRemoteAccessProvider Thing (RAE) for assets running an Edge application written using a ThingWorx Edge SDK , a ThingWorx Edge MicroServer (EMS), or a Lua Script Resource (LSR):
◦ RemoteAccessPermissionServices.GrantPermissionsThingWorxInternalForThing
◦ RemoteAccessPermissionServices.GrantPermissionsThingWorxInternalForTemplate
• eMessageServices Thing (ACE) for assets running Axeda Gateway Agents or Axeda Connector Agents:
◦ eMessageServices.GrantRemoteAccessPermissionsGASForThing
◦ eMessageServices.GrantRemoteAccessPermissionsGASForTemplate
How to Choose the Permissions and Visibility Granting Services to Use
Which services provided by the RemoteAccessPermissionServices Thing and the eMessageServices Thing should you use? It depends on the agent running on your edge devices. The following table maps the types of agents to their RemoteAccessProvider Things and shows the name of the Thing from which to run services to grant remote access permissions and visibility to an organization and/or user group. The table also shows which extension provides the necessary Things.
Agent Type | Extension(s) Required | Remote Access Provider | Services Thing (Extension) |
|---|---|---|---|
ThingWorx Edge MicroServer (EMS) and Lua Script Resource (LSR) | RAE | ThingworxInternalRemoteAccessProvider Thing (RAE) | RemoteAccessPermissionServices Thing (RAE) |
Axeda eMessage Agents (Axeda Gateway and Axeda Connector) | RAE and ACE* | Axeda Global Access Server (GAS), represented in ThingWorx by the GASRemoteAccessProvider Thing (RAE). | eMessageServices Thing (ACE) |
Running the Services
In general, navigate to the Thing that provides the permissions-granting services for remote access, and then run either or both of the services to grant visibility and permissions for an organization and user group. To grant visibility and permissions to a single Thing, use the service, GrantRemoteAccessPermissionsForThing. To grant visibility and permissions to a set of Things, namely all Things of the same Thing Template, use the GrantRemoteAccessPermissionsForTemplate service. In either case, you MUST set the following parameters for the service:
• organization — Specify the name of the organization that should be granted visibility and permissions to start, end, and get remote sessions on the specified Thing or Things derived from the specified Thing Template. The ThingWorx base type of this parameter is STRING.
• userGroup — Specify the name of the user group that should be granted visibility and permissions to start, end, and get remote sessions on the specified Thing or Things derived from the specified Thing Template. The ThingWorx base type of this parameter is GROUPNAME.
• Specify the name of the entity for which remote access permissions and visibility should be granted to the specified organization and user group:
◦ thingName — For the service that grants remote access permissions to a Thing, specify the name of the Thing in ThingWorx. The base type for this parameter is THINGNAME.
◦ templateName — For the service that grants remote access permissions to a Thing Template, specify the name of the Thing Template. The base type for this parameter is THINGTEMPLATENAME.
IMPORTANT! The Thing or Thing Template specified for the service must implement the RemoteAccessible or the GASRemoteAccessibleThing Shape. The table below maps agents to Thing Templates. If you have created custom Thing Templates, you can also specify those Thing Templates. Make sure, however, that the Thing Templates implement the RemoteAccessible Thing Shape.
Agent Type | Thing Templates |
|---|---|
ThingWorx Edge MicroServer (EMS) and Lua Script Resource (LSR) | RemoteThingWithTunnels, RemoteThingWithTunnelsAndFileTransfer, or a custom Thing Template that implements either of these Thing Templates AND implements the RemoteAccessible Thing Shape. |
Edge application written using the ThingWorx Edge C SDK, ThingWorx Edge Java SDK, or ThingWorx Edge .NET SDK | RemoteThingWithTunnels, RemoteThingWithTunnelsAndFileTransfer, or a custom Thing Template that implements either of these Thing Templates AND implements the RemoteAccessible Thing Shape. |
Axeda eMessage Agents | AxedaEMessageGatewayModel, AxedaManagedModel, AxedaStandaloneModel, or a custom Thing Template that implements one of these Thing Templates. All of these Thing Templates implement the GASRemoteAccessible Thing Shape. |
Security for the ThingWorx Remote Access Client (RAC)
The Remote Access Client can be launched from a mashup that provides a user interface for managing and creating remote sessions. As of v.1.1.0 of the RAC and v.1.2.0 of the RAE, a temporary application key, called a nonce key, is generated by the ThingWorx Platform for the user initiating the remote session. Once that key is created, a URI is constructed that includes the nonce key, the platform's public host and port, and the session ID of the newly created remote session. This URI is used to launch the Remote Access Client. The nonce key in the URI is used to establish connectivity from the Remote Access Client to the platform. As soon as possible after the nonce key is either used or expires, it is removed from the platform.
Platform User Permissions
The Remote Access Client connects to the ThingWorx Platform using a nonce key associated to the user initiating the session. The user, through the Remote Access Client, has the minimum set of security requirements necessary for the client to start a session with the remote device:
• READ on the RemoteAccessible Thing
• PROPERTY READ on the RemoteAccessible Thing
• SERVICE INVOKE on the session service(s) such as StartSession on the RemoteAccessible Thing