Skip to main content

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​

FieldValue
System TypePAM Tool
Default Scan Priority500
System Type controls where scan data goes

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 EditionSupported
CommunityNo
ProYes
EnterpriseYes

BeyondTrust scanning requires a Pro or Enterprise licence.

Supported Protocol​

ProtocolPortNotes
Password Safe REST API (HTTPS)443 TCPDefault; configurable via pamPlatformUrl

What OrbisID Discovers​

DataSource
Managed systemsGET /BeyondTrust/api/public/v3/ManagedSystems
Managed accountsGET /BeyondTrust/api/public/v3/ManagedAccounts
Account usernamesUserName property
Managed system namesSystemName 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:

  1. An Application Registration API key identifies the calling application
  2. 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:

PermissionPurpose
Requestor or ISA accessRequired to list managed accounts
AuditorAlternatively grants read access without request rights

Credential Mapping​

OrbisID FieldBeyondTrust Value
credential.usernameRun-as username
credential.passwordRun-as password
system.pamPlatformUrlBase URL of Password Safe (e.g., https://ps.example.com)
system.attributes.btApiKeyApplication Registration API key

Network Requirements​

RequirementDetail
HTTPS to Password SafeOrbisID server (or On-Premise Agent) must reach Password Safe on port 443
Application Registration enabledThe application registration must be active and have the API enabled

Configuration Steps​

  1. Create an Application Registration in Password Safe and note the API key
  2. Create or identify a run-as user with the required role
  3. Create a Credential in OrbisID:
    • Username: Run-as username
    • Password: Run-as password
  4. Navigate to Systems → Add System
  5. Fill in the fields:
FieldValue
NameDescriptive name (e.g., BeyondTrust Password Safe – Production)
PAM Platform URLBase URL of Password Safe (e.g., https://ps.example.com)
OS TypeBeyondTrust
System TypePAM Tool
CredentialThe run-as credential created above
  1. Add the btApiKey system attribute with the Application Registration API key
  2. Click Test Connection to verify authentication
  3. Click Save
btApiKey Required

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​

SymptomLikely CauseResolution
Scan fails: "BeyondTrust API key is required"btApiKey attribute not setAdd btApiKey in system attributes with the application registration API key
401 Unauthorized on sign-inInvalid API key or run-as credentialsVerify the API key, username, and password
403 ForbiddenRun-as user lacks required roleAssign the Requestor, ISA, or Auditor role in Password Safe
No accounts returnedNo managed accounts accessibleVerify the run-as user has access to at least one managed system
Connection refusedPassword Safe URL incorrect or port blockedVerify pamPlatformUrl; check firewall rules on port 443