Page Comparison

This guide provides comprehensive instructions for administrators on establishing privileged sessions to computers using OpenPSM through IAM Shop. It covers necessary parameters, user interaction steps, workflow processes, configurations, best practices, and troubleshooting tips to ensure secure and compliant connections.

Overview

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.

Connection Parameters

...

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 Added

2. Enter their Master Password.
   

   Image Added

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

   Image Added

Note: 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.

Image Added

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

   Image Added

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

Connection Parameters

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.

...

• 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:

  • If the access token has expired, PSM closes the tab 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

...

• 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.

Best Practices

• Parameter Verification: Always verify that all required parameters are correctly specified when initiating connections.

• Credential Management: Regularly update and manage shared and personal credentials to ensure availability.

• Policy Configuration: Align access request policies with organizational security requirements, including MFA and session recording.

• Monitor JIT Processes: Ensure JIT account provisioning and deprovisioning processes are functioning correctly.

• User Education: Inform users about session recording policies and the importance of providing consent

  • .

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.

...