Connect using PSM

This method enables you to connect to an account through PSM (PSMConnect) using a connection method defined in the PVWA.

A response header defines which connection method is returned.

For more information, refer to Privileged Session Management Interface.

URL

  • Make sure there are no spaces in the URL.

  • The following characters are not supported in URL values: + & %

  • If the URL includes a dot (.), add a forward slash (/) at the end of the URL. For example: api/Safes/MySafe/Members/user@cyber.com/

 

 

https://<IIS_Server_Ip>/PasswordVault/API/Accounts/{accountId}/PSMConnect/

The following mandatory value is required in the URL:

Parameter

AccountID

Type

String

Description

The unique ID of the account to retrieve and use to connect to the target system through PSM.

Resource information

HTTP method

POST

Content type

application/json

Header parameter

Parameter

Description

Authorization

The token that identifies the session, encoded in BASE 64. See Authentication.

Type: String

Mandatory: Yes

Default value: None

 

Parameter

Accept

Type

String

Description

The table below describes the expected response format depending on the value of the Accept header in the request, per connection method configuration (RDP File or PSM Gateway).

 

PVWA configuration

Optional values

Connection method

RDP

  • application/json

  • application/octet-stream (default)

  • */ *

  • RDPFile (JSON)

  • RDPFile (octet-stream raw)

PSMGW

* / *

PSMGW (JSON)

 
  • Returns the HTML5 connection data.
  • PSMGW must be configured before using this REST API in order to receive a PSMGW response.

Body parameters

 
{

"reason":"<Reason>",

"TicketingSystemName":"<Ticketing system>",

"TicketId":"<Ticketid>",

"ConnectionComponent":"<Connection component id>",

"ConnectionParams": {

"<Connection parameter name>": {

"value":"<Connection parameter value>",

"ShouldSave":<true\false>

},

"<Connection parameter name>": {

"value":"<Connection parameter value>",

"ShouldSave":<true\false>

}

}

}

 

Parameter

ConnectionComponent (mandatory)

Type

String

Description

The name of the connection component to connect with as defined in the PVWA configuration

Parameter

Reason

Type

String

Description

The reason that is required to request access to this account.

Parameter

TicketingSystemName

Type

String

Description

The name of the Ticketing System used in the request.

Parameter

TicketId

Type

String

Description

The ticket ID of the ticketing system.

Parameter

ConnectionParams

Type

List

Description

A list of parameters required to perform the connection, as defined in each connection component configuration. These parameters are listed in the table below.

 

"ConnectionParams":{
    "AllowMappingLocalDrives":{"value":"No","ShouldSave":false},
    "AllowConnectToConsole":{"value":"No","ShouldSave":false},
    "RedirectSmartCards":{"value":"no","ShouldSave":false},
    "PSMRemoteMachine":{"value":"myremotemachine","ShouldSave":false},
    "LogonDomain":{"value":"1.1.1.1","ShouldSave":false},
    "AllowSelectHTML5":{"value":"No","ShouldSave":false}
    }

Connection Parameters

Parameter

value

Type

String

Description

The content of the parameter

Valid values

Text

Default

-

Parameter

ShouldSave

Type

Boolean

Description

Whether or not this value will be saved with the account for future attempts to connect to the remote machine.

Valid values

true/false

Default

false

Result

Response header

Parameter

ConnectionMethod

Type

Boolean

Description

The connection method defined in PVWA.

Values

  • PSMGW
  • RDPFile

Response body

There are two possible responses, depending on the connection method.

RDP file

 
full address:s:<address>

server port:i:<port>

username:s:<username>

alternate shell:s:<username>

desktopwidth:i:<number>

desktopheight:i:<number>

screen mode id:i:<number>

redirectdrives:i:<number>

drivestoredirect:s:<string>

redirectsmartcards:i:<number>

EnableCredSspSupport:i:<number>

redirectcomports:i:<number>

remoteapplicationmode:i:<number>

use multimon:i:<number>

span monitors:i:<number>

PSMGW

 
{

"PSMGWURL": "<URL>",

"PSMGWRequest": "<Base64 Encoded Data>"

}

 

Parameter

PSMGWURL

Type

String

Description

The full URL of the web server that serves the HTML5 service.

Parameter

PSMGWRequest

Type

String

Description

Base64 encoded data that is passed to the web server and is essential for the actual web server HTML5 connection. This data is passed through the web server HTTP Post request.

After receiving the PSMGW response, you can start a monitoring session via the PSM Gateway by sending a POST request to the URL specified in the response, in the PSMGWURL field.

Template:
 
{

"PSMGWRequest":"<Base64Response>"

}
 

The body of the POST request must contain the PSMGWRequest field obtained from the response.

Here is an example in two parts:

  1. After obtaining the following response from PSMConnect,
 
{
"PSMGWURL":"https://<PSM gateway FQDN>:8443/guac/direct", "PSMGWRequest":"eyJ1k2VybmFtZSI6IlBTTUkb...00tUkRQIn0=" }
  1. The following POST request to https://<PSM gateway FQDN>:8443/guac/direct can be used to connect to the PSM Gateway.
 
{

"PSMGWRequest":"eyJ1k2VybmFtZSI6IlBTTUkb...00tUkRQIn0=" }

Return codes

For a complete list of return codes, see Return Codes.