Using Axeda Policy Server with the eMessage Connector
Your customers may require control over when you access their assets to perform routine maintenance or troubleshooting via remote sessions. The PTC Axeda Policy Server enables your customers to monitor requests for remote sessions from ThingWorx Platform to the Agents and approve or deny those requests.
Whenever a ThingWorx user sends a request for a remote session to an asset that is running either an Axeda Gateway or Axeda Connector Agent, the Agent checks the policy file stored on the asset. If the policy for the remote session is to always ask for permission, the Agent sends a request to Policy Server for permission and notifies the platform via the eMessage Connector, that it is waiting for permission.
Policy Server Support
As of version 1.4.0 of the Axeda Compatibility Package, the eMessage Connector provides support for Policy Server messages related to requests for remote sessions, including SOAPStatus codes. In addition, the following changes were made to the entities provided in version 1.3.0 of the ThingWorx Remote Access Extension (RAE):
• A description parameter, called metadata, for remote session is available in the RemoteSessionParameters Data Shape.
• The RAClientLinker widget supports a SessionDescription property. When it calls the StartSession service, this widget adds the metadata field containing the key description and value of the SessionDescription property.
When an asset is configured in Policy Server with the “Start Remote Application” policy set to Ask for Approval, the eMessage Agent running on that asset forwards any remote session request and its parameters to Policy Server for approval. In addition, the Agent sends an ASKING message to the eMessage Connector. When it receives the request for permission, Policy Server sends an e-mail to the address specified for the policy and then stores the action request in the Pending Requests queue. The action request will remain shown in the Pending Request page until it is approved or denied, or until it times out. If timed out, the action is denied and needs to be re-requested. A message is logged in the audit log for Policy Server.
If approved or denied, the action request is removed from the Pending Requests page. A message regarding the approval or denial is written to the audit log. Policy Server sends its response (accept or deny) to the asset. The asset sends another status message (ASK_ACCEPTED or ASK_DENIED) to the eMessage Connector to identify whether the remote session request was approved or denied. If the request was approved, the Agent then processes the remote session.
The following table shows the first version of the eMessage Connector and RAE that have the changes for Policy Server and also the version of ThingWorx Platform with which it is compatible:
eMessage Connector | Remote Access Extension | ThingWorx Platform |
|---|---|---|
v.1.3.x | v.1.3.0 | v.8.5.x |
The Description Parameter for a Remote Session
If you specify a description for a remote session, that information is sent down in the remote session request to the asset. This description will show up in Policy Server and in the Remote Access Client (RAC).
In the Policy Server application, the Pending Requests page looks like this when a START REMOTE APPLICATION request is received:
To see the description of the session, click the chip containing the date. The Pending Request details appear in a popup. Here is an example, with the description from the metadata parameter shown in the field, Remote Session description:
The operator at the Policy Server console clicks either DENY or APPROVE for the request. The denial or approval is sent to the Agent and the Agent responds accordingly.
Remote session requests are also displayed in the Remote Sessions page of the Policy Server UI. In the following example, one request for a remote session was denied and another is pending approval:
In the screenshot above, THINGWORX is highlighted to show you that the ENTERPRISE ID sent to Policy Server for the ThingWorx Platform is hard-coded to THINGWORX for v.1.4.0.
SOAPStatus Codes for Policy Server Messages
The eMessage Connector has been updated to process the Axeda Policy Server SOAPStatus codes. The changes most noticeably affect the Connector's handling of remote sessions.
To support the ASKING status, the AWAITING_AUTHORIZATION RemoteSessionStatus was added to both the ThingWorx Remote Access Extension (RAE) and to the eMessage Connector. The following values may be returned in the RemoteSessionStatus:
Status | Description |
|---|---|
INITIALIZING | This status is set to this state when the session is first created/persisted. |
CREATED | The status is set to this state after the session has been created successfully on the remote access server (for example, GAS). |
AWAITING_AUTHORIZATION | The status is set to this sate if the Agent is waiting for an asset administrator to authorize the session from the Policy Server user interface. |
STARTED | The status is set to this state after the Agent has successfully received egress to start the session. |
CLOSE_REQUESTED | The status is set to this state when the maximum duration of a remote session (in hours) has been reached. |
TERMINATED | The status is set to this state when the remote session is closed. |
The following table lists and briefly describes the SOAPStatus codes that Axeda Agents can send on behalf of Policy Server to the eMessage Connector. How the Connector handles the message and, where applicable, the cause of terminating a remote session are also described.
 | If auditing is enabled on the ThingWorx Platform, the cause of terminating a remote session can be retrieved from the audit record. For more information, refer to Querying Audit History for Remote Access. |
Status (Code) | Description | Audited? | eMessage Connector Handling |
|---|---|---|---|
ASK_ACCEPTED(40000006) | The Agent requested permission from the Policy Server, and the customer accepted the request. The action is performed. | The eMessage Connector does nothing here because a SUCCESS (0) status code is sent along with this message. The Connector processes the SUCCESS code as usual and transitions the status of the remote session to STARTED by calling RemoteAccessSubsystem.UpdateSession. | |
ASK_DENIED(40000005) | The Agent requested permission from the Policy Server, but the customer denied the request. | Yes | Terminates the remote session by calling RemoteAccessSubsystem.UpdateSession with a termination cause of Permission Denied. An operator at the APS for the Agent denied permission for the requested action. |
ASKING(40000004) | The Agent has asked the Policy Server for permission to execute the requested action and is waiting for a response from the customer. The Agent sends this response within 300 ms. | Transitions the Remote Session status from CREATED to AWAITING_AUTHORIZATION by calling RemoteAccessSubsystem.UpdateSession. The RAC shows this message when a Remote Session has this status. | |
DENIED_APMOFFLINE(40000007) | Since the Policy Server is offline, the request is denied automatically when the policy for the requested action is ASK. The Agent does not perform the action. | Yes | Terminates the remote session by calling RemoteAccessSubsystem.UpdateSession with a termination cause of Permission Denied. If Policy Server is offline, the request is automatically denied. |
DENIED_TIMEOUT(40000002) | The request timed out and is denied. | Yes | Terminates the remote session by calling RemoteAccessSubsystem.UpdateSession with a termination cause of Permission Denied (Timed out). If APS does not respond within a configured time, the request is automatically denied. |
DENIED(40000001) | Per the policy configured for the asset, the request is denied. | Yes | Terminates the remote session by calling RemoteAccessSubsystem.UpdateSession with a termination cause of Permission Denied. This means that the action or command sent to the Agent was denied, based on the APS policy for the Agent. |
UNSUPPORTED(40000003) | Policy Server returned a message that no policy exists for this command. Therefore, the request is denied. | Yes | Terminates the remote session by calling RemoteAccessSubsystem.UpdateSession with a termination cause of Unsupported. The Agent has no policy for this command, so the request is automatically denied. |