Security for Remote Access
To run remote sessions with the 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 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.
 |
If your assets are running Axeda eMessage Agents (Axeda Gateway and Axeda Connector), the ThingWorx Connection Services Extension (CSE) must be imported first, followed by the ThingWorx Remote Access Extension (RAE), and finally the ThingWorx Axeda Compatibility Extension (ACE). Without all three extensions imported in this order, you will not have all the entities and services you need for assets running Axeda eMessage Agents.
|
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:
• 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.
Running Services to Grant Visibility and Permissions for Remote Access
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 WebSocket-based Edge MicroServer (WS EMS) , or a Lua Script Resource (LSR):
◦ RemoteAccessPermissionsServices.GrantPermissionsThingWorxInternalForThing
◦ RemoteAccessPermissionsServices.GrantPermissionsThingWorxInternalForTemplate
• eMessageServices Thing (ACE) for assets running Axeda Gateway Agents or Axeda Connector Agents:
◦ eMessageServices.GrantRemoteAccessPermissionsForThing.
◦ eMessageServices.GrantRemoteAccessPermissionsForTemplate.
When do you use the services provided by each of these Things? 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 WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR)
|
RAE
|
ThingworxInternalRemoteAccessProvider Thing (RAE).
|
RemoteAccessPermissionsServices 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 (ACE).
|
eMessageServices Thing (ACE)
|
|
|
* The RAE provides the basic entities for remote access that are implemented by Axeda entities. For this reason, you need both extensions for remote access functionality with Axeda Agents.
|
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 Thing 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 WebSocket-based Edge MicroServer (WS 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 AxedaRemoteAccessible 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