Subscriptions

PingOne SSO for SaaS Apps audit events are available through a subscription facility.

The subscriptions can be either:

A Push type, where PingOne for Enterprise streams audit events to an external service in real time.
A Poll type, where your client retrieves audit events as needed in configurable blocks of records, until all retrievable records are consumed.

Audit events that occurred prior to a subscription being created are not delivered. Only audit events occurring after the subscription is created are delivered.

However, if you create another subscription of the same type, you will have access to events that occurred prior to that subscription, because those events were already being tracked.

Each audit event for a subscription is retained for seven days. After that time, if you haven’t already received or retrieved the audit event record, it will not be available.

PingOne attempts to deliver an audit event message for both types of subscriptions. You might receive duplicate messages because of streaming retries or very frequent polling. Each audit event message includes a unique id, so you can easily identify duplicate messages.

Push subscriptions

Push subscriptions push events to the target server in real time.

The audit events matching the subscription are streamed to the HTTPS endpoint configured for the subscription.

The uploaded certificate must match what an external client would see when accessing the configured URL. Be aware of load balancers or other network devices that might present a different certificate.

The audit event information can be returned in either the PingOne audit format or a include::ROOT:partial$p14e_p1refs_splunk.adoc[tags=Splunk]-compatible format. Both formats are JSON.

If the delivery of a Push audit event fails, PingOne will continue to retry delivery. The interval period between retries will increase to a maximum of 15 minutes. PingOne for Enterprise will retry to deliver for 7 days and then discard the event.

If events aren’t arriving as expected, check the reports at Dashboard → Reporting → Run New Report. Choose Log Subscription as the type and check for errors. For example, certificate-related exceptions indicate that the certificate being presented does not match the certificate on file in PingOne for Enterprise.

For more information, see Adding a Push subscription

Poll subscriptions

Poll subscription audit events are accumulated and made available to you. You must use a script or client to retrieve the audit events. The client can retrieve the events, up to the configured batch size specified for the subscription.

Poll subscription audit events are collected and returned once per subscription. This means that each poll retrieval will have a different result set.

The audit event information is returned in the PingOne audit format.

An easy way to retrieve the audit events for a poll subscription is to use cURL. For instructions on how to create a cURL command, see Get the audit events for a Poll subscription.

Estimate how much traffic you expect to generate and set your poll rate and batch size accordingly. Leave some extra room in your batch size, because some transactions can generate multiple events. For example, if you have 1000 users authenticating per hour, it will generate from 1000 to 3000 events. For this traffic level, you can set a batch size of 1000 and poll every 20 minutes, or a batch of 200 and poll every four minutes. You should poll at least hourly, even with lower usage.

The number of audit events accumulated may be less than the batch size. The configured batch size is an upper limit, not a consistent number of returned events.

A poll request with zero results means that you are caught up to the present and there are no new events. Your poll rate should be set so that this happens regularly.

Polling events are returned in roughly chronological order from oldest to newest. To ensure strict chronological order, set your client to sort events by timestamp.

Events are stored for 7 days and then discarded. You must ensure that your client doesn’t fall more than 7 days behind, or you will lose data.

If you do fall behind and events begin to backlog, batch size and sorting can become less consistent. For example, if your batch size is 1000 and you fall a week behind in polling, you might get responses with 600-700 events, with older events grouped in with new ones. This doesn’t mean that events are missing. All events are available and will be returned as your collector catches up. But they won’t be in consistent order.

For more information, see Add a Poll subscription.

Choosing Push or Poll

Poll subscriptions give the client control over the rate at which events are collected and saved to your storage system, but the client is responsible for ensuring it doesn’t fall behind.

Push subscriptions are not batched, and therefore generate more traffic because they generate one request per event. Your target system must be able to handle the traffic load.

We generally recommend Push subscriptions because they are simpler, especially if you have large amounts of traffic (in the tens of thousands of events per hour), which can make it difficult to determine the right poll frequency.