PSM Working Flow

Privileged Session Manager (PSM) streamlines the process of connecting to remote computers securely and efficiently. This article details the steps involved in connecting to a computer using PSM, including necessary configurations, user interactions, and the flow of information between EmpowerID and PSM.

Connecting with a Computer

Access Computers

To access computers, users navigate to the “Manage Access” tab on the Computers resource page of the IAM Shop. From there, they can remotely connect to computers to which they have access by doing the following:

Clicking Unlock (if they are in a new browser session).
Entering their Master Password.
Clicking the “Connect” button for a given computer to connect immediately.
Users can click the dropdown on the Connect button and select “Advanced Mode” to connect to a computer using shared or personal credentials. Note that if the Connect button is grayed out, users must connect using Advanced Mode.
After clicking “Connect,” users are redirected to the terms and conditions page, where they must agree to proceed to PSM.
Upon agreeing to the terms, users are directed to PSM via the path: https://FQDN_OF_YOUR_GATEWAY/start.

Parameters Provided to PSM

During the routing to PSM, EmpowerID provides the following parameters:

ComputerID: The unique identifier of the computer. Example: 2331
IsPersonalCred: A boolean value indicating whether the user is connected with personal credentials (true) or not (false).
ExternalCredentialCheckOutID: An ID assigned to the session by EmpowerID when the user checks out a computer.
LoginSessionID: Used to get user credentials from EmpowerID, such as username and password.
ApiUrl: The URL of EmpowerID. Example: https://api.empoweriam.com
Mode: The mode of remote connection, e.g., RDP, SSH, or Telnet.
ApiKey: Access token for EmpowerID.
CredentialID: Used to get credentials from EmpowerID.
ApiApplicationKey: Used to get credentials from EmpowerID.
GUAC_WIDTH: The computer's resolution width, e.g., 1920.
GUAC_HEIGHT: The computer's resolution height, e.g., 1208.
GUAC_DPI: Dots per inch on the screen, e.g., 192.

Height and width are dynamically adjusted based on the user's browser dimensions. If the user opens developer tools or minimizes the screen on the consent page, it may result in a smaller display, requiring the user to reconnect for an optimal fit.

Validation and Connection Flow

Before landing on the connection page, PSM performs the following validations:

Invalid Request Parameters: If ApiApplicationKey, LoginSessionID, or CredentialID lack valid UUIDs, PSM throws an error "Invalid request parameters."
Missing Request Parameters: If any of the payload parameters received from EmpowerID are null or undefined, PSM throws an error "Missing request parameters."

Master Password Page

If all parameters are present, EmpowerID directs users to the Master Password page, where they enter their unique master password.

Upon submitting the master password, PSM requests credentials from EmpowerID by hitting the endpoint /api/services/v1/secureaccessgateway/getcredential with the following payload:

computer: Computer ID received from EmpowerID
credential: Credential ID received from EmpowerID
password: Master password provided by the user
mode: Mode received from EmpowerID
session: PSM creates a new session UUID
loginsessionid: LoginSessionID received from EmpowerID

Request Failure Cases:

Invalid Master Password: If the user enters an invalid master password, EmpowerID throws a 401 error. PSM prompts the user to re-enter the correct password.
Access Token Expiry: If the access token expires, PSM closes the tab.
Other Errors: PSM redirects the user to an error page. If the user clicks "Close," the tab will be closed.

Response Received:

{
    "IsPasswordSSHKey": false,
    "UserName": "Prod\\ftariq",
    "Password": "Passw",
    "Notes": null,
    "Server": "EVM-Spare-01.thedotnetfactory.internal",
    "Server2": "192.168.75.92",
    "Server3": null,
    "GatewayServerDNSHostName": "lrdp.empoweriam.com",
    "ManagementPort": 3389,
    "AllowLiveSnooping": true,
    "AllowJoinRequests": false,
    "AllowJoinInvites": false,
    "RecordPSMSession": true
}

Mode-Specific Details

RDP: PSM provides a JSON object to the guacamole container to connect with the remote computer. If the access request policy recordings are set to true, it will also save the recordings locally.
SSH: In case of an SSH connection, PSM adds two new properties: typescript-path and typescript-name.
TELNET: In the case of a telnet connection, PSM adds typescript-path and typescript-name.

For a detailed explanation of the different connection types, please check the PSM Connection Types page.

Connection Object Encryption

After completing the above steps, PSM encrypts the connection object and passes it to the guacamole. The connection object looks like this:

{
    "connection": {
        "type": options.data.mode.toLowerCase(),
        "settings": {
            "hostname": con.server || con.server2 || con.server3,
            "username": con.userName,
            "domain": con.domain,
            "security": "any",
            "ignore-cert": true,
            "height": req.body.Height,
            "width": req.body.Width,
            "dpi": req.body.dpi,
            "create-recording-path": true,
            "recording-path": process.env.PSM_STORAGE_SHARE_LOCATION + '/' + session,
            "recording-name": '' + session + '.guac'
        },
        "api": {
            "Authorization": options.headers.Authorization,
            "ApiApplicationKey": options.headers["X-EmpowerID-API-Key"],
            "ApiUrl": options.data.apiurl,
            "ExternalCredentialCheckOutID": req.body.ExternalCredentialCheckOutID
        }
    }
}

Termination and Retry Mechanism

After closing the connection, an updateService function is called to notify EmpowerID that the specific connection is terminated. This function hits the following URL: https://YourEmpowerIDServer/api/services/v1/secureaccessgateway/endsession.

Error Handling:

If the API receives a 401 error, the authenticateToken() function is called to get a new access token, and the API is retried up to 7 times if it continues to fail.
For other errors, the process will also retry, ensuring robust error handling and retry mechanisms.