> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CyberArk PAM (Self-Hosted)

> Connect Serval to your self-hosted CyberArk PAM deployment via the PVWA REST API for privileged-access management workflows - safes, safe membership, vault users, credential rotation, and access-request approvals.

## About CyberArk PAM (Self-Hosted)

The CyberArk PAM (Self-Hosted) integration connects Serval to a CyberArk Privileged Access Manager deployment you host yourself, through the Password Vault Web Access (PVWA) REST API. It powers privileged-access management workflows: listing safes and accounts, granting and revoking safe membership for just-in-time (JIT) access, vault user lifecycle actions (disable/offboard), triggering CPM credential rotation, and approving or rejecting dual-control access requests.

**Serval never retrieves or stores vaulted secret values.** The curated API surface excludes all credential-retrieval endpoints - workflows can manage who has access to safes and when credentials rotate, but there is no path through Serval to read a vaulted password.

**Authentication:** Username and password for a dedicated service account (CyberArk-local or LDAP). Serval exchanges the credentials for a PVWA session token and attaches it to every proxied request - workflow code never sees the password or the token.

**Data sync:** On demand only. There is no background sync of safes, accounts, or users - Serval calls your PVWA only when a workflow or health check runs.

## What the CyberArk integration enables

| Capability                  | Description                                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Safe and account visibility | List safes, safe members, and the accounts stored in safes your service account can see - metadata only, never secret values. |
| JIT safe access             | Grant and revoke safe membership so privileged access can be provisioned just-in-time and cleaned up automatically.           |
| Vault user lifecycle        | Disable a vault user as part of offboarding or incident response.                                                             |
| Credential rotation         | Trigger CPM-managed password change operations on accounts (CyberArk's CPM performs the rotation; Serval only initiates it).  |
| Dual-control approvals      | List pending access requests and approve or reject them, so request/approve flows can run through Serval.                     |

## Prerequisites

Before connecting, make sure your deployment meets these requirements:

<Steps>
  <Step title="PVWA reachable over HTTPS from Serval">
    Your PVWA must be reachable over HTTPS from Serval's egress IPs. Self-hosted deployments typically need a firewall allowlist rule or reverse-proxy exposure for this - PVWA instances reachable only on a private network cannot be connected.
  </Step>

  <Step title="PVWA version 12.0 or later">
    The integration uses the Gen2 REST API, available from PVWA 12.0 onward.
  </Step>

  <Step title="A dedicated service account for Serval">
    Create a dedicated account for Serval, either a CyberArk-local user or an LDAP user. RADIUS and SAML authentication types are not supported - they are interactive and cannot be used by an API client.
  </Step>
</Steps>

### Least-privilege guidance for the service account

Grant the service account only what the workflows you install actually need:

* **Audit Users** (and safe management rights) if you install the vault user lifecycle workflows.
* **Membership on the safes Serval will manage**, with `manageSafeMembers` (for grant/revoke workflows), `listAccounts` (for account listing), and `initiateCPMAccountManagementOperations` (for rotation workflows).
* **No "Retrieve accounts" permission anywhere.** Serval's API surface has no credential-retrieval endpoints, but the account should not hold that permission regardless - defense in depth.

Where your organization's policy supports it, also enable "user cannot be used interactively"-style restrictions on the account and IP-allowlist it to Serval's egress IPs, so the credential is useless outside the integration.

## Connect in Serval

<Steps>
  <Step title="Select CyberArk PAM (Self-Hosted)">
    In Serval, open your team's integrations page and select **CyberArk PAM (Self-Hosted)**.
  </Step>

  <Step title="Enter the Base URL (required)">
    Enter your PVWA host, for example `pvwa.acme.com`. You do not need to include `https://` - Serval normalizes the value and always connects over HTTPS.
  </Step>

  <Step title="Choose the Auth Type (required)">
    Select **CyberArk** for a CyberArk-local service account or **LDAP** for an LDAP-backed one. This selects which logon endpoint Serval uses.
  </Step>

  <Step title="Enter the Username and Password (required)">
    Enter the dedicated service account's username and password. Serval stores the password encrypted and uses it only inside the proxy to authenticate.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval authenticates and runs the health checks (below).
  </Step>
</Steps>

<Note>
  **Session behavior:** Serval authenticates via `POST /PasswordVault/API/Auth/{type}/Logon` with `concurrentSession: true` and caches the session token briefly (about 15 minutes), so the service account must be permitted concurrent sessions. Without concurrent sessions, a Serval logon can terminate another active session for the same account (or vice versa).
</Note>

## Verifying the connection

Four health checks run after you connect:

1. **Test Connection** - authenticates against the PVWA and lists safes. Failure usually means the Base URL is wrong, the PVWA is not reachable from Serval's egress IPs, or the username/password/auth type is incorrect.
2. **List Safes** - confirms the service account can enumerate safes. Failure with a working Test Connection means the account has no safe memberships or lacks list rights.
3. **List Users** - confirms vault user read access. Failure typically means the account lacks the Audit Users permission.
4. **List Accounts** - confirms the account can list accounts in its safes. Failure typically means the account is missing `listAccounts` on the managed safes.

<Tip>
  If Test Connection fails outright, fix reachability and credentials first. If it passes but a later check fails, the service account authenticates fine and is just missing a CyberArk permission - adjust its vault authorizations or safe memberships.
</Tip>

## Installable workflows

The integration ships with installable workflows (names indicative):

| Workflow                     | Type  |
| ---------------------------- | ----- |
| List Safes                   | Read  |
| List Safe Members            | Read  |
| List Accounts                | Read  |
| Grant Safe Access            | Write |
| Revoke Safe Access           | Write |
| Disable Vault User           | Write |
| Rotate Account Credentials   | Write |
| List Pending Access Requests | Read  |
| Approve Access Request       | Write |
| Reject Access Request        | Write |

<Note>
  Write workflows default to **installer approval**: when a help-desk conversation or automation reaches a write step, the workflow pauses for sign-off from the installing team before the change is made in CyberArk.
</Note>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Serval cannot read vaulted secrets - by design">
    The curated API surface excludes every credential-retrieval endpoint, so no workflow (prebuilt or custom) can fetch a vaulted password through Serval. If a workflow needs to hand a credential to a person, do that inside CyberArk (for example via a dual-control access request that Serval approves), not through Serval.
  </Accordion>

  <Accordion title="RADIUS and SAML service accounts do not work">
    Those auth types are interactive (challenge/response or browser redirect) and cannot be driven by an API client. Use a CyberArk-local or LDAP service account.
  </Accordion>

  <Accordion title="The service account needs concurrent sessions">
    Serval logs on with `concurrentSession: true` and caches the session token for about 15 minutes. If the account is restricted to a single session, Serval's logon and any other use of the account will terminate each other's sessions.
  </Accordion>

  <Accordion title="PVWA must be exposed to Serval's egress IPs">
    Self-hosted PVWAs usually sit behind a firewall. Add an allowlist rule for Serval's egress IPs or expose the PVWA through a reverse proxy over HTTPS. A PVWA reachable only on a private network fails the Test Connection health check even with valid credentials.
  </Accordion>

  <Accordion title="Service-account permissions drive every workflow">
    CyberArk enforces authorization on the service account you configure. A grant/revoke workflow fails if the account lacks `manageSafeMembers` on the target safe; rotation fails without `initiateCPMAccountManagementOperations`. Grant per-safe permissions for exactly the workflows you install.
  </Accordion>

  <Accordion title="Rotation is asynchronous">
    Rotate Account Credentials marks the account for a CPM-managed change; the CPM performs the rotation on its own schedule. A successful workflow run means the operation was queued, not that the password has already changed.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your CyberArk PAM (Self-Hosted) integration.