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

# PingFederate

> Install the Oleria PingFederate agent to discover PingFederate administrators, SP connections, and the users and groups in a PingDirectory data store, plus optional admin activity.

Connect PingFederate to Oleria to see who administers your PingFederate server, which applications it federates to, and the users and groups in the directory it authenticates against. Oleria reads this through an agent that you install on a Windows machine on your network. The agent signs in to the PingFederate administrative API with a local administrative account, and reads users and groups directly from the PingDirectory data store that PingFederate uses to validate passwords.

One Oleria connection maps one PingFederate server and one LDAP data store. Connect additional servers or data stores as separate instances.

## What Oleria discovers

* **Administrators** - local administrative accounts on the PingFederate server, with their active or inactive status.
* **Applications** - SP connections, which are the applications PingFederate signs users in to.
* **Users** - user entries in the PingDirectory data store you choose, read through the LDAP Username Password Credential Validator that uses it, including whether each account is disabled.
* **Groups** - groups in the same data store (`groupOfNames`, `groupOfUniqueNames`, and inverted static groups).
* **Directories** - the LDAP data stores configured in PingFederate, with the search base of the credential validator that uses each one.
* **Activity** - PingFederate administrative audit events, such as administrator sign-ins, failed sign-ins, and sign-outs. Activity requires Fluentd and log forwarding, described below.

IdP connections, OAuth clients, authentication policies, and adapters are not synced.

## Prerequisites

* Admin access on the Oleria platform to add a new integration.
* A Windows machine to install the Oleria PingFederate agent on, and administrator permissions on it. The agent installs through a PowerShell script and runs as a Windows service.
* A PingFederate user with the **User Admin** role, to create the administrative account Oleria uses.
* The PingFederate administrative API set to native authentication, so the local account can sign in to it. See [Enable native authentication for the administrative API](#enable-native-authentication-for-the-administrative-api).
* To discover users and groups:
  * An LDAP data store in PingFederate with the LDAP type **PingDirectory** and connection security **None** (plain LDAP).
  * An **LDAP Username Password Credential Validator** that uses that data store.
  * A read-only account in PingDirectory that can search the directory. You can create one by following [Create a service account in Ping Directory](/integrations/ping-directory#create-a-service-account-in-ping-directory).

## Agent host requirements

The Oleria PingFederate agent and its bundled Fluentd log collector run on the Windows machine you choose. Make sure that machine meets these requirements:

| Requirement | Details |
| :- | :- |
| Operating system | Windows Server 2016 or later (2016, 2019, 2022, or 2025). |
| CPU architecture | 64-bit (x64). The bundled Fluentd package is x64 only. |
| CPU and memory (recommended) | At least 2 CPUs and 8 GB of RAM. |
| Installation rights | Local administrator, to run the installer from an elevated PowerShell session. The agent then runs as a Windows service. |
| Outbound HTTPS (port 443) | Your Oleria API endpoint (`api.<your-tenant>.oleria.io`), Oleria authentication (`auth.prod.oleria.io`), and Amazon S3 regional endpoints (`*.s3.<region>.amazonaws.com`, for example `*.s3.us-west-2.amazonaws.com`), which the agent uses to download the installer and upgrades and to upload data. Contact us for the regions your tenant uses. Oleria never connects in to the agent from the internet. |
| Connection to PingFederate | The PingFederate administrative console node over HTTPS, on the administrative port (`9999` by default). |
| Connection to PingDirectory | The first host name listed on the PingFederate LDAP data store, over plain LDAP (`ldap://`, port `389` unless the data store's host name includes a different port). |
| Activity (optional) | Inbound syslog from PingFederate to Fluentd on the agent machine. |

<Note>If you need to route the agent's outbound traffic through a proxy, contact us at [support@oleria.com](mailto:support@oleria.com) before you install.</Note>

## Prepare PingFederate

### Enable native authentication for the administrative API

Oleria signs in to the PingFederate administrative API with a local account's username and password. The API accepts local accounts only when it uses native authentication.

<Steps>
  <Step title="Check the authentication setting">
    On the administrative console node, open `<pf_install>/pingfederate/bin/run.properties` and find the `pf.admin.api.authentication` property.
  </Step>

  <Step title="Enable native authentication">
    If the value doesn't include `native`, set it to `native`, or to `OAuth2,native` to keep OAuth 2.0 access as well. Restart PingFederate.

    In a clustered environment, you only need to change `run.properties` on the console node.
  </Step>
</Steps>

### Create an administrative account for Oleria

<Steps>
  <Step title="Open Administrative Accounts">
    Sign in to the PingFederate administrative console with an account that has the **User Admin** role. Go to **System** -> **Server** -> **Administrative Accounts** and select **Create User**.
  </Step>

  <Step title="Enter the account details">
    On the **User Information** tab, enter a username such as `oleria-readonly` and an optional description.

    On the **Password Generation** tab, enter a strong password. Don't use **Generate one-time password**: a one-time password must be changed at first sign-in, and Oleria can't change it.

    Review the **Summary** tab and select **Done**.
  </Step>

  <Step title="Assign the Auditor role">
    On the **Administrative Accounts** window, set the new account's type to **Auditor** and select **Save**. The Auditor role has view-only access to all administrative functions.
  </Step>
</Steps>

<Note>
  Use a dedicated account for this integration rather than a person's account, so the integration keeps working if someone leaves.
</Note>

### Find the data store ID

<Steps>
  <Step title="Open Data Stores">
    In the PingFederate administrative console, go to **System** -> **Data & Credential Stores** -> **Data Stores**.
  </Step>

  <Step title="Check the data store">
    Open the PingDirectory data store that your users sign in against. Confirm its LDAP type is **PingDirectory** and its connection security is **None**.
  </Step>

  <Step title="Copy the ID">
    Copy the data store's system ID, for example `LDAP-123456789ABCDEF123456789ABCDEF123456A0AC`. You enter it when you install the agent.
  </Step>

  <Step title="Check the credential validator">
    Go to **System** -> **Data & Credential Stores** -> **Password Credential Validators**. Confirm that an **LDAP Username Password Credential Validator** uses this data store, and note its **Search Base** and **Search Filter**. Oleria searches the directory from that search base, and uses the search filter with any username to decide which entries to read.
  </Step>
</Steps>

## Connect PingFederate to Oleria

<Steps>
  <Step title="Open the integration">
    Sign in to your Oleria workspace and select **Workspace** -> **Integrations** -> **PingFederate**.
  </Step>

  <Step title="Name your agent">
    | Field | Notes |
    | :- | :- |
    | Agent Name | Required. A name for the agent, for example `pingfederate-prod`. It can only contain letters (a-z, A-Z), numbers (0-9), hyphens (-), and underscores (\_). |

    Select **Continue**.
  </Step>

  <Step title="Copy the installation script">
    Oleria shows a PowerShell installation script. Copy it, then select **Close**. You'll run the script on the Windows machine where you want to install the agent.
  </Step>
</Steps>

## Install the Oleria PingFederate agent

<Steps>
  <Step title="Run the installation script">
    Sign in to the Windows machine, open PowerShell as an administrator, and run the script you copied in the previous section. The script downloads the installers, checks their checksums and signatures, and then starts them.
  </Step>

  <Step title="Install Fluentd">
    The Fluentd installer opens first. Accept the license terms, select **Next**, and follow the prompts to complete the installation. Note the folder you install Fluentd to. Fluentd is only used for activity, but the script installs it either way.
  </Step>

  <Step title="Install the agent">
    The Oleria PingFederate agent installer opens next. Accept the license terms and select **Next**. When the installer asks, provide:

    * The PingFederate host name or IP address of the administrative console node, for example `pingfederate.example.com`
    * The PingFederate administrative port, for example `9999`
    * The username and password of the administrative account you created
    * The data store ID you copied
    * The bind DN and password of the read-only PingDirectory account, for example `uid=readonlyoleriauser,dc=example,dc=com`
    * For activity, the Fluentd installation folder and configuration file, and the option to enable activity logging. Leave activity logging off if you haven't set up Fluentd.

    Select **Next** and follow the remaining prompts to finalize the installation.
  </Step>

  <Step title="Confirm installation">
    When the installation completes, the **OleriaPingFederateConnectAgent** service appears in the Windows services list.
  </Step>
</Steps>

## Set up activity (optional)

Oleria gets PingFederate activity from the administrative audit log (`admin.log`), which records administrator sign-ins, sign-outs, and configuration changes. PingFederate sends these events over syslog to Fluentd on the agent machine, and the agent uploads them to Oleria.

To set this up, you configure a syslog appender for the administrative audit log in PingFederate's `log4j2.xml`, and a matching syslog source in the Fluentd configuration file on the agent machine. Contact us at [support@oleria.com](mailto:support@oleria.com) for the log format and Fluentd configuration to use, then enable activity logging when you install the agent.

Without activity, Oleria still discovers administrators, applications, users, and groups.

## Verify the integration

In your Oleria workspace, go to **Integrations** -> **Connected** -> **PingFederate** and select **View Details**. The side panel shows the health status of the agent. After the first sync completes, review the discovered administrators, applications, users, and groups in your Oleria workspace.

## Known limitations

* **PingDirectory only, over plain LDAP.** The data store whose ID you enter must have the LDAP type **PingDirectory** and connection security **None**. If it's an Active Directory data store, or uses LDAPS or StartTLS, user and group discovery fails for this connection. To see Active Directory users, connect [Active Directory](/integrations/active-directory) directly.
* **Other credential validator types can block user and group discovery.** If PingFederate also has password credential validators that aren't LDAP Username Password Credential Validators (for example Simple Username Password or RADIUS), user and group discovery can fail. Contact us if this applies to you.
* **One data store per connection.** Oleria reads users and groups from the one data store whose ID you enter, through the first host name listed on it.
* **Groups must match the validator's search filter.** Oleria applies the credential validator's search filter, with any username, to groups as well as users. If your filter matches an attribute that groups don't have, such as `uid`, no groups appear.
* **Group membership isn't shown.** Oleria lists groups but not which users belong to each one.
* **Directory users aren't flagged as administrators.** Only PingFederate administrative accounts are shown as administrators.
* **Every administrative account is shown as an administrator,** including accounts with only the Auditor role. Oleria doesn't show each account's individual PingFederate roles.
* **Application access isn't shown.** Oleria lists SP connections but not which users or groups can sign in to each one.
* **Activity covers administration only.** Oleria collects administrative audit events, not runtime single sign-on events from `audit.log`.
* **Non-human accounts aren't identified.** Directory entries, including entries with the `account` object class, appear as regular user accounts.
* **MFA isn't read from PingFederate.** Oleria reports every PingFederate account as not requiring MFA, whatever your actual MFA policy is.
* **No remediation actions.** Oleria can't change PingFederate or the directory from this integration.

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