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

# BeyondTrust Password Safe

> Connect BeyondTrust Password Safe Cloud so Oleria can discover BeyondInsight users, groups, roles, the non-human identities Password Safe holds, and user audit activity.

Connect BeyondTrust Password Safe to Oleria to see every BeyondInsight user, the groups they belong to, the feature permissions and Password Safe roles those groups grant, and who is an administrator. Oleria also discovers the non-human identities (NHIs) that Password Safe holds and collects BeyondInsight user audit activity.

<Note>This is a governance integration for **Password Safe Cloud**. Oleria discovers identities, groups, roles, and NHIs. It doesn't inventory assets, managed systems, or Smart Rules as resources. On-premises BeyondInsight isn't supported.</Note>

## What Oleria discovers

| Area | Detail |
| :- | :- |
| **Accounts** | Every BeyondInsight user: local users, directory users (Active Directory, Microsoft Entra ID, and LDAP), and Application users. Each account shows its name, username, email, whether it's active (an inactive or quarantined user is shown as disabled), last sign-in, whether its last sign-in used SSO, and whether it has API access. Members of the built-in **Administrators** group, and members of a group with **Full Control** on **User Accounts Management** or **API Registration Management**, are marked as administrators. |
| **Groups** | Every BeyondInsight user group and its direct members. BeyondInsight groups and directory-synchronized groups are shown with their group type. |
| **Roles** | The roles each group holds: feature permissions at their access level, such as **User Accounts Management (Full Control)**; Password Safe roles scoped to a Smart Rule, such as **Requestor on Domain Admins**; and Smart Rule access. |
| **Non-human identities** | **Application users** (OAuth clients), shown as service accounts. Their client secrets, **managed accounts**, **functional accounts**, and **Secrets Safe** secrets, shown as secrets. **API key registrations**, shown as API tokens and linked to every user the key can run as. Secrets Safe secrets show their owners. Oleria reads metadata only. It never reads passwords, keys, or secret values. |
| **Activity** | BeyondInsight user audit events, such as sign-ins, credential requests, user, group, and permission changes, API registration changes, and Secrets Safe changes, with the user who performed them. |

## Prerequisites

* A **BeyondTrust Password Safe Cloud** instance, with a URL such as `https://example.ps.beyondtrustcloud.com`. Oleria accepts instance URLs under `beyondtrustcloud.com` only.
* A BeyondInsight administrator who can create user groups, API registrations, and users.

## Choose an authentication method

Oleria supports two authentication methods. Both connect as a BeyondInsight user, and Oleria's access comes from that user's groups.

| Method | Connects as | When to use it |
| :- | :- | :- |
| **OAuth client credentials (recommended)** | A BeyondInsight **Application user** bound to an **API Access Policy** registration. | Use this method when you can. Oleria stores no user password, and Oleria's own activity is excluded from the activity it collects. |
| **API key** | The **RunAs user** of an **API Key Policy** registration. | Use this method if your organization already automates Password Safe with API keys. |

<Warning>
  If you use an API key, create a dedicated, non-human BeyondInsight user for Oleria to run as. Don't use a person's account:

  * Failed sign-ins with a wrong RunAs password or personal access token count toward that user's lockout threshold.
  * Oleria signs in as that user on every sync, so the user's audit trail (and, depending on your BeyondInsight version, its last sign-in date) reflects Oleria's activity, not the person's.
</Warning>

## Set up the integration

<Steps>
  <Step title="Create a user group for Oleria">
    In BeyondInsight, create a user group for Oleria. Under the group's **Features**, grant the permissions you need from this table.

    | Feature | Access | Used for |
    | :- | :- | :- |
    | **User Accounts Management** | Read | Required. Users, groups, group membership, feature permissions, and Smart Rule access. |
    | **API Registration Management** | Read | API key registrations. |
    | **Password Safe Role Management** | Read | Password Safe role assignments. |
    | **Password Safe System Management** | Read | Managed systems, to find their managed accounts. |
    | **Password Safe Account Management** | Read | Managed accounts and functional accounts. |
    | **Secrets Safe** | Read | Secrets Safe secrets. |
    | **User Audits** | Read | Required. Activity. |

    Oleria checks both required permissions when you connect. If any other read permission is missing, Oleria still syncs, but skips that kind of data. It picks the data up on the next sync after you grant the permission.
  </Step>

  <Step title="Share Secrets Safe folders">
    Secrets Safe returns only the secrets that the connecting user can see. Share each Secrets Safe folder you want Oleria to govern with the Oleria group.
  </Step>

  <Step title="Create the credential">
    Follow the steps for the method you chose.

    <Tabs>
      <Tab title="OAuth client credentials">
        1. Create an API registration of type **API Access Policy**.
        2. Create an **Application user**, bind it to the API Access Policy registration, and add it to the Oleria group.
        3. Copy the Application user's **Client ID** and **Client Secret**.
      </Tab>

      <Tab title="API key">
        1. Create an API registration of type **API Key Policy**, and grant it to the Oleria group.
        2. Copy the registration's **API key**.
        3. Add the dedicated BeyondInsight user that Oleria runs as to the Oleria group, and note its username.
        4. If the registration requires the **User Password** authentication factor, note the RunAs user's password. If it requires the **Personal Access Token** factor, create a personal access token for the RunAs user.

        Registrations that enforce multi-factor authentication aren't supported, because they need an interactive challenge. Use a registration without that factor, or use OAuth client credentials.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Allow Oleria's IP addresses">
    If the API registration restricts source addresses, add Oleria's IP addresses to its rules. Contact [support@oleria.com](mailto:support@oleria.com) for the current list.
  </Step>
</Steps>

## Connect BeyondTrust Password Safe to Oleria

<Steps>
  <Step title="Open the integration">
    Sign in to your Oleria workspace and navigate to **Integrations** -> **BeyondTrust Password Safe** -> **Connect**.
  </Step>

  <Step title="Complete the connection form">
    | Field | Notes |
    | :- | :- |
    | **Instance URL** | Required. Your Password Safe Cloud instance URL, for example `https://example.ps.beyondtrustcloud.com`. You can't change it after the connection is created. |
    | **Authentication method** | **OAuth client credentials (recommended)** (default) or **API key**. |
    | **Client ID** | Required for OAuth client credentials. The Application user's Client ID. |
    | **Client Secret** | Required for OAuth client credentials. The Application user's client secret. |
    | **API Key** | Required for API key. The API Key Policy registration's key. |
    | **RunAs Username** | Required for API key. The BeyondInsight user the key runs as, as a domain account name or UPN. It must be in a group that's granted the registration. |
    | **RunAs Password (optional)** | API key only. Enter it only if the registration requires the **User Password** factor. |
    | **Personal Access Token (optional)** | API key only. Enter it only if the registration requires the **Personal Access Token** factor. |
  </Step>

  <Step title="Complete the connection">
    Select **Authenticate**. Oleria signs in and confirms that it can read the connecting user's own record, which needs **User Accounts Management** (Read), and the user audit log, which needs **User Audits** (Read). If either permission is missing, the connection fails with a message that names it. Otherwise, Oleria begins the first sync.

    If BeyondInsight rejects the credentials, Oleria doesn't retry, so that a wrong password or token counts only once toward the RunAs user's lockout threshold. BeyondInsight records the reason under **User Audits**.
  </Step>
</Steps>

### Edit the connection

You can change the authentication method and credentials of an existing connection, but not the **Instance URL**. To connect a different instance, create a new connection.

* **Secrets:** Leave a secret blank to keep the stored value. You must enter a new **Client Secret** if you change the authentication method or the **Client ID**, and a new **API Key** if you change the authentication method.
* **RunAs password and personal access token:** A blank value keeps the stored one only while the **RunAs Username** and authentication method stay the same. If you change either, Oleria removes the stored values, and you must enter them again if the registration still requires them.
* **Removing a stored factor:** To remove a stored value that the registration no longer requires, select **Remove stored RunAs password** or **Remove stored personal access token**, then select **Update**.

## Verify the integration

Confirm BeyondTrust Password Safe appears on the **Connected** tab of your Oleria **Integrations** page. After the first sync completes, you can review BeyondInsight users, groups, roles, NHIs, and activity in your Oleria workspace.

## Known limitations

* **No remediation actions:** This integration is read-only. Oleria doesn't change users, groups, or NHIs in BeyondTrust Password Safe.

* **Password Safe Cloud only:** On-premises BeyondInsight and U-Series appliances aren't supported.

* **MFA status:** BeyondTrust's API doesn't report whether a user has multi-factor authentication, so Oleria shows MFA as unavailable.

* **Password changes and creation dates:** BeyondTrust's API doesn't report when a user was created or last changed their password.

* **Personal access tokens:** BeyondTrust's API can't list personal access tokens, so Oleria doesn't discover them.

* **Secrets Safe coverage:** Oleria sees only the secrets that are shared with the connecting user.

* **Activity history:** Oleria collects up to the last 120 days of user audit events.

* **User Audits permission removed later:** If the Oleria group loses **User Audits** (Read) after you connect, activity syncs fail until you grant it again. Oleria doesn't skip ahead, so the events from that period are collected once the permission is back.

* **Activity types:** BeyondTrust doesn't publish its full list of audit event types. Oleria classifies the events it recognizes, and shows any other event as a custom activity, labeled with its BeyondInsight section and action.

* **Oleria's activity in API key mode:** With OAuth client credentials, Oleria excludes its own sign-ins from the activity it collects. With an API key, the RunAs user's activity is kept, including Oleria's own sign-ins. Every event by the RunAs user is labeled as coming from the Oleria connection user, so you can tell it apart from other users' activity.

* **Credential-level access:** Oleria shows Password Safe access as roles on Smart Rules. It doesn't show which group can retrieve each individual managed account.

* **Smart Rules the Oleria group can't read:** If BeyondInsight denies Oleria access to the Password Safe roles on a Smart Rule, Oleria skips that Smart Rule's roles and still collects the roles on every other Smart Rule.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.