# Ping identity

SureCloud connects to Ping Identity (PingOne and PingFederate) to retrieve user population records, application connection configuration, MFA policy status, and authentication policy settings. This allows SureCloud to verify that enterprise SSO is correctly configured, that MFA policies are enforced, and that access governance controls are operating across your Ping Identity environment.

## Authentication and setup

PingOne uses OAuth 2.0 with client credentials for API access. SureCloud connects using a dedicated worker application registered in your PingOne environment.

{% tabs %}
{% tab title="PingOne (cloud)" %}
{% stepper %}
{% step %}

### Create a Worker application in PingOne

Log in to the PingOne admin console. Navigate to **Applications → Applications → Add Application**. Select **Worker** as the application type and name it `SureCloud CCM`. Click **Save**.
{% endstep %}

{% step %}

### Assign read-only roles

On the application's **Roles** tab, assign the **Identity Data Read Only** and **Environment Admin (read-only)** roles. These allow SureCloud to read user, group, and policy data without making changes.
{% endstep %}

{% step %}

### Note the application credentials

Navigate to the **Configuration** tab and copy the **Client ID** and **Client Secret**. Also note the **Environment ID** from the **Overview** tab.
{% endstep %}

{% step %}

### Enter the credentials in SureCloud

Navigate to **SureCloud → Integrations → Ping Identity → Connect (PingOne)**. Enter your PingOne **Region** (e.g. `NorthAmerica`, `Europe`, `AsiaPacific`), **Environment ID**, **Client ID**, and **Client Secret**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="PingFederate (self-managed)" %}
{% stepper %}
{% step %}

### Create an OAuth client in PingFederate

Log in to the PingFederate admin console. Navigate to **OAuth Server → Clients → Create New**. Name it `SureCloud CCM` and configure it as a confidential client with the **client\_credentials** grant type. Assign read-only scopes for user and policy data. Note the **Client ID** and **Client Secret**.
{% endstep %}

{% step %}

### Enter the credentials in SureCloud

Navigate to **SureCloud → Integrations → Ping Identity → Connect (PingFederate)**. Enter the PingFederate base URL, Client ID, and Client Secret. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the Client Secret securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days and update it in **SureCloud → Integrations → Ping Identity → Edit Connection**.
{% endhint %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                                  | Use Case                                                              |
| --------------------------------------------------------- | --------------------------------------------------------------------- |
| `GET /v1/environments/{envId}/users`                      | Enumerate users in the PingOne population                             |
| `GET /v1/environments/{envId}/groups`                     | List groups and their membership                                      |
| `GET /v1/environments/{envId}/applications`               | Retrieve application connections and their SSO configuration          |
| `GET /v1/environments/{envId}/signOnPolicies`             | Retrieve authentication (sign-on) policies and their MFA requirements |
| `GET /v1/environments/{envId}/mfaSettings`                | Retrieve MFA device policy configuration                              |
| `GET /v1/environments/{envId}/users/{userId}/mfaSettings` | Retrieve per-user MFA device enrolment status                         |

## Pagination

`GET /v1/environments/{envId}/users` uses cursor-based pagination. SureCloud uses the `_links.next.href` from each response to retrieve subsequent pages until no `next` link is present.

```
GET /v1/environments/{envId}/users?limit=100&cursor=<value_from_previous_response>
```

## Required permissions

SureCloud requires a PingOne Worker application with:

| Role                          | Purpose                                               |
| ----------------------------- | ----------------------------------------------------- |
| Identity Data Read Only       | Read users, groups, and population data               |
| Environment Admin (read-only) | Read application connections and policy configuration |

No write, create, or provisioning permissions are required.

## Polling frequency

| Data Type                            | Interval       |
| ------------------------------------ | -------------- |
| User population and group membership | Every 24 hours |
| Application SSO configuration        | Every 24 hours |
| Authentication and MFA policies      | Every 24 hours |
| Per-user MFA enrolment               | Every 24 hours |

## Troubleshooting

<details>

<summary>Authentication fails with "invalid_client" or 401</summary>

The Client ID or Client Secret is incorrect, or the Worker application has been deleted. Navigate to **PingOne → Applications → SureCloud CCM**, confirm the application is active, and regenerate the Client Secret if necessary. Update the credentials in **SureCloud → Integrations → Ping Identity → Edit Connection**.

</details>

<details>

<summary>User list returns empty despite a populated directory</summary>

Confirm the Worker application has been assigned the **Identity Data Read Only** role at the environment level. Role assignments are made on the application's **Roles** tab, not within the OAuth scope configuration. Without this role, user API calls will return empty or 403.

</details>

<details>

<summary>Wrong region causes connection failures</summary>

PingOne API endpoints are region-specific. Using the wrong region will result in 404 or DNS resolution errors. Confirm your PingOne environment's region from the admin console URL (e.g. `console.pingone.eu` indicates the Europe region). Update the region in **SureCloud → Integrations → Ping Identity → Edit Connection**.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/ping-identity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.