Setting up a BeyondTrust integration¶

Certificate Manager - SaaS uses the BeyondTrust Password Safe API to access credentials stored in Password Safe. After you connect Certificate Manager - SaaS to Password Safe, you can create credential references in Certificate Manager - SaaS 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 Certificate Manager - SaaS. When Certificate Manager - SaaS provisions a certificate to that machine, it uses the BeyondTrust credential to access the machine.

Certificate Manager - SaaS reads the credential from Password Safe each time it uses it, so a password that Password Safe rotates takes effect the next time Certificate Manager - SaaS uses it. You don't need to update anything in Certificate Manager - SaaS. Certificate Manager - SaaS never stores the retrieved password.

How Certificate Manager - SaaS retrieves a managed account password¶

For a managed account, each retrieval is a check-out. Certificate Manager - SaaS 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, Certificate Manager - SaaS 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 Certificate Manager - SaaS makes includes a reason that identifies the request as coming from Certificate Manager - SaaS, 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 Certificate Manager - SaaS 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.

Follow our documentation to deploy VSatellites.

Step 2: Prepare BeyondTrust Password Safe¶

Certificate Manager - SaaS signs in to Password Safe as an API user. Set up the API user, its access, and each account it serves before you connect Certificate Manager - SaaS. For instructions on any of these settings, see the BeyondTrust documentation.

1. Create the API user that Certificate Manager - SaaS 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.

2. 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.

3. Give the API user access to the credentials Certificate Manager - SaaS 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.

4. If Certificate Manager - SaaS 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.

5. 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 Certificate Manager - SaaS checks it in, before Certificate Manager - SaaS uses it. The certificate operation then fails at the machine with a password that's no longer valid.

6. Prepare each managed account that Certificate Manager - SaaS 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.

Step 3: Set up the BeyondTrust integration in Certificate Manager - SaaS¶

With the API user in place, you're ready to connect Certificate Manager - SaaS to Password Safe.

Performed by: System Administrator

1. Sign in to Certificate Manager - SaaS.

2. Click Integrations > Credential Managers.

3. Click New, and then select BeyondTrust Password Safe (Preview).

4. 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 Certificate Manager - SaaS 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. Certificate Manager - SaaS trusts these certificates in addition to the publicly trusted root CAs.
   • Choose a VSatellite: The VSatellites that can connect to Password Safe. Only active VSatellites are listed. Choose at least one.

   Certificate Manager - SaaS encrypts each secret when you move out of its field. Test Access is unavailable until the encryption finishes.

   Note

   Certificate Manager - SaaS always verifies the certificate that Password Safe presents, and you can't turn this off. To trust a privately issued certificate, use CA Certificate.

5. Click Test Access. Certificate Manager - SaaS 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.

   Avoid locking the API user

   Password Safe records failed sign-ins, and repeated failures can lock or quarantine the API user. Certificate Manager - SaaS 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.

6. 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, Certificate Manager - SaaS clears all secret fields, and you must enter the secrets for the new method.
• If you clear Run As User, Certificate Manager - SaaS also removes the stored Run As Password.

Step 4: Create BeyondTrust credentials in Certificate Manager - SaaS¶

With the connection in place, you can create credentials in Certificate Manager - SaaS. BeyondTrust credentials in Certificate Manager - SaaS are references to managed accounts or secrets stored in Password Safe.

Performed by: System Administrator

1. Click Inventory > Credentials.

2. 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.
   • Owning Teams: The teams that can use this credential.
   • Access Type: Choose what Certificate Manager - SaaS 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, Certificate Manager - SaaS 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.

3. Click Save. The Credentials page opens with your new credential listed.

4. 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 Certificate Manager - SaaS uses the credential on a machine, for example when you test access on the machine, or during discovery or provisioning.

   If Certificate Manager - SaaS was unable to access the credential, see the troubleshooting tips below.

Step 5: Assign the BeyondTrust credential on a Certificate Manager - SaaS machine¶

Performed by: Resource Owner or higher

Now that the credential is in Certificate Manager - SaaS, you can assign it to a machine. Pay attention to the following when creating a new machine that you want to use this credential:

• The Owning Team on the machine configuration must match the Owning Team on the credential.
• 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.
• Certificate Manager - SaaS 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 Certificate Manager - SaaS 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.

BeyondTrust credential errors¶

These errors appear when you test access on a BeyondTrust credential.

Errors at first use¶

These errors appear when Certificate Manager - SaaS 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.

Related links¶

• Credential managers overview
• Integrations overview