Building a PSM connector for a web application

When a console has its own login page and nothing in the Marketplace, PSM can still open it for your users: isolated, recorded, with the password typed for them. Here is how to build that connector, test it and keep it working.

The short version

A PSM web connector is a connection component that drives a real browser on the PSM server. It follows a short list of instructions, the WebFormFields, to type the vaulted credentials into the login page, checks that the login worked, then hands the window to the user.

  • Check first: if the Marketplace already has a connector for your console, deploy it. Build only what nobody covers.
  • The framework: CyberArk (now Idira) ships it as the Secure Web Application Connectors Framework. It drives Chrome or Edge through Selenium WebDriver, and since version 14.6 it uses a 64-bit dispatcher by default.
  • The work: copy the sample component, describe the login in a few lines, link the component to a platform, test.
  • The real cost is upkeep: browsers update every few weeks, and the driver must match the browser version exactly. Plan for it from day one.

Before you build: four routes

There are four ways to bring a privileged web session under control, from the cheapest to the most expensive. Check the first two before paying for the third.

Your targetBest route
A console the Marketplace already coversDeploy the Marketplace connectorPackaged and documented. Testing it against your version is still your job.
A SaaS application your users reach through Idira IdentitySecure Web SessionsActivity is recorded from the user's own browser, through an extension. No jump server, so no isolation.
A web console with a login page, on premises or in the cloudA PSM web connector, the subject of this guideThe session runs on the PSM server: isolated, recorded, and the password never reaches the workstation.
A Windows thick clientA Universal ConnectorAutoIt or SDK automation of the client: a different job, covered on our connector development page.

Isolation is what separates the third route from the second. When the console administers something that matters, such as a firewall, a hypervisor or a backup system, you want the session to run away from the user's workstation. That is the job PSM does.

How a PSM web session works

A web connector is a chain of five links. Knowing which link does what saves hours when something breaks.

How a PSM web session runsThe user connects from PVWA; PSM takes the password from the Vault; on the hardened PSM server, WebAppDispatcher starts Chrome or Edge through the WebDriver; the browser logs in to the web console, then the session is shown to the user over RDP and recorded.PSM server · hardenedUserRDP clientPVWAConnectVaultpasswordDispatcherWebAppDispatcherWebDrivermatches browserChrome / EdgeincognitoRecordingvideo + auditWeb consolelogin page12345
Fig. 2From the click on Connect to the console on screen. The password stays on the PSM side.
  1. 1 The user clicks Connect in PVWA, which opens a session on a PSM server.
  2. 2 PSM takes the account’s password from the Vault; the user never receives it.
  3. 3 WebAppDispatcher starts Chrome or Edge through the WebDriver.
  4. 4 The driver fills in the login page from the WebFormFields lines, then checks the validation element.
  5. 5 The user takes over the browser window through RDP. The whole session is recorded.

Three details matter in practice. The browser runs on the PSM server, in an incognito window, and PSM ties the session to that window. The driver, chromedriver.exe or msedgedriver.exe, must be exactly the same version as the browser. And the login is a script: if one line fails, the user gets an error instead of the console. By default the browser stays minimised behind a progress bar while that script runs.11The MinimizeBrowserWhenLoading setting, on Yes by default. Setting it to No while you develop lets you watch each step.

Prerequisites

ItemWhat you need
PSM14.2.3 or later for the current framework. From 14.6, the 64-bit dispatcher is the default.
FrameworkThe latest Secure Web Application Connectors Framework, from the Marketplace (Integrations). Since browser driver 133, version 14.6.0.244 or later.
BrowserGoogle Chrome 100 or later, or Microsoft Edge 103 or later, in 32 or 64 bits. Edge's IE mode is not supported.
Driverchromedriver.exe or msedgedriver.exe of exactly the browser's version, in the PSM Components folder.
HardeningThe PSM hardening script run with web application support, and the browser allowed in the AppLocker configuration.
PlatformThe character > added to the platform's forbidden password characters, as the documentation requires: it is the separator in every WebFormFields line.

Build it step by step

  1. Install the frameworkExtract the Marketplace zip on the PSM server and copy the content of its Components folder to PSM\Components for the 32-bit dispatcher, or to PSM\Components\x64 for the 64-bit one.
  2. Prepare the browserInstall Chrome or Edge and the matching driver. Run PSMHardening.ps1 with web application support (the -supportWebApplication option, or $SUPPORT_WEB_APPLICATIONS on a server outside the domain), then allow the browser in PSMConfigureAppLocker.xml and run PSMConfigureAppLocker.ps1. Check that the path in the XML file is where the browser is really installed.
  3. Copy the sampleIn PVWA, under Administration, Configuration Options, Options, Connection Components, copy PSM-WebAppSample, paste it, and give the copy its own Id and display name.
  4. Describe the loginUnder Target Settings, Web Form Settings: LogonURL is the login page and can use account properties, as in https://{Address}/login; WebFormFields holds the login lines; EnforceCertificateValidation stays on Yes.
  5. Choose the browserSet ClientApp to Chrome, the default, or to Edge, and leave MainWindowClass at Chrome_WidgetWin_1, the right value for both.
  6. Touch the timeouts only if neededActionTimeout (10 seconds by default) and PageLoadTimeout (30 seconds) suit most consoles. Slow appliances may need more.
  7. Link the component to a platformIn Platform Management, edit the platform, add the connection component under UI & Workflows with its Id and Enable set to Yes, and add > to its forbidden characters.
  8. Test with a lab accountConnect from PVWA. If the login fails, switch on advanced debugging and read the screenshots, as described below.

When the login needs the credentials of the account's linked logon account, add the LogonAccount capability to the component (Target Settings, Supported Capabilities) and use its placeholders, listed in the next section.

The WebFormFields cheat sheet

WebFormFields is a list of lines, run from top to bottom. Each line finds one element on the page and does one thing with it, always in the same order: the identifier, the separator >, the value or the action, then how to find the element.

Pattern

identifier > value or (Action) (SearchBy=Id|Name|Class|Text|XPath)
ToWrite
Type into a fieldusername > {username} (SearchBy=Id)Add (SendSlow=0.2) for fields that drop characters typed too fast: the value is the delay, in seconds, between two characters.
Clicklogin > (Button) (SearchBy=Id)(Click) does the same on any clickable element.
Click through JavaScriptmenu > (ScriptClick) (SearchBy=Id)For hidden or dynamic elements that ignore a normal click.
Prove the login workedlogout > (Validation) (SearchBy=Id)(Verification) is equivalent. Validation lines come last.
Explain a failureerror > (Failure) (SearchBy=Class) (Message=Your text)Shows your words instead of a generic “Element not found”.
Enter a framemain > (iFrame) (SearchBy=Id)(iFrame) alone enters a frame that has no identifier, more slowly. Nested frames work; (MainWindow) goes back to the page.
Open another page(Navigate=https://console.example/home)The address must contain ://.
Pause(Wait=1)Also closes a validation block, see below.
Type an MFA codeRun Generate_TOTP_MFA_Code (MFADeviceSecret=…), then otp > &MFACode&TOTP codes only. Read the security note before using it.
Branchif ((…)) … end-ifWith else-if, else and the Exists, Count and Placeholder conditions.
Account values
{username}, {password}, {address} and any other property of the account, such as {domain}: {username}@{domain} is valid.
Linked accounts
{logonaccount\username}, {reconcileaccount\password}, {extraaccount\password}. Logon account values need the LogonAccount capability.
PreConnect values
Whatever your own PreConnect DLL returns, written &name&.
XPath
Put a caret before every square bracket: //form^[@id='login'^]//button.
Search order
Without SearchBy, the element is looked up by Id, then Name, then Class. Naming the method avoids surprises.

One rule about validation catches everyone once. A validation line opens a block: the compatible lines that follow it, such as iFrame, Navigate or MainWindow, stay in that block and are skipped as soon as a validation succeeds. Several validation lines in a row are alternatives, and one success is enough. To navigate after a successful validation, put another command in between, such as (Wait=1).

A worked example, line by line

To show the method without touching anyone's console, we use the login page of the-internet, an open-source practice site from Sauce Labs that Selenium users train on. Its demo credentials are printed on the page: in a lab, store them in a test account, in a test safe.

1. Read the login page

Open the page in the browser on the PSM server itself, then inspect the form. The two fields have the ids username and password. The button has no id and no name, only the class radius.

2. Read the page after login

This is the step most people skip, and it is where validation goes wrong. The secure area that follows a successful login has a logout link pointing to /logout, a success message, and a span whose id is… username, like the login field.

  • Validating on username would pass on the login page itself: a failed login would look like a success.
  • Validating on the class radius would pass too: the login button and the logout link share it.
  • The logout link exists only after a successful login. That is the element to check.

3. Write the lines

LogonURL

https://the-internet.herokuapp.com/login

WebFormFields

username > {username} (SearchBy=Id)
password > {password} (SearchBy=Id)
radius > (Button) (SearchBy=Class)
error > (Failure) (SearchBy=Class) (Message=The site refused the password stored in the vault)
//a^[@href='/logout'^] > (Validation) (SearchBy=XPath)

Line by line: fill in the two fields with the account's credentials, click the button, show a clear message if the site displays its error banner (its class includes error), and confirm success on the logout link. The carets in the last line escape the XPath brackets, as the framework requires.

On a real console, the LogonURL usually becomes https://{Address}/login, so that one connection component serves every appliance of the same model.

Harder logins

Two-step logins

Many consoles ask for the username, then show the password field on a second screen. That only takes more lines: type the username, click Next, type the password, click Sign in. Pauses are rarely needed, because the framework already waits for each element to become usable, up to WaitForElementActionableTimeout (ActionTimeout when it is not set). Raise that before adding (Wait) lines.

identifier > {username} (SearchBy=Id)
next > (Button) (SearchBy=Id)
password > {password} (SearchBy=Name)
signin > (Button) (SearchBy=Id)
account-menu > (Validation) (SearchBy=Id)

Frames

Older consoles often load the login form inside a frame. Enter it before the fields, then come back to the main page before validating anything that lives outside the frame.

(iFrame)
user > {username} (SearchBy=Name)
pass > {password} (SearchBy=Name)
signin > (Button) (SearchBy=Id)
(MainWindow)
nav-menu > (Validation) (SearchBy=Id)

MFA codes

For TOTP-based MFA, the framework can compute the code itself from the device secret, and type it wherever you write &MFACode&:

username > {username} (SearchBy=Id)
password > {password} (SearchBy=Id)
login > (Button) (SearchBy=Id)
Run Generate_TOTP_MFA_Code (MFADeviceSecret=YOUR-BASE32-SECRET)
otp > &MFACode& (SearchBy=Name)
dashboard > (Validation) (SearchBy=Id)

The documentation's own example writes the secret into the connection component. Treat that as a lab shortcut: anyone who can read the PVWA configuration can read the secret, and a TOTP secret belongs to one account, while a component serves many. In production, keep each secret with its account, and check in your lab whether your version accepts an account placeholder in the MFA command; if it does not, a PreConnect DLL (below) can supply the secret. Push notifications and hardware tokens need a person, so they cannot be scripted this way.

Screens that appear only sometimes

A “session already open” prompt, a cookie banner, a password expiry page: these break a fixed script. Conditional blocks handle them.

username > {username} (SearchBy=Id)
password > {password} (SearchBy=Id)
login > (Button) (SearchBy=Id)
if ((resume-session > (Condition) (SearchBy=Id) (Exists eq true)))
resume-session > (Button) (SearchBy=Id)
end-if
dashboard > (Validation) (SearchBy=Id)

Each condition sits in its own parentheses, and conditions are joined with and or or. Exists tests whether an element is there, Count compares how many elements match (eq, ne, gt, ge, lt, le), and Placeholder compares an account or PreConnect value, which lets some accounts follow a different path. else-if and else blocks follow an end-if, and every block has its closing command.

Basic authentication

Since PSM 14.0, the framework can also answer the browser's Basic or Digest authentication prompt, with the credentials placed in the address through account placeholders (domain\username:password@URL). Two limits matter: PSM cannot tell whether the authentication worked, so add a validation or failure line, and a wrong syntax can write sensitive data to the logs. On a hardened PSM, the browser policy must also allow the basic and digest schemes before you run the hardening again.

Values computed before the login

When the login needs something the Vault doesn't hold as such (a temporary user, a token, a value derived from the username), the framework can first call your own .NET DLL. It implements the IPreconnectContract interface from CyberArk.PSM.WebAppDispatcher.PreconnectUtils.dll, which ships with PSM. You declare it in the component's client-specific settings (PreConnectDllName, PreConnectParameters) and use what it returns as &name& in WebFormFields. Throw a PreconnectException on any error, so that the user sees your message rather than a generic one.

When it fails

Start with the screenshots. EnableAdvancedDebugging, a platform parameter, makes the dispatcher capture an image at each WebFormFields step, which shows exactly where the login stops. Delete the screenshots folder once you are done: both the images and the file names can contain sensitive data.

SymptomCause and fix
“Element not found” on the first lineA wrong identifier, a form inside a frame, or a page still loading.Inspect the page in the browser on the PSM server itself, add (iFrame), or raise PageLoadTimeout.
Worked yesterday, fails for every account todayThe browser updated, the driver did not.Install the driver of exactly the browser's version, or deploy the WebDriverUpdater tool.
The browser no longer starts at allAppLocker no longer recognises the updated browser.The browser rule in PSMConfigureAppLocker.xml is a hash rule (Method="Hash"): run PSMConfigureAppLocker.ps1 again after each browser update.
A warning page instead of the login page, on an HTTP consoleHTTPS-First Mode, on by default in incognito windows since Chromium 127.Move the console to HTTPS; failing that, test and adjust the browser policy on PSM.
A certificate error on an internal consoleA self-signed certificate or a private certificate authority.Make the PSM server trust the internal authority; set EnforceCertificateValidation to No only as a last resort.
The login works, the validation failsThe element differs between landing pages, or a Navigate line directly follows the validation lines.Validate on an element that every post-login page has; separate a following Navigate with another command, such as (Wait=1).
A connector breaks after the move to the 64-bit dispatcherComponents from the Marketplace still sit in the 32-bit folders.Copy them to Components\x64\Connectors, or point ClientDispatcher back at {PSMComponentsFolder32}.
Works for one account, not for anotherScreens specific to the account: consent, password expiry, MFA enrolment.Add if/else blocks, or a Placeholder condition.

Security: don't let a connector weaken PSM

  • Harden first, build second: run the hardening with web support rather than relaxing browser policies by hand, and allow only the browser you actually use.
  • HTTPS and certificate checks: the vendor supports HTTP, and basic authentication over HTTP, but recommends against both. Keep EnforceCertificateValidation on Yes.
  • No secret in the component: passwords come from placeholders, and MFA secrets stay with their accounts.
  • Clean up after debugging: delete the screenshots and switch EnableAdvancedDebugging off again.
  • One component per application: easier to review, test and retire than one component stretched across several consoles with if/else blocks.

Keeping it alive

A web connector is finished the day it works, and starts ageing the next morning. Four habits keep it alive.

  1. Update the browser, the driver and AppLocker togetherThe driver must match the browser exactly. The WebDriverUpdater tool from the Marketplace checks both every hour and downloads the matching driver from Google or Microsoft; if you prefer change windows, do all three in one go.
  2. Keep the framework currentBrowsers change underneath it: after driver 133, the framework had to be at 14.6.0.244 or later to keep working properly.
  3. Test again after every change, on either sideA PSM upgrade, a console update, a new login screen. Keep one test account per connector and a short test list: login, failure message, validation, recording.
  4. Choose stable identifiersIds first, then names. Classes generated by front-end frameworks and long XPath expressions break at the first redesign.

If you inherit old connectors built on the WebFormDispatcher, convert them: point ClientDispatcher at CyberArk.PSM.WebAppDispatcher.exe and set ClientApp to the browser. Test each one again afterwards.

Privilege Cloud

With Privilege Cloud, PSM runs on the connector servers in your own network, so everything above applies there: framework, browser, driver, hardening and upkeep. The Privilege Cloud documentation has its own copy of the procedure. Those connector servers also follow a support calendar of their own: see our end-of-life table.

How we can help

We build web connectors for the consoles the Marketplace doesn't cover (vendor portals, appliance interfaces, internal tools), test them against your PSM version, and hand over the component, the test list and the documentation. We can also review the connectors you already run before an upgrade.

Describe your console

More on this service: PSM connectors and CPM plugins.

Sources

Checked against PAM Self-Hosted 15.2 on 15 November 2026. Menus and parameter names can differ in older versions; the official pages remain the reference.

Questions

PSM web connectors, in short

Can a PSM web connector handle MFA?

Yes, for TOTP codes: the framework computes the code from the device secret and types it into the page. Push notifications and hardware tokens need a person, so they cannot be automated; ask the application owner whether a TOTP option exists.

Why did my web connector stop working after a browser update?

Almost always because the driver no longer matches the browser version. Install the matching chromedriver or msedgedriver, or deploy the WebDriverUpdater tool. If the browser no longer starts at all, run the AppLocker script again: its browser rule is a hash rule.

Should I use Chrome or Edge on PSM?

Both are supported: Chrome 100 or later and Edge 103 or later, in 32 or 64 bits, without Edge's IE mode. Choose the one your PSM servers already maintain; Chrome is the default.

Does the same connector work with Privilege Cloud?

Yes. PSM runs on your connector servers, with the same framework, browser and driver requirements.

Can users see the password?

No. The driver types it into the page on the PSM server before the user takes over the window, and by default the browser even stays minimised during the login. The password never reaches the workstation.

● Next step

Tell us about your vault

Version, size, deadline. We will tell you straight away whether we are the right people for it.