Skip to main content

​
About PingID

PingID (PingOne) is Ping Identity’s cloud identity platform. The Serval PingID integration connects to your PingOne environment using a worker application with OAuth 2.0 client credentials. Workflows can manage the full identity lifecycle — look up, create, enable, disable, unlock, and delete users, reset passwords, revoke sessions, manage group membership — plus MFA devices, and call PingOne Management and MFA APIs with typed request schemas. The integration is marked Beta in Serval’s connect UI. Authentication: OAuth 2.0 client credentials against your PingOne environment. Serval exchanges the Client ID and Client Secret for short-lived bearer tokens at https://auth.{region}/{environmentId}/as/token and attaches them to API requests at https://api.{region}. Data sync: Background sync keeps Serval’s user directory, group catalog (with memberships), and application catalog current with the PingOne environment. Users support changed-since delta syncs via PingOne’s updatedAt filter; groups re-walk in full on a schedule because PingOne exposes no group change feed.

​
What the PingID integration enables

Mutating workflows ship with installer approval by default; read-only lookups and the self-service recovery-code email run without approval.

​
Get your credentials

You need your PingOne Environment ID, a worker application Client ID and Client Secret, and the region that hosts your environment.
1

Open the PingOne admin console

Sign in to the PingOne admin console for your organization.
2

Copy the Environment ID

Go to Settings → Environment Properties and copy the Environment ID (a UUID).
3

Create or select a worker application

Under Connections → Applications, create a Worker application (or reuse an existing one). Assign roles that include Identity Data Admin for this environment — it covers the user, group, password, and session operations, and the MFA device workflows.
4

Copy the Client ID and Client Secret

From the worker application’s Overview tab, copy the Client ID and Client Secret.
5

Note your region

Select the PingOne region that matches your environment: North America (api.pingone.com), Canada (api.pingone.ca), Europe (api.pingone.eu), Asia-Pacific (api.pingone.asia), Australia (api.pingone.com.au), or Singapore (api.pingone.sg).
Worker applications are machine credentials with broad API access. Restrict the application’s roles to the smallest set that covers your Serval workflows.

​
Connect in Serval

1

Open the PingID connect form

In Serval, add the PingID integration. It is labeled Beta.
2

Region (required)

Select the PingOne API domain for your environment.
3

Environment ID (required)

Paste the UUID from Environment Properties.
4

Client ID (required)

Paste the worker application’s Client ID.
5

Client Secret (required)

Paste the worker application’s Client Secret in the password field.
6

Save and verify

Submit the form. Serval runs the health checks below.
When editing an existing connection, blank or obfuscated fields keep their stored values. Paste a new Client Secret to rotate credentials without re-entering the Environment ID.

​
Verifying the connection

Five health checks cover the integration:
  1. Test PingID Connection — reads the environment record. Success: Successfully authenticated with PingOne. Failure includes region- or credential-specific guidance from the integration.
  2. List PingOne Users — fetches one user from /environments/{environmentID}/users. Confirms Identity Data read access.
  3. List PingOne Populations — reads populations in the environment. Confirms directory read access beyond authentication alone.
  4. List PingOne Groups — fetches one group. Confirms the read access the group workflows depend on.
  5. Manage PingOne Groups — creates and immediately deletes a serval-healthcheck- prefixed group. Confirms the write access used by group management and access provisioning. This is a write check; if the delete fails, the check names the leftover group so you can remove it in the PingOne console.
If the connection test passes but user, population, or group checks fail, the worker application authenticates but lacks Identity Data Admin (or equivalent) permissions. Adjust the application’s role assignment in PingOne.

​
Gotchas and troubleshooting

Serval uses the client-credentials grant. Browser-based or authorization-code applications will not exchange tokens the way this integration expects.
A North America Client ID against an EU environment (or mismatched Environment ID) fails token exchange before any workflow runs.
Delete PingOne User is permanent and removes group memberships and MFA devices with the account. Disable PingOne User blocks sign-on reversibly and is the right default during offboarding. Disabling does not revoke existing sessions — pair it with Revoke PingOne User Sessions.
Send PingOne Password Recovery Code only works when the environment’s password policy has recovery enabled and the user has an email address. Otherwise use Reset PingOne User Password, which sets a temporary password (visible in the run output) and forces a change at next sign-on.
Create PingOne User provisions the account without credentials. Follow up with the recovery-code or password-reset workflow so the user can sign on.
Reset All PingID MFA Devices removes every enrolled factor for the target user. They must re-enroll on next sign-in. Keep installer approval enabled unless your team explicitly wants open access.
User-scoped workflows resolve PingOne users by email (falling back to username for environments that store the email there). Verify the target user’s primary email in PingOne matches the address passed from Serval tickets or workflows.
Group workflows take the exact group name and resolve the ID with a SCIM name eq filter. Group names are unique per environment only for environment-level groups — population groups can reuse a name across populations. When that happens the lookup refuses to guess; pass the optional population name input to scope it. Use List PingOne Groups to find the group spelling.
Need help? Contact support@serval.com for assistance with your PingID integration.