Connecting to Computers via OpenPSM

Owned by Phillip Hanegan
Last updated: Dec 04, 2024
7 min read

OpenPSM (Open Privileged Session Management) integrates with the IAM Shop to enable administrators and authorized users to initiate secure, audited sessions to managed computers. The integration ensures adherence to predefined access request policies and supports features like Just-In-Time (JIT) account provisioning, multi-factor authentication (MFA), and access level assignments.

Accessing Computers via the IAM Shop

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:

  1. Click the Unlock button (if they are in a new browser session).

    image-20240723-183316.png

  2. Enter their Master Password.

    image-20240723-183515.png

  3. Click the Connect button next to the desired computer to connect immediately.

Advanced Mode:

  • If the Connect button is grayed out or you require specific credential options, click the dropdown arrow and select Advanced Mode.

  • Note: Advanced Mode allows you to select between shared or personal credentials

  1. Agree to Terms and Conditions:

  2. After clicking “Connect,” users are redirected to the terms and conditions page, where they must agree to proceed to PSM.

     

  3. Upon agreeing to the terms, users are directed to PSM via the path: https://FQDN_OF_YOUR_GATEWAY/start.

     

Connection Parameters

When initiating a connection via OpenPSM from IAM Shop, several parameters are provided to ensure the session is correctly associated with the target user, computer, and access policies.

Required Parameters

  • TargetPersonGuid

    • Type: GUID

    • Description: The unique identifier of the person initiating the connection.

  • AccessRequestPolicyID

    • Type: GUID

    • Description: The unique identifier of the access request policy applicable to the computer.

  • TargetComputerGuid

    • Type: GUID

    • Description: The unique identifier of the target computer.

  • IsAdvanceMode

    • Type: Boolean

    • Description: Indicates whether to use advanced connection settings.

Optional Parameters

  • CheckOutStartDate

    • Type: DateTime

    • Description: The start date and time for the access period.

  • CheckOutEndDate

    • Type: DateTime

    • Description: The end date and time for the access period.

  • ExternalCredentialGuid

    • Type: GUID

    • Description: The unique identifier of an external credential (if personal credentials are used).

  • PSM_Connection_Delay

    • Type: Integer (seconds)

    • Description: The delay after account creation on JIT-enabled computers before prompting for the master password.

Additional Parameters Passed to PSM

During the routing to PSM, the following parameters are provided:

  • ComputerID: The unique identifier of the computer (e.g., 2331).

  • IsPersonalCred: Indicates whether personal credentials are used (true or false).

  • ExternalCredentialCheckOutID: The session ID assigned when the user checks out a computer.

  • LoginSessionID: Used to retrieve user credentials from EmpowerID.

  • ApiUrl: The URL of EmpowerID's API (e.g., https://api.empoweriam.com).

  • Mode: The mode of remote connection (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, GUAC_HEIGHT, GUAC_DPI: Parameters for screen resolution and display settings.

Workflow Steps

The connection process involves several orchestrated steps within the OpenPSM workflow. Below is an overview of each step and its purpose.

1. Initialize Workflow

Purpose: Set up initial parameters and validate inputs.

  • Actions:

    • Assign TargetPerson, AccessRequestPolicy, and TargetComputer using their GUIDs.

    • Configure consent text for session recording agreements.

    • Validate all required parameters.

    • If validation fails, display "Invalid Request parameters."

2. Check for Available Credentials

Purpose: Determine if shared or personal credentials are available for the connection.

  • Actions:

    • Retrieve existing checked-out credentials for the user and computer.

    • If no external credential is provided and shared credentials are required:

      • Attempt to find an available shared credential.

      • If none are available, prompt the user to select a personal credential.

      • If no credentials are available, display "No shared or personal credentials are available."

    • If an existing credential is checked out, use it for the session.

3. Select Personal Credential

Purpose: Allow the user to choose a personal credential if necessary.

  • Actions:

    • Display a list of the user's personal credentials.

    • User selects a credential for the session.

4. Consent for Session Recording

Purpose: Obtain user consent if session recording is required.

  • Actions:

    • Prompt the user with the consent text.

    • If the user agrees, proceed.

    • If the user declines, end the workflow.

5. Set Session Parameters

Purpose: Configure OAuth settings, time constraints, and validate credentials.

  • Actions:

    • Retrieve OAuth application settings.

    • Validate the access request policy and computer details.

    • Determine access time window using provided dates or policy defaults.

    • Validate external credentials and ownership.

    • Handle JIT account provisioning if applicable.

6. Select Connection Mode

Purpose: Allow the user to choose the connection mode (e.g., RDP, SSH).

  • Actions:

    • Display available connection modes.

    • User selects a preferred mode.

7. Perform MFA Authentication

Purpose: Ensure MFA requirements are met before session initiation.

  • Actions:

    • Check if the session includes required MFA points.

    • Prompt the user to complete MFA steps if necessary.

8. Set Access Levels

Purpose: Enable users to select access levels if permitted.

  • Actions:

    • Retrieve available access levels where the user is pre-approved.

    • Filter access levels based on account stores and groups.

    • User selects desired access levels for the session.

9. Checkout Credential and Get Token

Purpose: Manage credential checkout and prepare the session token.

  • Actions:

    • Checkout the selected credential.

    • Handle JIT account creation and group assignments.

    • Validate successful credential checkout.

    • Prepare the session token for authentication.

10. Initiate OpenPSM Session

Purpose: Finalize the connection and start the privileged session.

  • Actions:

    • Set session parameters, including credential IDs and URLs.

    • Handle any errors and set failure messages if necessary.

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 GUIDs, PSM displays an error: "Invalid request parameters."

  • Missing Request Parameters:

    • If any of the payload parameters received from EmpowerID are null or undefined, PSM displays an error: "Missing request parameters."

Master Password Prompt

If all parameters are present, users are directed to the Master Password page.

  • Action:

    • Enter your unique master password.

    • Purpose: Authenticates the user and decrypts stored credentials.

Requesting Credentials from EmpowerID

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

  • Parameters:

    • computer: Computer ID

    • credential: Credential ID

    • password: Master password

    • mode: Connection mode (RDP, SSH, Telnet)

    • session: Newly generated session UUID

    • loginsessionid: LoginSessionID

Handling Response and Errors

  • Invalid Master Password:

    • If the master password is incorrect, EmpowerID returns a 401 error.

    • Action: PSM prompts the user to re-enter the correct password.

  • Access Token Expiry:

    • PSM closes the tab if the access token has expired and requires the user to restart the process.

  • Other Errors:

    • PSM redirects the user to an error page.

    • Action: The user can click "Close" to exit.

Response Received from EmpowerID

An example of a successful response:

{ "IsPasswordSSHKey": false, "UserName": "Domain\\username", "Password": "DecryptedPassword", "Notes": null, "Server": "ServerName.domain.com", "Server2": "192.168.X.X", "Server3": null, "GatewayServerDNSHostName": "gateway.domain.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 session recording is enabled, recordings are saved locally.

  • SSH and Telnet:

    • PSM adds properties such as typescript-path and typescript-name for session recording.

Connection Object Encryption

After preparing the connection details, PSM encrypts the connection object and passes it to Guacamole. The connection object includes:

  • Connection Settings:

    • Type (mode)

    • Hostname

    • Username

    • Domain

    • Security settings

    • Display settings (height, width, DPI)

    • Recording settings

  • API Credentials:

    • Authorization tokens

    • API URLs

    • Session IDs

Termination and Retry Mechanism

  • Session Termination:

    • Upon closing the connection, PSM notifies EmpowerID that the session has ended by calling /api/services/v1/secureaccessgateway/endsession.

  • Error Handling:

    • If a 401 error occurs, PSM attempts to re-authenticate and retries the API call up to 7 times.

    • For other errors, PSM implements retry logic to ensure proper session termination.

Configuration Guidelines

Just-In-Time (JIT) Account Provisioning

  • Setup:

    • Ensure the computer is configured for JIT provisioning.

    • Define account stores and groups for temporary accounts.

  • Behavior:

    • If no external credential is provided, a temporary account is created.

    • The account is added to the appropriate groups based on access levels.

    • Time constraints are applied as per policy or provided dates.

Multi-Factor Authentication (MFA)

  • Requirements:

    • MFA settings are defined in the access request policy.

    • Users must complete MFA steps before session initiation.

  • Configuration:

    • Define MFA points required for different network locations.

    • Ensure users have the necessary MFA methods enrolled.

Access Levels

  • Purpose:

    • Determine the permissions and privileges during the session.

  • Configuration:

    • Assign access levels to groups associated with the computer.

    • Pre-approve users for specific access levels as needed.

Error Handling and Messages

  • Common Errors:

    • "Invalid Request parameters."

    • "No shared or personal credentials are available."

    • "Invalid Credential. You cannot use someone else's personal credential."

    • "None of the shared credentials are available."

  • Troubleshooting:

    • Verify all GUIDs and parameters are correct.

    • Ensure shared or personal credentials are available and valid.

    • Check JIT configurations and account store accessibility.

    • Confirm access levels and group assignments are properly set up.

Troubleshooting Tips

  • Invalid Parameters:

    • Check for typos or incorrect GUIDs.

    • Ensure all required parameters are included.

  • Credential Availability Issues:

    • Verify that shared credentials are available for the computer.

    • Confirm users have personal credentials assigned if needed.

  • JIT Account Creation Failures:

    • Ensure the computer is JIT-enabled.

    • Check account store configurations and permissions.

  • Access Level Selection Problems:

    • Verify that access levels are correctly assigned to groups.

    • Ensure users are pre-approved for the necessary access levels.

  • MFA Challenges:

    • Confirm that users have enrolled in required MFA methods.

    • Check that MFA policies align with access request policies.