Using Policy Server with the eMessage Connector
 |
As of v.7.1.0, Axeda Policy Server is rebranded as ThingWorx Policy Server. The information here applies to Axeda Policy Server v.7.0.0 and to ThingWorx Policy Server v.7.1.0.. For simplicity, just "Policy Server" is used to refer to these two PTC products.
|
Your customers may require control over when you access their assets to perform routine maintenance or troubleshooting. Policy Server enables your customers to monitor requests for remote sessions from a service technician user of ThingWorx to the customer's Agents. When requests arrive, the customer administrator of Policy Server can approve or deny those requests.
Whenever a ThingWorx user sends a request for an action 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 requested action 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
In versions 1.4.0 and 2.2.0, the eMessage Connector was updated to support Policy Server messages, including SOAPStatus codes. In addition, the following changes were made to the entities provided in versions 1.3.0 and 2.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 requested again. 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 versions of the eMessage Connector and RAE that have these changes and also the version of ThingWorx Platform with which they are compatible:
eMessage Connector | Remote Access Extension | ThingWorx Platform |
|---|---|---|
v.1.3.0 | v.1.3.0 | v.8.5.x |
v.2.2.0 | v.2.3.0 | v.9.1.x and 9.0.x |
The Description Parameter for a Remote Session
When a remote session is started using the StartSession service, you can now add a description by adding it to the RemoteSessionParameters JSON field, called metadata. The eMessage Connector forwards the description to the agent when it tells the agent to start a remote session. This description shows up in Policy Server. Here is an example of the Pending Request in the Policy Server application, with the description highlighted:
SOAPStatus Codes for Policy Server Messages
To update the status field of the RemoteSession, the eMessage Connector processes the Policy Server SOAPStatus codes:
To support the Ask for Approval workflow of Policy Server, the status of the remote session is updated to AWAITING_AUTHORIZATION. The status is reported in the Remote Access Client (RAC).
The following values may be returned in the status for a remote session:
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 state 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. The RAC shows the Waiting for authorization 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 is offline and 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. |