Cloudflare Zero Trust Integration via API

Purpose

This guide explains how to generate the required API Token and permissions in Cloudflare Zero Trust, and how to use those credentials in Logsign USO to collect Zero Trust logs for security analytics and forensic investigations.

The Cloudflare Zero Trust source can collect the following log types. You choose them on the source form in Logsign USO.

• Cloudflare Access Logs: Access login events (allowed and denied), from the Access access_requests REST endpoint. Enabled by default.
• Cloudflare Gateway Network Logs: Gateway network (L4) sessions, from the GraphQL Analytics dataset gatewayL4SessionsAdaptiveGroups.
• Cloudflare Gateway DNS Logs: Gateway DNS queries, from the GraphQL Analytics dataset gatewayResolverQueriesAdaptiveGroups.
• Cloudflare Gateway DNS Logs (with user identity): Gateway DNS queries with the user e-mail, device and source IP, from the GraphQL Analytics dataset cf1GatewayDnsRawGroups.
• Cloudflare Gateway HTTP Logs: Gateway HTTP requests, from the GraphQL Analytics dataset gatewayL7RequestsAdaptiveGroups.
• Cloudflare WARP Device Status: WARP device connect and disconnect events, from the GraphQL Analytics dataset warpDeviceAdaptiveGroups.

Sources that existed before these log types were added keep collecting Access logs only, from their saved position. To collect the other log types, edit the source and select them.

1. Log in to Cloudflare Dashboard

Visit: https://dash.cloudflare.com

Log in with your Global Administrator or Zero Trust account owner credentials.

Ensure that your Cloudflare plan includes Zero Trust features.

2. Create a Custom API Token

In the Cloudflare dashboard, click your profile icon in the top-right corner and select “My Profile”.

Navigate to the “API Tokens” tab.

Click “Create Custom Token”.

Enter a meaningful name for the token, for example:

Token Name: ZeroTrustAPI-forLogsign

Configure Token Permissions

Add the following permissions exactly as listed below:

Account → Access: Audit Logs → Read

Account → Zero Trust → Read

Account → Access: Organizations, Identity Providers, and Groups → Read

Account → Account Analytics → Read

Account → Cloudflare DEX → Read

Access: Audit Logs is used for the Access login events. Account Analytics is required for the Gateway Network, Gateway DNS, Gateway DNS (with user identity), Gateway HTTP and WARP Device Status log types, because Logsign reads them from the Cloudflare GraphQL Analytics API. If the token does not have Account Analytics, those log types are not collected, while Access logs continue to work.

Zero Trust: Read lets Logsign read Gateway rules and registered devices. Cloudflare DEX: Read lets Logsign read the DEX fleet status of WARP devices. Logsign uses this data to add the rule or policy name, device name, user e-mail and IP addresses to the events (see "Event enrichment" below).

Optionally, add Zero Trust: PII Read. Without this permission, Cloudflare replaces the user e-mail, user ID, device ID and IP addresses in Gateway logs with the text REDACTED. Logsign does not write these placeholder values to the normalized fields. Instead, the raw field redactedFields lists the fields that Cloudflare hid. If you need user and device identity in Gateway events, add Zero Trust: PII Read to the token.

These permissions allow Logsign to collect audit trail and Zero Trust event data safely, without edit or administrative privileges.

Save and Record the Following Details

After creating the token, copy and store the following information securely:

API Token: The generated Bearer token (visible only once).

Account ID: Found in the Cloudflare dashboard URL, for example
https://dash.cloudflare.com/xxxxxxxxxxxxxx/

Cloudflare only shows the token value once, so make sure to save it securely in a vault or password manager.

Configure Integration in Logsign USO

Log in to your Logsign USO instance.

Go to Data Sources → Add New → API → Cloudflare Zero Trust.

Enter the following fields:

API Token: Paste the token you created. The tooltip of this field lists the required token permissions.

Account ID: Enter your Cloudflare account identifier. A Zone ID is not needed, all data is collected at account level.

Verify SSL: Leave it enabled unless your network inspects TLS traffic with its own certificate.

Log types: Select the log types to collect. "Cloudflare Access Logs" is selected by default. "Cloudflare Gateway Network Logs", "Cloudflare Gateway DNS Logs", "Cloudflare Gateway DNS Logs (with user identity)", "Cloudflare Gateway HTTP Logs" and "Cloudflare WARP Device Status" are optional. At least one log type must be selected, otherwise the source collects nothing.

Source Name: For example, “Cloudflare Zero Trust Logs”.

How the Log Types Are Collected

Each log type keeps its own position, so a problem with one log type (for example a missing token permission) does not stop the others. Logsign reads events up to 3 minutes behind the current time, because Cloudflare analytics data reaches the API with a short delay. The event time (Time.Generated) is taken from the Cloudflare event itself.

Gateway Network, Gateway DNS, Gateway HTTP and WARP Device Status data comes from Cloudflare's adaptive (sampled) analytics datasets. Under heavy load some events can be missing. Cloudflare keeps this data for about 30 days, so a new source cannot read older events. If a single second contains more than 10,000 rows, Logsign skips the excess and writes a warning to the poller log.

Gateway Network and Gateway HTTP logs exist only when the Cloudflare Gateway proxy is enabled for your WARP clients. The "Cloudflare Gateway DNS Logs" log type does not contain user or device information, because Cloudflare does not provide these fields in that dataset. Use "Cloudflare Gateway DNS Logs (with user identity)" if you need them.

"Cloudflare Gateway DNS Logs (with user identity)" sends one event per DNS query, or per group of identical queries in the same second. The number of queries in the event is in the raw field queries. This dataset carries the user e-mail, device ID and source IP, but not the resolved IPs or category names. If you need resolved IPs and category names, keep "Cloudflare Gateway DNS Logs" enabled as well. Cloudflare rejects a query on this dataset that covers more than 3 hours. For this reason Logsign reads at most 3 hours per poll, and a source that is further behind catches up one 3-hour span per poll.

For both DNS log types, the DNS decision of Cloudflare (for example allowedOnNoPolicyMatch or blockedByCategory) is written to Event.Action. A decision code that Cloudflare does not document stays only in the raw field resolverDecision.

Cloudflare reports the WARP status of each device about every 2 minutes. Logsign sends an event only when the status of a device changes (for example from connected to disconnected), so very short connections may not appear.

Event Enrichment

Logsign adds context to the events with the following lookups. The results are cached for 15 minutes. If a lookup fails, the events are still sent without the extra fields.

The device IP and ISP IP of WARP events are the last values that Cloudflare saw for the device, not the values at the event time. If your Cloudflare account hides the ISP IP, Source.IP stays empty on WARP events. The public IP of the user is still visible in Source.IP of Gateway Network and Access events, unless the token lacks Zero Trust: PII Read.

For Gateway DNS (with user identity), the main fields are mapped as follows: queried name to DNS.Query, source IP to Source.IP, user e-mail to Source.Mail, device ID to Device.ID, protocol to Protocol.Name, application names to Application.Name, country to Source.Country and policy ID to Policy.ID.

Event Mapping

WARP connect and disconnect events use the VPN login and logout EventMap. If you already have an alert rule on VPN user login (for example "EventMap.ID IS 50101"), it also fires for every WARP connection after you enable the WARP Device Status log type. Add an exception to the rule if you do not want this.

Troubleshooting