PingOne Advanced Identity Cloud

Manage log streaming using the API

Learn more about streaming PingOne Advanced Identity Cloud log events in Stream logs to an external monitoring tool.

Log-streaming service API endpoints

The log-streaming service provides these Advanced Identity Cloud API endpoints:

  • Telemetry API endpoint (/environment/telemetry)

    • Use GET to view the log-streaming service configuration. Note that you can only have one log-streaming service configuration in your tenant environment.

  • OTLP telemetry API endpoint (/environment/telemetry/otlp)

    • Use GET to view a specified OTLP log-streaming service configuration.

    • Use PUT to create or update an OTLP log-streaming service configuration.

    • Use DELETE to delete an OTLP log-streaming service configuration.

  • Splunk telemetry API endpoint (/environment/telemetry/splunk)

    • Use GET to view a specified Splunk log-streaming service configuration.

    • Use PUT to create or update a Splunk log-streaming service configuration.

    • Use DELETE to delete a Splunk log-streaming service configuration.

Authenticate to log-streaming service API endpoints

To authenticate to log-streaming service API endpoints, use an access token created with the following scope:

Scope Description

fr:idc:telemetry:*

Full access to log-streaming service API endpoints. Use this scope to view, create, update, or delete log-streaming services.

View the log-streaming service configuration

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Get the log-streaming service configuration from the /environment/telemetry endpoint:

    $ curl \
--request GET 'https://<tenant-env-fqdn>/environment/telemetry' \(1)
--header 'Authorization: Bearer <access-token>' \(2)
--header 'Content-Type: application/json'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <access-token> with the access token.

    The response shows the log-streaming service configuration:

    Show example response for an OTLP log-streaming service 
    {
  "otlp": [
    {
      "encoding": "PROTO", (1)
      "endpoint": "https://example-siem.com:4317", (2)
      "id": "mySIEM-otlp", (3)
      "sources": [ (4)
        "am-everything",
        "idm-everything"
      ],
      "type": "GRPC" (5)
    }
  ],
  "splunk": []
}
    1 The encoding format for telemetry data, either PROTO (Protocol Buffers, the default) or JSON.
    2 The destination URL for sending log event data.
    3 A unique identifier for the log-streaming service.
    4 The Advanced Identity Cloud log sources that are streamed.
    5 The streaming service protocol: GRPC for a gRPC-based monitoring tool or HTTP for Systems using JSON-based logs.
    Show example response for a Splunk log-streaming service 
    {
  "otlp": [],
  "splunk": [
    {
      "endpoint": "https://splunk:8088/services/collector/event", (1)
      "id": "mySIEM-splunk", (2)
      "sources": [ (3)
        "am-everything",
        "idm-everything"
      ]
    }
  ]
}
    1 The destination URL for sending log event data.
    2 A unique identifier for the log-streaming service.
    3 The Advanced Identity Cloud sources that are streamed.

Configure an OTLP log-streaming service

An Advanced Identity Cloud tenant environment can have only one log-streaming service configuration. You must delete the existing log-streaming service configuration before creating a new one.

To create or update an OTLP log-streaming service, send a PUT request to the /environment/telemetry/otlp endpoint.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Run the following command:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/otlp/<log-streaming-id>' \(1)(2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data '{
  "basicAuth": { (4)
    "username": "<username>",
    "password": "<password>"
  },
  "encoding": "<encoding-format>", (5)
  "endpoint": "<monitoring-tool-url>", (6)
  "headers": { (7)
      "api-key": "key"
  },
  "sources": [ (8)
    "am-activity",
    "idm-activity"
  ],
  "type": "<streaming-protocol>" (9)
}'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <log-streaming-id> with a unique identifier for your log-streaming service configuration (for example, mySIEM-otlp).
    3 Replace <access-token> with the access token.
    4 Replace <username> and <password> with the credentials for your external monitoring tool.
    5 Replace <encoding-format> with the encoding format for telemetry data, either PROTO (Protocol Buffers, the default) or JSON. Refer to your monitoring tool vendor’s documentation for details.
    6 Replace <monitoring-tool-url> with the destination URL for sending log event data. For gRPC, this is the host and port (for example, https://example-siem.com:4317). For HTTP, this is the full URL including the path (for example,https://example-siem.com:4318/v1/logs).
    7 (Optional) Define any headers to apply to all outgoing data (traces, metrics, and logs). Omit this section if not needed.
    8 Specify the log sources to stream as a JSON array of strings.
    9 The streaming service protocol: GRPC for a gRPC-based monitoring tool or HTTP for Systems using JSON-based logs. Refer to your monitoring tool vendor’s documentation for details.
    Show example configuration body 
    {
  "basicAuth": {
    "username": "admin",
    "password": "x6ghe*suj"
  },
  "encoding": "PROTO",
  "endpoint": "https://example-siem.com:4317",
  "headers": {
      "api-key": "key"
  },
  "sources": [
    "am-activity",
    "idm-activity"
  ],
  "type": "HTTP"
}
The log-streaming service starts streaming events after a few minutes. Even if credentials are rotated during this period, no logs are lost.

Example OTLP log-streaming service configuration requests

Learn more about configuring Grafana, Datadog, and New Relic in Set up a log-streaming service.

Grafana example configuration request 
$ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/otlp/0' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
  "basicAuth": {
    "username": "1134238",
    "password": "glc_eyJcvIjoiMTMxNDI1JrIjoicDlnMjloRWZ2NzE3SXR5WEFssaN3E3TTEzIiwibSI6eyJyIdjoicHJvZC11csy13ZXNs0LTAifX0="
  },
  "encoding": "PROTO",
  "endpoint": "https://otlp-gateway-example.grafana.net/v1/logs",
  "sources": [
    "am-activity",
    "idm-activity"
  ],
  "type": "HTTP"
}'
Datadog example configuration request 
$ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/otlp/datadog' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
  "headers": {
    "dd-api-key": "<DD_API_KEY>"
    },
  "encoding": "PROTO",
  "endpoint": "https://http-intake.logs.datadoghq.com/v1/logs",
  "sources": [
    "am-activity",
    "idm-activity"
  ],
  "type": "HTTP"
}'

Learn more about the Datadog endpoint in the Datadog documentation.

New Relic example configuration request 
$ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/otlp/newrelic' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--data '{
  "headers": {
    "api-key": "<LICENSE_KEY>"
    },
  "encoding": "PROTO",
  "endpoint": "https://otlp.example.net/v1/logs",
  "sources": [
    "am-activity",
    "idm-activity"
  ],
  "type": "HTTP"
}'

Learn more about the New Relic endpoint in the New Relic documentation.

Configure a Splunk log-streaming service

An Advanced Identity Cloud tenant environment can have only one log-streaming service configuration. You must delete the existing log-streaming service configuration before creating a new one.

To create or update a Splunk log-streaming service configuration, send a PUT request to the /environment/telemetry/splunk endpoint.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Run the following command:

    $ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/telemetry/splunk/<log-streaming-id>' \(1)(2)
--header 'Authorization: Bearer <access-token>' \(3)
--header 'Content-Type: application/json' \
--data '{
  "endpoint": "<monitoring-tool-url>", (4)
  "token": "<splunk-hec-token>", (5)
  "index": "<splunk-index>", (6)
  "sources": [ (7)
    "am-activity",
    "idm-activity"
  ]
}'
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <log-streaming-id> with a unique ID for your log-streaming service configuration, for example mySIEM-splunk.
    3 Replace <access-token> with the access token.
    4 Replace <monitoring-tool-url> with the Splunk destination URL for receiving log events.
    5 Replace <splunk-hec-token> with the HEC token, obtained when you set up HEC for Splunk.
    6 (Optional) Replace <index> with the name of the specific Splunk index you want to target. Omit this line if not needed.
    7 Specify the log sources to stream as a JSON array of strings.
    Show example configuration body 
    {
  "endpoint": "https://splunk.example.com:8088/services/collector/event",
  "token": "12345678-90ab-cdef-1234-567890abcdef",
  "index": "log-index",
  "sources": [
    "am-activity",
    "idm-activity"
  ]
}
The log-streaming service starts streaming events after a few minutes. Even if credentials are rotated during this period, no logs are lost.

Delete the log-streaming service configuration

You must delete a log-streaming service configuration before you can create a new one.

In your tenant environment:

  1. Get an access token created with the fr:idc:telemetry:* scope.

  2. Delete the log-streaming service configuration:

    $ curl \
--request DELETE 'https://<tenant-env-fqdn>/environment/telemetry/<telemetry-format>/<log-streaming-id>' \(1)(2)(3)
--header 'Authorization: Bearer <access-token>' \(4)
    1 Replace <tenant-env-fqdn> with the FQDN of your tenant environment.
    2 Replace <telemetry-format> with the telemetry format, either otlp or splunk.
    3 Replace <log-streaming-id> with the ID of the log-streaming service configuration.
    4 Replace <access-token> with the access token.