BeyondTrust
Connector maturity: Beta. See Connector maturity.
Description
The BeyondTrust connector uses the BeyondTrust Password Safe REST API to discover managed accounts across all managed systems. It discovers the systems registered in Password Safe and the accounts managed within each, recording managed-system membership as entitlements in OrbisID.
System Type Classification
| Field | Value |
|---|---|
| System Type | PAM Tool |
| Default Scan Priority | 500 |
Set System Type = PAM Platform to feed scan results into PAM Inventory/Reconciliation (the default for new BeyondTrust systems). Set System Type = Application instead to list the same accounts on the Accounts/Entitlements pages, like any other target system.
Version Support
| OrbisID Edition | Supported |
|---|---|
| Community | No |
| Pro | Yes |
| Enterprise | Yes |
BeyondTrust scanning requires a Pro or Enterprise licence.
Supported Protocol
| Protocol | Port | Notes |
|---|---|---|
| Password Safe REST API (HTTPS) | 443 TCP | Default; configurable via pamPlatformUrl |
What OrbisID Discovers
| Data | Source |
|---|---|
| Managed systems | GET /BeyondTrust/api/public/v3/ManagedSystems |
| Managed accounts | GET /BeyondTrust/api/public/v3/ManagedAccounts |
| Account usernames | UserName property |
| Managed system names | SystemName property — recorded as BEYONDTRUST_SYSTEM entitlements |
| Account status (active/inactive) | IsActive property |
Connection Requirements
Authentication
BeyondTrust Password Safe uses a two-factor API authentication model:
- An Application Registration API key identifies the calling application
- A run-as user credential authenticates the operator
Create an Application Registration in Password Safe (Configuration → Application & API Registrations) and note the API key.
The run-as user must have the Password Safe Operator role with at minimum:
| Permission | Purpose |
|---|---|
| Requestor or ISA access | Required to list managed accounts |
| Auditor | Alternatively grants read access without request rights |
Credential Mapping
| OrbisID Field | BeyondTrust Value |
|---|---|
credential.username | Run-as username |
credential.password | Run-as password |
system.pamPlatformUrl | Base URL of Password Safe (e.g., https://ps.example.com) |
system.attributes.btApiKey | Application Registration API key |
Network Requirements
| Requirement | Detail |
|---|---|
| HTTPS to Password Safe | OrbisID server (or On-Premise Agent) must reach Password Safe on port 443 |
| Application Registration enabled | The application registration must be active and have the API enabled |
Configuration Steps
- Create an Application Registration in Password Safe and note the API key
- Create or identify a run-as user with the required role
- Create a Credential in OrbisID:
- Username: Run-as username
- Password: Run-as password
- Navigate to Systems → Add System
- Fill in the fields:
| Field | Value |
|---|---|
| Name | Descriptive name (e.g., BeyondTrust Password Safe – Production) |
| PAM Platform URL | Base URL of Password Safe (e.g., https://ps.example.com) |
| OS Type | BeyondTrust |
| System Type | PAM Tool |
| Credential | The run-as credential created above |
- Add the
btApiKeysystem attribute with the Application Registration API key - Click Test Connection to verify authentication
- Click Save
The btApiKey attribute is required. The scan will fail to start if it is missing. Add it via Systems → Edit System → Attributes → Add Attribute.
Onboarding accounts into Password Safe
Requires Enterprise edition.
OrbisID can also add privileged accounts that are not in Password Safe to it. See Vault Onboarding for how batches, approval and rollback work. In the onboarding rules, the Managed system is the name of a managed system in Password Safe (usually the host name, so {system} fits) and the Platform is the platform that managed system must be on, by name (for example Windows) or numeric ID. This is what Password Safe needs:
- A write credential. Create a separate run-as user for this. It needs Account Management (Read/Write) to add and remove managed accounts, and System Management (Read) to find managed systems. For scanning, a read-only user is enough; this is not. The system's application API key is used as it is for scanning.
- Existing managed systems. OrbisID never creates a managed system. The one named by your rule must exist and be on the platform the rule names; if it is on a different platform, the account is shown as Blocked.
- Automatic password management. The managed system must have automatic password management turned on and a functional account set, and its platform must support it. Password Safe then takes the password over by changing it through the functional account.
- Local accounts on assets and databases. Directory and cloud managed systems, and platforms that need a secret, object ID or tenant ID, are shown as Blocked, because they need details OrbisID does not hold.
OrbisID does not have the account's password and does not send one. The managed account is added with automatic management and password testing on and no password, which Password Safe allows. OrbisID then asks Password Safe to change the password immediately and to test it. Only if the test succeeds is the account counted as onboarded; if the change or the test fails, the managed account is deleted again.
Rolling back deletes the managed accounts the batch created.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
| Scan fails: "BeyondTrust API key is required" | btApiKey attribute not set | Add btApiKey in system attributes with the application registration API key |
401 Unauthorized on sign-in | Invalid API key or run-as credentials | Verify the API key, username, and password |
403 Forbidden | Run-as user lacks required role | Assign the Requestor, ISA, or Auditor role in Password Safe |
| No accounts returned | No managed accounts accessible | Verify the run-as user has access to at least one managed system |
| Connection refused | Password Safe URL incorrect or port blocked | Verify pamPlatformUrl; check firewall rules on port 443 |