Setting Up a BeyondTrust Integration
Note (Preview feature): This feature is available in Preview and isn't yet generally available (GA). Functionality and behavior can change before GA.
Next-Gen Trust Security uses the BeyondTrust Password Safe API to access credentials stored in Password Safe. After you connect Next-Gen Trust Security to Password Safe, you can create credential references in Next-Gen Trust Security that point to either of these items:
A managed account: a password that Password Safe manages for an account on a managed system.
A Secrets Safe secret: a credential secret, which holds a username and password, or a text secret, which holds one value.
You can then assign a credential reference to a machine in Next-Gen Trust Security. When Next-Gen Trust Security provisions a certificate to that machine, it uses the BeyondTrust credential to access the machine.
Next-Gen Trust Security reads the credential from Password Safe each time it uses it, so a password that Password Safe rotates takes effect the next time Next-Gen Trust Security uses it. You don't need to update anything in Next-Gen Trust Security. Next-Gen Trust Security never stores the retrieved password.
Note (BeyondTrust feature enablement): Creating the BeyondTrust connection requires the Superuser role and
Tenant selected in the workspace switcher.
Credential Managers is visible from any workspace, but with a workspace selected it is read only and the buttons for adding a connector are unavailable. See
Workspace-Scoped Resources.
If you don't see the menu options mentioned in the steps below, contact your Palo Alto Networks representative.
Note (Supported BeyondTrust versions): The Next-Gen Trust Security integration supports BeyondTrust Password Safe, both on-premises and Password Safe Cloud, version 24.3 and later. Pathfinder isn't supported.
How Next-Gen Trust Security Retrieves a Managed Account Password
For a managed account, each retrieval is a check-out. Next-Gen Trust Security requests the password, reads it, and checks the request back in right away, before it uses the password on the machine. When it checks the password out, Next-Gen Trust Security asks Password Safe not to rotate it at check-in, so the password it just read still works for the certificate operation.
Password Safe honors that request only when the account's access policy allows API rotation override. This matters for accounts that change their password after each release. Step 2 explains how to set this up.
Each check-out and check-in that Next-Gen Trust Security makes includes a reason that identifies the request as coming from Next-Gen Trust Security, so Password Safe administrators can tell these requests apart from others.
Step 1: Deploy VSatellites in Your Datacenter
If you don't already have any VSatellites installed, you'll need to get those up and running first. VSatellite is the connector between Next-Gen Trust Security and BeyondTrust.
The VSatellites need to be able to reach Password Safe over HTTPS. You'll need the outbound IP addresses of the VSatellites in the next step.
Step 2: Prepare BeyondTrust Password Safe
Next-Gen Trust Security signs in to Password Safe as an API user. Set up the API user, its access, and each account it serves before you connect Next-Gen Trust Security. For instructions on any of these settings, see the BeyondTrust documentation.
Create the API user that Next-Gen Trust Security signs in as. Choose one of these methods:
OAuth client credentials (recommended): Create an application user with a client ID and client secret. It runs unattended and uses short-lived tokens.
API key: Create an API registration. If the registration requires it, also create a run-as user.
Configure the API registration:
Add the outbound IP addresses of your VSatellites to the registration's source IP rules. If Password Safe is behind a load balancer, also add an X-Forwarded-For rule. Password Safe checks these rules on every call, not only at sign-in.
Turn off Enforce multi-factor authentication.
Give the API user access to the credentials Next-Gen Trust Security needs:
Managed accounts: The Requestor role on the managed systems that hold the accounts.
Secrets Safe secrets: The Secrets Safe (Read) permission and the Read Secrets and Folders permission on the safe. Safe permissions can expire, so check their end dates.
If Next-Gen Trust Security will use managed accounts, create an access policy for the API user that automatically approves View Password requests and doesn't require a ticket number.
If any managed account changes its password after each release, turn on Allow API Rotation Override in a dedicated access policy that covers only the API user and the accounts it serves. Other users keep the change-after-release behavior, and scheduled rotation still applies.
Important: Without the rotation override, Password Safe rotates the password as soon as Next-Gen Trust Security checks it in, before Next-Gen Trust Security uses it. The certificate operation then fails at the machine with a password that's no longer valid.
Prepare each managed account that Next-Gen Trust Security serves:
Turn on Enable for API Access.
Dedicate the account to the API user, or to no one.
Set Max Concurrent Requests to 0 (unlimited), or to a value higher than the number of certificate operations that can run at the same time plus the number of people who check out the account at the same time.
Warning: Keep the OAuth client secret current. The client secret expires in Password Safe, and recycling it invalidates the old secret immediately. When you recycle the secret, enter the new one in the BeyondTrust connection in Next-Gen Trust Security right away. Until you do, every BeyondTrust credential that uses the connection stops working.
Step 3: Set Up the BeyondTrust Integration in Next-Gen Trust Security
With the API user in place, you're ready to connect Next-Gen Trust Security to Password Safe.
Before You Begin
The full address of the Password Safe API. It must start with https:// and end with /api/public/v3, for example https://ps.example.com/BeyondTrust/api/public/v3.
The sign-in details of the API user from Step 2: either the client ID and client secret, or the API key and, if needed, the run-as user and password.
If Password Safe uses a server certificate from a private or internal CA, that CA's certificate in PEM format.
Performed by: Superuser
Sign in to Next-Gen Trust Security.
Click Configuration > Certificate Integrations > Credential Managers.
Click New, and then select BeyondTrust Password Safe (Preview).
Under Password Retrieval, complete the fields according to the following guidelines:
Configuration name: A name for this connection. It must be at least 3 characters, with no leading or trailing spaces.
API URL: The full address of the Password Safe API, for example https://ps.example.com/BeyondTrust/api/public/v3. The address must use https://, can't include a username or password, and must end with /api/public/v3.
Authentication Type: How Next-Gen Trust Security signs in to Password Safe:
OAuth client credentials: (Default) Enter the Client ID and Client Secret of the application user.
API key: Enter the API Key. If the API registration requires a run-as user, also enter the Run As User and, if needed, the Run As Password. The run-as user can't contain semicolons, and the run-as password can't contain a closing bracket (]).
CA Certificate: (Optional) If Password Safe uses a server certificate from a private or internal CA, paste that CA's certificate in PEM format. You can paste more than one certificate. Next-Gen Trust Security trusts these certificates in addition to the publicly trusted root CAs.
Allow everyone to consume and Authorized Workspaces: (Optional) Share this connector with other workspaces. Turn on Allow everyone to consume to share it with every workspace, including ones created later, or select specific workspaces in Authorized Workspaces. Sharing gives those workspaces read-only access without changing who owns the connector.
Choose a VSatellite: The VSatellites that can connect to Password Safe. Only active VSatellites are listed. Choose at least one.
Next-Gen Trust Security encrypts each secret when you move out of its field. Test Access is unavailable until the encryption finishes.
Note: Next-Gen Trust Security always verifies the certificate that Password Safe presents, and you can't turn this off. To trust a privately issued certificate, use CA Certificate.
Click Test Access. Next-Gen Trust Security confirms, through each VSatellite you chose, that the address is the Password Safe API and that the API user can sign in. Save stays unavailable until the test succeeds and every VSatellite you chose can reach Password Safe.
Warning: Avoid locking the API user. Password Safe records failed sign-ins, and repeated failures can lock or quarantine the API user. Next-Gen Trust Security doesn't retry a rejected sign-in. If the test fails with a sign-in error, check the sign-in details before you test again.
If your access is unsuccessful, check the troubleshooting tips below.
Click Save.
To change a connection later, open it from the list. Secret fields appear empty. Leave a secret field blank to keep its current value, or enter a new value to replace it, with these exceptions:
If you change Authentication Type, Next-Gen Trust Security clears all secret fields, and you must enter the secrets for the new method.
If you clear Run As User, Next-Gen Trust Security also removes the stored Run As Password.
Step 4: Create BeyondTrust Credentials in Next-Gen Trust Security
With the connection in place, you can create credentials in Next-Gen Trust Security. BeyondTrust credentials in Next-Gen Trust Security are references to managed accounts or secrets stored in Password Safe.
Before You Begin
In the workspace switcher, select the workspace that will use the credential. A credential belongs to the workspace it's created in, and machines in that workspace can use it. See
Workspace-Scoped Resources.
For a managed account, find the name of the managed system and the name of the account. Write a domain account as DOMAIN\account or account@domain. The account name alone doesn't match a domain account.
For a Secrets Safe secret, find either its folder path and title, or its secret ID.
Performed by: Superuser
Click Insights > Certificate Installations > Credentials.
Click New > BeyondTrust Credential (Preview). Complete the fields on the Add a New Credential screen according to the following guidelines:
Name: A name for the credential. It must be at least 3 characters, with no leading or trailing spaces.
Configuration: The BeyondTrust connection you set up in Step 3.
Access Type: Choose what Next-Gen Trust Security reads from Password Safe:
Username and Password: (Default) Both the username and the password. For a managed account, the username is the Account Name exactly as you enter it here, so enter it in the form the machine expects.
Password Only: Only the password. Use this for a text secret.
Reference Type: Choose the kind of item the credential points to:
Managed account: (Default) Enter the System Name of the managed system and the Account Name.
Secrets Safe: Enter the Folder Path and the Title of the secret. Write the folder path with the safe first and folders separated by /, for example Safe/Folder. Matching ignores case. Or, to point to the secret by its ID, turn on Advanced and enter the Secret ID. When you enter a secret ID, Next-Gen Trust Security ignores the folder path and title. Turning Advanced off clears the secret ID.
You can't change Access Type or Reference Type after you save the credential.
Click Save. The Credentials page opens with your new credential listed.
You can now test the credential you just created. Click the credential to open its details, and then click Test Access.
Test Access confirms that the connection signs in, and that the account or secret exists, is visible to the API user, and is a supported kind. It doesn't check out a managed account password, and it never causes a rotation.
Important: Because Test Access doesn't check out the password, it can't detect access policy problems, such as a policy that requires approval or a ticket number, or a concurrent request limit that's been reached. These problems appear the first time Next-Gen Trust Security uses the credential on a machine, for example when you test access on the machine, or during discovery or provisioning.
If Next-Gen Trust Security was unable to access the credential, see the troubleshooting tips below.
Step 5: Assign the BeyondTrust Credential On a Next-Gen Trust Security Machine
Performed by: Superuser
Now that the credential is in Next-Gen Trust Security, you can
assign it to a machine in the same workspace. During machine configuration, when asked for a Credential Type, choose
Select Credentials, and then select your BeyondTrust credential. A machine that signs in with a username and password lists only credentials whose
Access Type is
Username and Password.
After you assign the credential, test access on the machine. This is the first check that can catch access policy problems in Password Safe.
Limitations
Accounts whose access policy requires approval, approvers, or a ticket number aren't supported.
Accounts that change their password after each release are supported only when their access policy allows API rotation override.
Next-Gen Trust Security doesn't wait for another open request on an account. If another request holds the account, the operation fails right away.
Only passwords are retrieved, with or without a username. SSH keys, SSH key passphrases, and Secrets Safe file secrets aren't supported.
ISA accounts aren't supported.
A run-as user works with an API key only, not with OAuth client credentials.
API registrations that enforce multi-factor authentication or require a personal access token aren't supported, and neither is client certificate authentication.
Pathfinder isn't supported.
Troubleshooting
Use these tips to troubleshoot common errors. Each error message includes a reason code, such as (reason BT-2001). Messages never include a secret, a token, or the raw response from Password Safe.
Some errors can appear at more than one point:
BT-2106, listed under credential errors, can also appear at first use.
BT-5001 to BT-5003 can appear on any test or retrieval. They mean that Password Safe returned a server error, or a response that Next-Gen Trust Security couldn't read or didn't expect, such as an empty password. Check that Password Safe is running and is a supported version.
BeyondTrust Connection Errors
These errors appear when you test access on a BeyondTrust connection.
| Reason code | Error | Resolution |
|---|
| BT-1002 to BT-1005 | The address, sign-in method, sign-in details, or CA certificate is invalid | Correct the field that the message names. |
| BT-2001 | No connection to host | Check the address, and check that the VSatellite can reach it through any firewall or proxy. For Password Safe Cloud, check that the VSatellite's outbound IP address is allowed. |
| BT-2002 | BeyondTrust at host did not answer in time | Check that the VSatellite can reach Password Safe, and that Password Safe is responding. |
| BT-2003 | The certificate of host is not issued by a trusted CA | Paste the certificate of the CA that issued the Password Safe server certificate into CA Certificate. |
| BT-2004 | The certificate of host does not match the address or is not valid | Use the host name in the server certificate, and check that the certificate hasn't expired. |
| BT-2005 | host did not answer as the Password Safe API | Check that the address ends with /api/public/v3 (normally https://<host>/BeyondTrust/api/public/v3) and doesn't point to the web console or a load balancer page. |
| BT-2101 | BeyondTrust rejected the OAuth client ID or secret | Enter the current client ID and client secret. The secret might have expired or been recycled. |
| BT-2102 | Sign-in was refused | Check the API key and the run-as user and password. Check that the API registration's IP rules include the VSatellite's outbound address, and the X-Forwarded-For rule behind a load balancer. Check that the API key wasn't rotated, and that the registration doesn't require a personal access token. |
| BT-2103 | The API registration enforces multi-factor authentication | Turn off Enforce multi-factor authentication on the API registration. |
| BT-2104 | BeyondTrust refused the session | Password Safe reported an invalid license, or couldn't establish TLS trust with the VSatellite. Check the Password Safe instance settings. |
| BT-2105 | BeyondTrust refused the API version | Version 3 of the Password Safe API is turned off on the instance. Turn it on. |
BeyondTrust Credential Errors
These errors appear when you test access on a BeyondTrust credential.
| Reason code | Error | Resolution |
|---|
| BT-1006 | The reference is incomplete | Enter the system name and account name, or the folder path and title. A secret ID must be a GUID. |
| BT-2106 | BeyondTrust rejected a call after sign-in | Check the API registration's IP rules, which Password Safe checks on every call. Also check that the API user isn't quarantined or locked. |
| BT-3001 | No requestable account account on system system | Check that the account exists, has Enable for API Access turned on, has a credential, and isn't dedicated to another user. Check that the API user has the Requestor role on the system. Write a domain account as DOMAIN\account or account@domain. |
| BT-3002 | account on system is an ISA account | ISA accounts aren't supported. Use a regular managed account. |
| BT-3003 | No secret title in folder is visible to the API user | Check the folder path and title. Give the API user the Secrets Safe (Read) permission and the Read Secrets and Folders permission on the safe. If the API user can see the secret through a group, a search by folder might not find it. Use the Secret ID instead. |
| BT-3004 | title in folder matches more than one secret | Use the Secret ID. |
| BT-3005 | The secret is a file secret | File secrets aren't supported. Use a credential secret or a text secret. |
| BT-3006 | A text secret holds one value | Create a credential with Access Type set to Password Only, or use a credential secret. |
| BT-3007 | The API user lacks Secrets Safe (Read), or read permission on the safe | Give the API user the permission. Safe permissions can expire. |
| BT-3008 | Access to managed accounts was denied | Give the API user the Requestor role on the managed system. |
| BT-3009 | account on system matches more than one account | Make the system name or account name unique in Password Safe. |
Errors at First Use
These errors appear when Next-Gen Trust Security first retrieves the credential for a machine, for example when you test access on the machine, or during discovery or provisioning. Test Access on the credential can't detect them.
| Reason code | Error | Resolution |
|---|
| BT-4001 | Another request holds the account | Set Max Concurrent Requests on the account to 0 (unlimited), or above the number of parallel certificate operations plus the people who check it out. If the access policy requires approval, use an access policy that approves requests automatically. |
| BT-4002 | The access policy requires approval | Use an access policy that automatically approves View Password requests for the API user. |
| BT-4003 | The API user may not request account | Give the API user the Requestor role on the system, and turn on Enable for API Access on the account. Check that access policy location restrictions include the VSatellite, and check Max Concurrent Requests. |
| BT-4004 | The account's access policy is not usable | The policy is approver-only or doesn't have enough approvers. Use an access policy that approves requests automatically. |
| BT-4005 | BeyondTrust rejected the check-out | The access policy might require a ticket number, restrict the location, or have no schedule open now. These policies aren't supported. |
| BT-4006 | The check-out ended before it could be read | Another process might be checking in requests for this account. Dedicate the account to the API user. |
| — | The certificate operation succeeds once, and then the machine rejects the password | The account changes its password after each release, and its access policy doesn't allow API rotation override. Turn on Allow API Rotation Override as described in Step 2. |
