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.
Updated almost 5 years ago