Connecting to Computers via OpenPSM

OpenPSM (Open Privileged Session Management) enables secure, audited, and policy-based remote sessions to managed computers via IAM Shop. Sessions support:

• Just-In-Time (JIT) account provisioning
• Multi-factor authentication (MFA)
• Role-based access level selection
• Personal and shared credential support
• Session recording and auditing

---

User Workflow: Connecting via IAM Shop

To initiate a remote session through OpenPSM:

1. Navigate to the "Manage Access" tab on the Computers resource page.

2. If starting a new browser session, click Unlock.
   

3. Enter your Master Password.
   

4. Click the Connect button next to the computer to initiate a session.
   

   🛠️Advanced Mode Credential Options

   If the Connect button is disabled, use the dropdown to select Advanced Mode.
   Advanced Mode allows users to connect using either shared or personal credentials.
   

5. Accept the Terms and Conditions to proceed to OpenPSM.
   

6. You are redirected to: https://FQDN_OF_YOUR_GATEWAY/start

---

Connection Parameters

Required Parameters

Parameter	Type	Description
TargetPersonGuid	GUID	Unique identifier of the session initiator
AccessRequestPolicyID	GUID	Identifier of the relevant access request policy
TargetComputerGuid	GUID	Identifier of the computer
IsAdvanceMode	Boolean	Indicates if Advanced Mode is used

Optional Parameters

Parameter	Type	Description
CheckOutStartDate	DateTime	Access start time
CheckOutEndDate	DateTime	Access end time
ExternalCredentialGuid	GUID	Identifier for personal credentials
PSM_Connection_Delay	Integer	Delay before prompting for master password in JIT (sec)

Additional Parameters Passed to PSM

Parameter	Description
ComputerID	Internal computer ID (e.g., 2331)
IsPersonalCred	Indicates if personal credentials are used
ExternalCredentialCheckOutID	Session ID for credential checkout
LoginSessionID	Retrieves user credentials from EmpowerID
ApiUrl	EmpowerID API URL
Mode	Connection type: RDP, SSH, Telnet
ApiKey	EmpowerID access token
CredentialID	Credential identifier
ApiApplicationKey	OAuth key for EmpowerID
GUAC_WIDTH, GUAC_HEIGHT, GUAC_DPI	Screen resolution settings

Workflow: OpenPSM Session Initialization

Step 1: Initialize Workflow

• Validate all input parameters
• Assign GUIDs: TargetPerson, AccessRequestPolicy, TargetComputer
• Display error if parameters are invalid

Step 2: Check Credential Availability

• Retrieve personal/shared credentials
• If none are found:
  • Prompt for personal credential
  • Show: "No shared or personal credentials are available."

Step 3: Select Personal Credential

• Display list of user-owned credentials
• User selects one for session use

Step 4: Consent for Session Recording

• Display recording agreement
• Proceed only if user agrees

Step 5: Set Session Parameters

• Retrieve OAuth settings
• Validate policy, computer, credentials
• Determine access time window
• Trigger JIT provisioning if needed

Step 6: Select Connection Mode

• Present available modes: RDP, SSH, Telnet
• User selects preferred mode

Step 7: MFA Authentication

• Enforce required MFA points
• Prompt user for MFA if not completed

Step 8: Access Level Selection

• Display access levels where user is pre-approved
• User selects access level for session

Step 9: Checkout Credential & Get Token

• Perform credential checkout
• Create JIT account if needed
• Validate and prepare session token

Step 10: Initiate OpenPSM Session

• Encrypt session parameters
• Launch session or return error on failure

Validation and Connection Flow

Pre-Connection Validation

• Invalid Request Parameters:
  "Invalid request parameters."
• Missing Parameters:
  "Missing request parameters."

Master Password Prompt

• User enters master password to decrypt credentials

API Request to EmpowerID

Endpoint:
/api/services/v1/secureaccessgateway/getcredential

Payload:

{
  "computer": "ComputerID",
  "credential": "CredentialID",
  "password": "MasterPassword",
  "mode": "RDP",
  "session": "UUID",
  "loginsessionid": "LoginSessionID"
}

API Response Handling

• 401 Unauthorized

  • Cause: Incorrect master password
  • Action: Prompt user to re-enter password

• Access Token Expired

  • Cause: OAuth token timeout
  • Action: Session tab is closed; user must restart the process

• Other Errors

  • Cause: API failure, connectivity, or internal error
  • Action: Redirect to error page with an option to click Close

Example Success 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
}

Connection Mode Details

RDP

• PSM sends a JSON configuration object to the Guacamole container
• If session recording is enabled, recordings are saved locally

SSH and Telnet

• Adds typescript-path and typescript-name for command logging
• Sessions are recorded and stored based on policy configuration

Encrypted Connection Object

After preparing the connection, PSM encrypts the session object and delivers it to Guacamole. This object includes:

Connection Settings

• Type (mode): RDP, SSH, or Telnet
• Hostname
• Username
• Domain (if applicable)
• Security settings
• Display resolution: width, height, DPI
• Recording configuration

API Credentials

• OAuth tokens
• API URLs
• Login/session IDs

Session Termination and Retry Logic

Session Termination

Upon closing the session, PSM calls: /api/services/v1/secureaccessgateway/endsession

Retry Mechanism

• 401 Errors: PSM retries the API call up to 7 times
• Other Errors: General retry logic is applied to ensure the session is properly closed

Configuration Guidelines

Just-In-Time (JIT) Account Provisioning

Requirement	Description
Enabled Computers	Must be JIT-enabled for temporary account use
Account Stores/Groups	Must support dynamic account creation
Behavior	Temporary account is created, assigned to appropriate groups, and time-restricted

Multi-Factor Authentication (MFA)

Requirement	Description
Policy Definition	MFA requirements defined in access request policy
Location Awareness	MFA points may vary by network zone or IP context
Enrollment	Users must have valid, configured MFA methods

Access Level Assignment

Feature	Description
Scope of Access	Determines user privileges during the session
Group Mapping	Access levels mapped to computer-associated groups
Pre-Approval	Users must be authorized for access level assignment

Error Handling and Troubleshooting

Common Errors and Resolutions

Error Message	Cause
"Invalid Request parameters."	One or more required parameters are malformed
"No shared or personal credentials are available."	No credentials are configured or available
"Invalid Credential. You cannot use someone else's personal credential."	Unauthorized use of another user's credentials
"None of the shared credentials are available."	All shared credentials are currently in use

Troubleshooting Tips

• Verify all required GUIDs and parameters are valid and correctly formatted
• Check if shared credentials are configured and available
• Confirm that users have assigned personal credentials if needed
• Ensure JIT settings, account stores, and provisioning rules are correctly configured
• Validate access level pre-approvals and group assignments
• Confirm that users are fully enrolled in the MFA policies applicable to their location and policy

Summary

By following the configurations and workflow procedures outlined in this document, administrators can enable secure, compliant, and auditable privileged sessions via OpenPSM. Consistent monitoring of policy settings, credential health, access level assignments, and MFA enrollment is critical to maintaining a secure and governed IGA environment.