> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/pingone.md).
# PingOne
Harmony integrates with PingOne (Ping Identity) as an identity provider. Once connected, Harmony keeps your PingOne employee directory, SSO applications, groups and sign-in events in sync - giving you a single view of who exists in your directory, which applications they can reach, and who is actually signing in, without cross-referencing the PingOne console.
The integration is **read-only**. Harmony reads your PingOne environment and never writes to it, so connecting it cannot change a user, a group or an application in PingOne.
#### What the PingOne integration enables
| Capability | Description |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| Directory Sync | Keep your employee directory in sync, including active/inactive status and last sign-on time |
| IdP Status | See each employee's PingOne account state alongside your other identity providers |
| Application Discovery | Discover the SSO applications configured in your PingOne environment, with their sign-on protocol |
| Access Visibility | See which groups grant access to each application |
| Group Sync | Make PingOne groups available in Harmony's group pickers and access-request workflows |
| Sign-In Events | Ingest PingOne authentication events to power application login statistics and usage trends |
| Multiple Environments | Connect each PingOne environment separately, with its own directory and applications |
***
#### Prerequisites
Before you start, make sure you have:
1. **A PingOne environment**, and administrator access to it sufficient to create an application and assign roles
2. **Your PingOne environment ID** - a UUID found under **Settings** > **Environment Properties**
3. **Your PingOne region**, which matches your console domain (for example, a console at `console.pingone.eu` is Europe)
4. **A Harmony account** with permission to manage integrations
***
#### Configuration in PingOne
Harmony authenticates as a **Worker application** using the OAuth client-credentials grant. Worker applications carry no OAuth scopes - what the integration is allowed to read is decided entirely by the **administrator roles** assigned to the application, so both roles below are required.
**Step 1: Create a Worker application**
1. Sign in to your PingOne admin console
2. Go to **Applications** > **Applications**
3. Click **+** to add an application
4. Give it a name, for example "Harmony Integration"
5. Choose **Worker** as the application type
6. Save the application, then **enable** it
**Step 2: Assign the required roles**
Open the application's **Roles** tab and assign both of the following for the environment you want Harmony to read:
| Role | Grants Harmony |
| --------------------------- | -------------------------------------------------------------------- |
| **Identity Data Read Only** | Users, groups, group membership, and audit activity (sign-in events) |
| **Configuration Read Only** | Applications |
Both roles are read-only. Neither allows Harmony to modify anything in PingOne.
{% hint style="info" %}
If you use a least-privilege **custom role** instead of the built-in roles, it must include `dir:read:groupMembership` in addition to `dir:read:group`. Reading a group and reading who belongs to it are separate permissions in PingOne - without the second, applications are collected with no users on them.
{% endhint %}
**Step 3: Copy the client credentials**
1. Open the application's **Configuration** tab
2. Copy the **Client ID** and **Client Secret**
3. Confirm the **token endpoint authentication method** is **Client Secret Basic** or **Client Secret Post**. The JWT-based methods cannot be used with a client secret
**Step 4: Note your environment ID and region**
1. Go to **Settings** > **Environment Properties**
2. Copy the **Environment ID**
3. Note your region from your console domain
***
#### Connect PingOne to Harmony
1. Log in to Harmony and go to **Settings** > **Integrations**
2. Find **PingOne** under the **Identity Provider** category and click **Connect**
3. Fill in the connection form with the values below, then click **Connect**
| Field | Value |
| ------------------ | ----------------------------------------------------------------- |
| **Region** | The region matching your PingOne console domain |
| **Environment ID** | The environment ID from **Settings** > **Environment Properties** |
| **Client ID** | The Worker application's client ID |
| **Client Secret** | The Worker application's client secret |
Available regions are North America (`pingone.com`), Canada (`pingone.ca`), Europe (`pingone.eu`), Asia-Pacific (`pingone.asia`), Australia (`pingone.com.au`) and Singapore (`pingone.sg`).
**What happens when you save**
Harmony validates the connection before accepting it. It requests a token with the values you supplied, then performs each read a sync depends on - one user, one group, one group-membership query, one application, and one page of audit activity. A wrong secret, the wrong region, or a missing role is reported immediately with a specific message, rather than appearing later as a sync that quietly returns nothing.
The audit read is checked but does **not** block the connection. Applications, groups and employees do not need it - only sign-in statistics do - so a connection that cannot read audit activity is still accepted, and Harmony skips sign-in collection for it instead of failing. Both built-in roles above include audit access, so this only applies to custom roles.
#### Connecting more than one environment
A PingOne environment is a separate directory with its own users, groups and applications, and many organizations run more than one - production alongside a sandbox, for example. Each environment connects to Harmony as its own instance, with its own environment ID and credentials. Repeat the steps above for each one.
***
#### What Harmony syncs
**Employees**
Harmony reads your PingOne users and maps them to employees:
* **Work email** - from the user's `email` attribute. PingOne usernames are often not email addresses, so the email attribute is what Harmony matches on
* **Name** - given, family and formatted name
* **Job title**, **type**, **time zone** and **photo**
* **Phone numbers** - primary phone as work, mobile phone as mobile
* **Location** - city, state and country, resolved from the user's address
* **Employment start date** - from the account's creation date
* **Last login** - from the user's last sign-on time
* **Status** - active or inactive from whether the account is enabled, with PingOne's own account state (for example `OK` or `LOCKED`) surfaced as the IdP status
{% hint style="warning" %}
**Users without an email address are skipped.** PingOne allows a user to exist without one, but Harmony matches employees by work email, so such users cannot be synced. If a user is missing from Harmony, check that they have an email attribute in PingOne.
{% endhint %}
**Applications**
* SSO applications configured in your environment, with their name, sign-on protocol and login URL
* Application status, from whether the application is enabled in PingOne
* The **groups that grant access** to each application, read from the application's access-control configuration
PingOne's own built-in platform applications - the administrative console and the self-service portal - are excluded, so they do not appear alongside your SaaS applications.
**Groups**
* Group name and description
* Membership, including **dynamic groups**. A dynamic group reports no direct members in PingOne, so Harmony resolves its membership by querying which users match it
**Sign-in events**
Successful PingOne authentication events are ingested and normalized, then used to compute application login statistics and usage trends, so you can see which applications are actually being used and by whom.
***
#### Custom attributes: department, level and manager
PingOne's standard user schema has **no department, no level and no manager** field. Organizations that track these keep them in custom attributes on the user, and Harmony reads them.
By default Harmony looks for the attribute names most commonly used:
| Harmony field | PingOne attribute names checked, in order |
| -------------- | ------------------------------------------ |
| **Department** | `department` |
| **Level** | `level`, `jobLevel` |
| **Manager** | `manager`, `directmanager`, `managerEmail` |
The first attribute the user actually carries is used. The manager attribute should hold the **manager's work email**, which is how Harmony links the two employees.
If your attributes are named differently, they can be mapped explicitly - field mappings take precedence over these defaults, and can also be used to source **job title**, **employment role**, **location** and **employment start date** from a custom attribute instead of the standard schema. Contact Harmony support to configure a mapping.
***
#### What the integration does not do
The PingOne integration is read-only by design. Harmony's worker application holds only read roles, so the following are **not** available through PingOne:
* **No password reset, MFA reset, or account unlock** from Harmony
* **No account suspension or deactivation**, and no attribute writes back to PingOne
* **No group membership changes.** PingOne groups appear in Harmony and access can be *requested* against them, but every PingOne group is reported as unmanageable, so the request is routed to a person to apply in PingOne rather than applied automatically
There is also one limit that comes from PingOne itself rather than from Harmony's permissions:
* **Application access is group-based only.** PingOne has no concept of assigning an individual user to an application - access is granted through the groups listed in the application's access control. An application with **no** access-control groups is reachable by everyone in the environment; Harmony records no per-user assignments for those, so they show no seats. Usage for such applications comes from sign-in events instead
***
#### Troubleshooting
"PingOne rejected the credentials"
**Issue**: The connection is refused when you click **Connect**.
A wrong client ID, wrong client secret, wrong environment ID and wrong region all produce the same response from PingOne, so check all four:
* Confirm the client ID and client secret are copied from the **Worker** application, with no extra whitespace
* Confirm the environment ID matches **Settings** > **Environment Properties**
* Confirm the region matches your console domain - a console at `console.pingone.eu` is Europe, not North America
* Confirm the application is **enabled** in PingOne
* Confirm the token endpoint authentication method is **Client Secret Basic** or **Client Secret Post**, not a JWT method
"The Worker application is not allowed to read users"
**Issue**: PingOne returns HTTP 403 for users.
Open the application's **Roles** tab and assign the **Identity Data Read Only** role for the environment you are connecting. A Worker application has no permissions until a role is assigned, so a token can be issued successfully by an application that can read nothing.
"The Worker application is not allowed to read applications"
**Issue**: PingOne returns HTTP 403 for applications.
Applications are governed by a different role than users. Open the application's **Roles** tab and assign **Configuration Read Only** in addition to Identity Data Read Only.
Applications sync, but with no users on them
**Issue**: Applications appear in Harmony with no assigned users.
Reading a group and reading who belongs to it are separate permissions in PingOne. If you are using a custom role, make sure it includes `dir:read:groupMembership` as well as `dir:read:group`. The built-in **Identity Data Read Only** role includes both.
Note also that an application with no access-control groups is open to everyone in the environment, and Harmony deliberately records no per-user assignments for those rather than listing your entire directory against it.
"Could not reach PingOne at the selected region"
**Issue**: The check fails with a connection or timeout error.
This is almost always the wrong region. PingOne serves each region from its own domain, and a request to the wrong one does not reach your environment. Match the region to your console domain and save again. If the region is correct, PingOne may be temporarily unavailable - try again shortly.
"PingOne could not find this environment"
**Issue**: PingOne returns HTTP 404 for the environment.
The environment ID and region must refer to the same environment. Re-copy the environment ID from **Settings** > **Environment Properties** and confirm the region.
Sign-in events are missing
**Issue**: Applications and employees sync, but login statistics are empty.
* Confirm the Worker application's role grants audit access. Both built-in roles include it; a least-privilege custom role may not. If audit activity could not be read when you connected, Harmony accepted the connection and skipped sign-in collection rather than failing the whole integration - reconnect after fixing the role
* Allow time for the first collection to complete
* Confirm users have actually signed in through PingOne SSO in the period being reported
An employee is missing from Harmony
**Issue**: A user exists in PingOne but no matching employee appears in Harmony.
* Confirm the user has an **email** attribute. Users without one are skipped, because Harmony matches employees by work email
* Confirm the email is well-formed
* Confirm the user is in the environment you connected, not a different PingOne environment
* Trigger a manual sync from Harmony
"PingOne rate-limited the check"
**Issue**: Saving fails with HTTP 429.
PingOne applies rate limits per licence, shared across all environments under it, so another integration or script using the same licence can consume the allowance. Wait a moment and save again.
***
#### Data & privacy
Data handling
* All traffic to PingOne is over TLS 1.2 or higher
* Harmony stores user profiles, group memberships, application records, employment status, last sign-on timestamps and sign-in events
* Credentials are stored encrypted, and the client secret is never displayed again after it is saved
* Passwords, MFA secrets and recovery codes are never accessed
* The integration can be disconnected at any time, which stops all collection
Access control
* Harmony authenticates as a Worker application scoped to a single PingOne environment
* The two roles Harmony asks for are read-only; the integration cannot modify users, groups or applications in PingOne
* Access can be revoked at any time by disabling or deleting the Worker application in PingOne, or by disconnecting the integration in Harmony
* Rotating the client secret in PingOne requires updating it in Harmony, which re-runs the same validation checks
Compliance
* **GDPR**: data processed in line with data protection regulations
* **Regional data**: PingOne serves each region from its own domain, and Harmony connects only to the region you select
* **Audit trails**: integration activity is logged
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.harmony.io/integrations/identity-provider/pingone.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.