Audit reporting service


Audit activities and events

The audit reporting service caches incoming audit messages and provides endpoints to request audit events for a specified date range. The following events and actors are tracked:

  • Actions

    Logs any action or activity against a defined PingOne resource. The audit message includes the ID for the resource affected by the event.

  • Actors

    Tracks the actor or agent who initiated the action. The audit message includes the unique identifier and the friendly name of the actor (end user) responsible for the event and the client used by the actor to perform the action on the resource.

  • Date and time

    The date and time the audit activity was recorded.

  • Status

    Tracks and caches the resulting status of the action. The audit message specifies the success or failure of the event, and if a failure occurred, it provides the reason for the failure.

Filtering result data

GET requests for audit activities require a SCIM filter to specify start and end dates for the result data. For large collections, additional filtering expressions can be added to the request URL to focus on particular event types. For example, this SCIM filter returns audit events from the start date of “2018-01-01” and an end date of “2018-03-31”:

https://api.pingone.com/v1/environments/{id}/activities?filter=recordedat gt "2018-01-01T00:00:00Z" AND recordedat lt "2018-03-31T23:59:00Z"

These SCIM operators can be applied to the following attributes:

  • eq (equals)

    Supported attributes: correlationid, actors.user.id, actors.user.name, actors.client.id, action.type, resources.id, resources.type, resources.population.id, org.id, environment.id

  • gt (greater than)

    Supported attributes: recordedat

  • lt (less than)

    Supported attributes: recordedat

  • ge (greater than or equal to)

    Supported attributes: recordedat

  • le (less than or equal to)

    Supported attributes: recordedat

  • in (includes)

    Supported attributes: action.type, resources.population.id

  • and (logical AND)

    Logical AND for building compound expressions in which both expressions are true.

  • or (logical OR)

    Logical OR for building compound expressions if either expression is true.

Note: These SCIM operators are not supported: ne (not equal), co (contains), ew (ends with), pr (present, is a non-empty or non-null value), sw (starts with), not (logical NOT).

For more information about SCIM syntax and operators, see Conventions.

Audit reporting API operations

The audit reporting service supports the following endpoint operations:

For hands-on experience with the audit reporting API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Audit reporting data model

Property Description
action.description A string that specifies the description of the action performed.
action.type A string that specifies the type of action performed (such as authentication or password reset).
actors.user.id A string that specifies the ID of the actor.
actors.user.name A string that specifies the name assigned to the user for PingOne sign on.
actors.population.id A string that specifies the ID of the population resource associated with the user.
actor.type A string that specifies the type of Actor. Options are USER or CLIENT.
correlationId A string that specifies a PingOne identifier for multiple messages in a transaction.
id A string that specifies the ID of the audit activity event.
recordedAt The date and time at which the event was recorded (ISO 8601 format).
resources.id A string that specifies the ID assigned as the key for the identifier resource (such as the environment, population or event message).
resources.name A string that can be either the user name or the name of the environment, based on the resource type.
resources.type A string that specifies the type of resource associated with the event. Options are USER, ORGANIZATION, or ENVIRONMENT.
resources.population.id The UUID assigned as the key for the population resource.
result.description A string that specifies the description of the result of the operation.
result.reason A string that specifies the reason for the result of the operation.
result.status A string that specifies the result of the operation. Options are succeeded or failed.
source.id The UUID of the originating source (such as a user agent).
source.ipAddress The IP address of the originating source.
source.type A string that specifies the type of Actor. Options are USER or (originating source).

Response codes

Code Message
200 Successful operation.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get audit activities for an environment

You can get all audit activity events for a selected environment. The GET /environments/{id}/activities request must specify a SCIM filtering expression that designates a time range for the result data.

The following sample shows the GET /environments/{id}/activities?filter=recordedat gt "2018-08-20T00:00:00Z" AND recordedat lt "2018-08-22T23:59:00Z" operation to return all audit activity events for the specified environment. The filtering expression designates a time period between 08/20/2018 and 08/22/2018.

curl -vX GET "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/activities?filter=recordedat%20gt%20%222018-08-20T00:00:00Z%22%20AND%20recordedat%20lt%20%222018-08-22T23:59:00Z" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data for the audit-activities event list looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/activities?filter=recordedat%20gt%20%222018-08-20T00:00:00Z%22%20AND%20recordedat%20lt%20%222018-08-22T23:59:00Z"
        }
    },
    "_embedded": {
        "activities": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/activities/a4a0a8c0-2d47-4efe-a8a5-463684f79f1c"
                    }
                },
                "id": "a4a0a8c0-2d47-4efe-a8a5-463684f79f1c",
                "recordedAt": "2018-08-22T21:47:12.859Z",
                "correlationId": "B2C30206-9EE5-42DE-8B98-D8D3E4913F80",
                "actors": {
                    "client": {
                        "id": "common-services-test",
                        "name": "common-services-test",
                        "type": "CLIENT"
                    }
                },
                "action": {
                    "type": "APPLICATION.DELETED",
                    "description": "Application Deleted"
                },
                "resources": [
                    {
                        "type": "APPLICATION",
                        "id": "60420de9-9d38-44c5-a2a7-4839ded541f0",
                        "name": "UPDATED_1534974432",
                        "environment": {
                            "id": "000c2764-3489-4d34-a707-b23dd488049c"
                        },
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/applications/60420de9-9d38-44c5-a2a7-4839ded541f0"
                    }
                ],
                "result": {
                    "status": "SUCCESS",
                    "description": "Deleted Application UPDATED_1534974432 of type 'SERVICE' with disabled state"
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/activities/deee0af7-655f-48cf-ae2e-7571fdfe5ac6"
                    }
                },
                "id": "deee0af7-655f-48cf-ae2e-7571fdfe5ac6",
                "recordedAt": "2018-08-22T21:47:12.005Z",
                "correlationId": "68E80AD8-C9D4-4DB8-93A9-6FF4C88D1E2B",
                "actors": {
                    "client": {
                        "id": "common-services-test",
                        "name": "common-services-test",
                        "type": "CLIENT"
                    }
                },
                "action": {
                    "type": "APPLICATION.UPDATED",
                    "description": "Application Updated"
                },
                "resources": [
                    {
                        "type": "APPLICATION",
                        "id": "60420de9-9d38-44c5-a2a7-4839ded541f0",
                        "name": "UPDATED_1534974432",
                        "environment": {
                            "id": "000c2764-3489-4d34-a707-b23dd488049c"
                        },
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/applications/60420de9-9d38-44c5-a2a7-4839ded541f0"
                    }
                ],
                "result": {
                    "status": "SUCCESS",
                    "description": "Updated Application UPDATED_1534974432 of type 'SERVICE' with disabled state"
                }
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/activities/ddc7214e-23a1-401d-be06-ea70a3479be8"
                    }
                },
                "id": "ddc7214e-23a1-401d-be06-ea70a3479be8",
                "recordedAt": "2018-08-22T21:47:11.404Z",
                "correlationId": "3678B778-2DE3-4AB4-BA25-38529D3CE1AF",
                "actors": {
                    "client": {
                        "id": "common-services-test",
                        "name": "common-services-test",
                        "type": "CLIENT"
                    }
                },
                "action": {
                    "type": "APPLICATION.CREATED",
                    "description": "Application Created"
                },
                "resources": [
                    {
                        "type": "APPLICATION",
                        "id": "60420de9-9d38-44c5-a2a7-4839ded541f0",
                        "name": "app_1534974431",
                        "environment": {
                            "id": "000c2764-3489-4d34-a707-b23dd488049c"
                        },
                        "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/applications/60420de9-9d38-44c5-a2a7-4839ded541f0"
                    }
                ],
                "result": {
                    "status": "SUCCESS",
                    "description": "Created Application app_1534974431 of type 'SERVICE' with enabled state"
                  }
              }
         ]
    }
}

Get one audit activity

You can get data for one audit activity by specifying the audit activity ID. The GET /environments/{id}/activities/{activityId} request returns information associated with the specified audit activity. You must specify a SCIM filtering expression that designates a time range for the result data.

curl -vX GET "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/activities/{activityId}?filter=recordedat%20gt%20%222018-08-20T00:00:00Z%22%20AND%20recordedat%20lt%20%222018-08-22T23:59:00Z" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/activities/a4a0a8c0-2d47-4efe-a8a5-463684f79f1c"
        }
    },
    "id": "a4a0a8c0-2d47-4efe-a8a5-463684f79f1c",
    "recordedAt": "2018-08-22T21:47:12.859Z",
    "correlationId": "B2C30206-9EE5-42DE-8B98-D8D3E4913F80",
    "actors": {
        "client": {
            "id": "common-services-test",
            "name": "common-services-test",
            "type": "CLIENT"
        }
    },
    "action": {
        "type": "APPLICATION.DELETED",
        "description": "Application Deleted"
    },
    "resources": [
        {
            "type": "APPLICATION",
            "id": "60420de9-9d38-44c5-a2a7-4839ded541f0",
            "name": "UPDATED_1534974432",
            "environment": {
                "id": "000c2764-3489-4d34-a707-b23dd488049c"
            },
            "href": "https://api.pingone.com/v1/environments/000c2764-3489-4d34-a707-b23dd488049c/applications/60420de9-9d38-44c5-a2a7-4839ded541f0"
        }
    ],
    "result": {
        "status": "SUCCESS",
        "description": "Deleted Application UPDATED_1534974432 of type 'SERVICE' with disabled state"
    }
}