Watch and Terminate Sessions

Centrify provides the ability for administrators to monitor remote sessions in real time and to terminate them. Monitoring enables administrators to watch the actions performed by another user on a remote machine session that was launched from the tenant, in real time. If an administrator wants to prevent the user from performing additional actions, they can optionally terminate that remote session (e.g. if they don't agree with the actions being performed by the remote user).

Note: after terminating a session, an administrator may have to perform additional actions such as revoking access permissions on the remote user's account to prevent the user from logging back in again.

This document describes the API workflow to programmatically launch a monitoring window and to terminate a remote session.

Before continuing, ensure you are familiar with:

The remainder of this document assumes that you have already authenticated the user and have obtained the authentication token necessary to invoke subsequent endpoints.

Watching a Remote Session

Step 1. Getting Active Sessions

The first step is get a list of all sessions using the /ServerManage/GetSessions endpoint:

POST /ServerManage/GetSessions

{  
   "RRFormat":true,
   "Args":{  
      "PageNumber":1,
      "PageSize":100000,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

The Results array in the response contains information for each active session:

{  
   "success":true,
   "Result":{  
      "IsAggregate":false,
      "Count":1,
      "Columns":[  
         {  
            "Name":"SessionIdentity",
            "IsHidden":false,
            "DDName":null,
            "Title":"SessionIdentity",
            "DDTitle":null,
            "Description":null,
            "Type":12,
            "Format":null,
            "Width":73,
            "TableKey":null,
            "ForeignKey":null,
            "TableName":null
         },
         ...
      ],
      "FullCount":1,
      "Results":[  
         {  
            "Entities":[  
               {  
                  "Type":"Session",
                  "Key":"??",
                  "IsForeignKey":false
               }
            ],
            "Row":{  
               "SessionIdentity":"cccccddd-03f7-48cb-afa6-a4e70d6d8e75|56d08a79-cf60-4d95-beb5-f1aabe75da83",
               "User":"[email protected]",
               "LoggedUser":"administrator",
               "Host":"mycomputer.resource.centrify.com",
               "HostName":"mycomputer",
               "Started":"\/Date(1518807691453)\/",
               "SessionID":"cccccddd-03f7-48cb-afa6-a4e70d6d8e75|56d08a79-cf60-4d95-beb5-f1aabe75da83",
               "ProxyUUID":"cccccddd-03f7-48cb-afa6-a4e70d6d8e75",
               "Height":768,
               "SessionType":"Rdp",
               "ProxyIdentity":"cccccddd-03f7-48cb-afa6-a4e70d6d8e75|56d08a79-cf60-4d95-beb5-f1aabe75da83",
               "HostID":"72222222-e1ee-4c11-8aff-4d874aec7dcd",
               "AccountType":"Local",
               "ConnectionID":"abcdefgh-456e-42f1-a15d-9ea862c1aeb9",
               "JumpType":"Rdp",
               "ProxyVersion":"1",
               "Width":1024,
               "AccountID":"52152151-f504-46bf-b974-9eea4985759a"
            }
         }
      ],
      "ReturnID":""
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

The HostID field contains the ID of the remote system on which a session is taking place, the SessionIdentity identifies the session connection, the AccountID identifies the user who opened the session, and the ConnectionID identifies the connection. These parameters must be retained because they will be used for invoking subsequent endpoints throughout this API worflow. You can use the other fields (e.g. the HostName) to help determine the session from which you should pull these values from.

Step 2. Verifying Rights to Manage a Remote Session

The next step is to ensure that the user can manage a session for a remote system. Invoke the /ServerManage/GetComputerRights endpoint and pass the HostID returned from the previous endpoint via the ID field:

POST /ServerManage/GetComputerRights

{  
   "ID":"72222222-e1ee-4c11-8aff-4d874aec7dcd"
}

The Result lists the rights that the user has for administering the remote system. Ensure that ManageSession is listed as shown here:

{  
   "success":true,
   "Result":"ManageSession, Edit, Delete, Grant, AgentAuth, RequestZoneRole, View",
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Step 3. Open a Monitoring Window

After you have verified that the user has the ManageSession right, open a session window by invoking the /serversession/jumpterm endpoint and setting the mode parameter to 4. Combine the hostID and SessionIdentity returned from /ServerManage/GetSessions into one string separating the two values with a "|" character and pass them via the host query pararmeter:

GET /serversession/jumpterm?mode=4&sess=abcdefgh-456e-42f1-a15d-9ea862c1aeb9&height=768&width=1024&host=72222222-e1ee-4c11-8aff-4d874aec7dcd&prxid=c0c6ce4e-03f7-48cb-afa6-a4e70d6d8e75|cccccddd-cf60-4d95-beb5-f1aabe75da83&title=Watch%20session%20mycomputer

The response contains the HTML indicating how to render a monitoring window:

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/html; charset=utf-8
Vary: Accept-Encoding
X-CFY-TX-PN: Pod9
X-CFY-TX-ID: d62c3ac61596424b9cf68339d389868a
X-CFY-TX-DT: Mi8xNi8yMDE4IDc6MDI6MTEgUE0_
X-Frame-Options: SAMEORIGIN
P3P: CP="NON COR ADMa CURa DEVa OUR IND COM UNI NAV INT PRE LOC ONL PHY STA ONL"
X-CFY-TX-TM: 120
Set-Cookie: antixss=Q_K...Zw__-mFTOnOF_KLybgfN4oXQFxw__; path=/; secure
Set-Cookie: sessdata=L3dV...; expires=Sun, 18-Mar-2018 19:02:11 GMT; path=/; secure
X-Robots-Tag: noindex, nofollow
Date: Fri, 16 Feb 2018 19:02:11 GMT
Content-Length: 4072


<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=8,9,10" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <link rel="shortcut icon" />

        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_01.css?_ver=1518773059"/>
        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_02.css?_ver=1518773059"/>
        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_03.css?_ver=1518773059"/>

    <style>
        .x-viewport body {
            overflow: hidden !important;
            background-color: #000;
        }
    </style>
    <script src="/vfslow/lib/ui/jsutil/resources/locale/en.js?_ver=1518773059"></script>
            <script src="/vfslow/lib/ui/jsutil/resources/locale/en.js?_ver=1518773059"></script>
    <link href='/vfslow/lib/ui/../uibuild/compiled/jsutil/production/resources/fonts/Roboto.css?_ver=1518773059' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/fonts/Icon-Set.css?_ver=1518773059' rel='stylesheet' type='text/css'>
    <script type="text/javascript">
        var ServerConfig = {
            ResourceBase: "/vfslow/lib/ui/",
            ExtLocation: "/vfslow/lib/ui//ext/src",
            DisableCacheSetting: false,
            LoadBase: "/vfslow/lib/ui/",
            Version: "1518773059",
            AppBase:"1518773059",
            SkinDef:  {"themeColor":"#363a40","t ...},
            droppedPacketThreshold: 25,
            useFastForwardOnDrop: true,
            continueOnDropped: true,
            sendFailureCountLimit: 200,
            droppedPacketThresholdTime: 120,
            heartBeatTime: 5,
            challengeSessionId: "Zw_-OAzfh...",
            MissingBuildFilesFail: false,
            ManDef: {
                restUrl: ""
            }
        };

        window.Jsutil = window.Jsutil || {};
        //Do not show login automatically when we utilize jsutil.
        Jsutil.bypassLogin = true;
    </script>
    <script src="/vfslow/lib/ui/../uibuild/compiled/jsutil/production/app.js?_ver=1518773059"></script>
    <style type="text/css">
        html {
            height: 100%;
        }

        body {
            height: 100%;
            font-size: 12px;
            background: black;
        }

        .no-script-alert {
            background: #fff;
            text-align: left;
            padding: 10px 20px 10px 45px;
            border-top: 2px solid #ffd324;
            border-bottom: 2px solid #ffd324;
        }
    </style>
    <script type="text/javascript" src="/vfslow/lib/ui/terminals/rdp.js?_ver=1518773059"></script>
    </head>
    <body>
    <canvas id="rdpCanvas" />
    </body>
</html>

Step 4. Negotiate an SSH Session

Negotiate an SSH session terminal by invoking the /signalr/negotiate endpoint:

GET /signalr/negotiate?clientProtocol=1.5&connectionData=%5B%7B%22name%22%3A%22rdphub%22%7D%5D&_=1518807732656

The response contains information about the connection including a unique ConnectionToken for use in subsequent API calls:

{  
   "Url":"/signalr",
   "ConnectionToken":"KoBX...",
   "ConnectionId":"12233333-bb0e-4684-bb7c-22e536f8c9ff",
   "KeepAliveTimeout":20.0,
   "DisconnectTimeout":30.0,
   "ConnectionTimeout":110.0,
   "TryWebSockets":true,
   "ProtocolVersion":"1.5",
   "TransportConnectTimeout":5.0,
   "LongPollDelay":0.0
}

Step 5. Connect to the SSH Session

Connect to the remote SSH session by invoking the /signalr/connect endpoint and pass the token returned from the /signalr/negotiate endpoint via the ConnectionToken query parameter:

GET /signalr/connect?transport=webSockets&clientProtocol=1.5&connectionToken=KoBX...&connectionData=%5B%7B%22name%22%3A%22rdphub%22%7D%5D&tid=0

The response contains information about the connection including the number of bytes sent and received:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Server: Microsoft-IIS/10.0
X-Content-Type-Options: nosniff
Sec-WebSocket-Accept: WjgsoayLG4BsD2N/v/3yPJrTin8=
Connection: Upgrade
X-Robots-Tag: noindex, nofollow
Date: Fri, 16 Feb 2018 19:02:12 GMT
EndTime: 11:02:19.627
ReceivedBytes: 143459
SentBytes: 800

Step 6. Start the SSH Session

Start the SSH session by invoking the /signalr/start endpoint and pass the token returned from the /signalr/negotiate endpoint via the ConnectionToken query parameter:

GET /signalr/start?transport=webSockets&clientProtocol=1.5&connectionToken=KoBX...&connectionData=%5B%7B%22name%22%3A%22rdphub%22%7D%5D&_=1518807732657 HTTP/1.1

The response indicates that the session was started:

{  
   "Response":"started"
}

Step 7. (Optional) Close the Session Window

The session can be optionally closed programmatically by invoking the /signalr/abort endpoint, and passing the connection token via the connectionToken query parameter:

POST /signalr/abort?transport=webSockets&clientProtocol=1.5&connectionToken=KoBXnm...&connectionData=%5B%7B%22name%22%3A%22rdphub%22%7D%5D

The response contains information indicating if the request was successful:

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Expires: -1
Server: Microsoft-IIS/10.0
X-Content-Type-Options: nosniff
X-Robots-Tag: noindex, nofollow
Date: Fri, 16 Feb 2018 19:02:18 GMT
Content-Length: 0

Terminating a Remote Session

This section describes the API workflow for terminating a remote session.

Step 1. Verifying Rights to Delete a Remote Session

Ensure that the user can delete a session for a remote system. Invoke the /ServerManage/GetComputerRights endpoint and pass the HostID returned from the previous end point via the ID field:

POST /ServerManage/GetComputerRights

{  
   "ID":"72222222-e1ee-4c11-8aff-4d874aec7dcd"
}

The Result lists the rights that the user has for administering the remote system. Ensure that Delete is listed as shown here:

{  
   "success":true,
   "Result":"ManageSession, Edit, Delete, Grant, AgentAuth, RequestZoneRole, View",
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Step 2. Terminate the Session

Terminate the session by invoking the /ServerManage/TerminateSession endpoint. Pass the ID's for the connection, remote session user, session, and host that were returned from /ServerManage/GetSessions via the connectionID, accountID, sessionIdentity, and hostID parameters:

POST /ServerManage/TerminateSession

{  
   "connectionID":"abcdefgh-456e-42f1-a15d-9ea862c1aeb9",
   "accountID":"52152151-f504-46bf-b974-9eea4985759a",
   "sessionIdentity":"cccccddd-03f7-48cb-afa6-a4e70d6d8e75|56d08a79-cf60-4d95-beb5-f1aabe75da83",
   "hostID":"72222222-e1ee-4c11-8aff-4d874aec7dcd"
}

The success field in the response indicates if the request was successful:

{  
   "success":true,
   "Result":null,
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Upon successfully terminating the session, the remote user will see a message indicating that the session was terminated.

Step 3. (Optional) Getting Active Sessions

After terminating a session, you can optional call the /ServerManage/GetSessions endpoint to view the active remote sessions (e.g. to verify that the session was in fact terminated):

POST /ServerManage/GetSessions

{  
   "RRFormat":true,
   "Args":{  
      "PageNumber":1,
      "PageSize":100000,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

The response lists all active sessions. In the example, there are no active sessions:

{  
   "success":true,
   "Result":{  
      "IsAggregate":false,
      "Count":0,
      "Columns":[  

      ],
      "FullCount":0,
      "Results":[  

      ],
      "ReturnID":""
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Try the API in Postman:
.
Click here for help with using our sample Postman collection.