Skip to content

[CF1] add details on serial numbers in posture checks #22790

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 4, 2025
Merged

[CF1] add details on serial numbers in posture checks #22790

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
33ce192
[CF1] add details on serial numbers in posture checks
deadlypants1973 May 30, 2025
f2f3a2f
edits
deadlypants1973 May 30, 2025
d2c8ed8
sentinelone edit
deadlypants1973 May 30, 2025
fbde87f
Update src/content/partials/cloudflare-one/posture/service-provider-i…
deadlypants1973 Jun 4, 2025
3bb1562
Apply suggestions from code review
deadlypants1973 Jun 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 44 additions & 25 deletions src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,9 @@ sidebar:
order: 1

description: Configure custom device posture checks in Cloudflare Zero Trust using a service-to-service integration.

---

import { Render } from "~/components"
import { Render } from "~/components";

Cloudflare Zero Trust allows you to enforce custom device posture checks on your applications. This involves configuring a WARP service-to-service integration that periodically calls the external API of your choice, whether it is a third-party endpoint provider or a home built solution. When called, the API will receive device identifying information from Cloudflare and be expected to return a value between `0` to `100`. You can then set up a device posture check that determines if the returned value counts as a pass or fail; for example, you could allow access to a user only if their device has a posture value greater than `60`.

Expand All @@ -23,6 +22,7 @@ sequenceDiagram
WARP->>External API: JSON with user and device identity
External API-->>WARP: JSON with 0-100 result
```

## External API requirements

The custom service provider integration works with any API service that meets the following specifications. For an example of a custom device posture integration API, refer to our [Cloudflare Workers sample code](https://github.com/cloudflare/custom-device-posture-integration-example-worker).
Expand All @@ -35,16 +35,23 @@ The WARP client authenticates to the external API through Cloudflare Access. The

Cloudflare will pass the following parameters to the configured API endpoint. You can use this data to identify the device and assign a posture score. For some devices, not all identifying information will apply, in which case the field will be blank. A maximum of 1,000 devices will be sent per a request.

| Field | Description |
| ----- | ----------- |
| `device_id` | Device UUID assigned by the WARP client |
| `email` | Email address used to authenticate the WARP client |
| `serial_number` | Device serial number |
| `mac_address` | Device MAC address |
| `virtual_ipv4` | Device virtual IPv4 address |
| `hostname` | Device name |
| Field | Description |
| --------------- | -------------------------------------------------- |
| `device_id` | Device UUID assigned by the WARP client |
| `email` | Email address used to authenticate the WARP client |
| `serial_number` | Device serial number |
| `mac_address` | Device MAC address |
| `virtual_ipv4` | Device virtual IPv4 address |
| `hostname` | Device name |

:::note

Devices are identified by their serial numbers. You must ensure that each of your devices has a unique serial number. If multiple devices have the same serial number, Cloudflare and your external API will not be able to accurately match them.
Copy link
Contributor Author

@deadlypants1973 deadlypants1973 May 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Justin Lu to review

Copy link

@jlu-cloudflare jlu-cloudflare Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps change it to third person to match the rest of the docs. possibly:
"Devices are identified by their serial numbers. It is essential to ensure that each device has a unique serial number. If multiple devices have the same serial number, it is not possible to accurately match a Cloudflare device with a third-party provider device."


:::

Example request body:

```json
{
"devices": {
Expand All @@ -68,12 +75,13 @@ Example request body:

For each Cloudflare `device_id`, the API service is expected to return a posture score and optionally a third-party device ID.

| Field | Description |
| ----- | ----------- |
| Field | Description |
| -------- | --------------------------------------------------- |
| `s2s_id` | Third party device ID (empty string if unavailable) |
| `score` | Integer value between `0` - `100` |
| `score` | Integer value between `0` - `100` |

Example response body:

```json
{
"result": {
Expand All @@ -100,28 +108,39 @@ Next, secure the external API behind Cloudflare Access so that WARP can authenti
1. [Create a self-hosted application](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) for your API endpoint.
2. Add the following Access policy to the application. Make sure that **Action** is set to _Service Auth_ (not _Allow_).

| Action | Rule type | Selector | Value |
| ------ | --------- | ----------------- | ------------------------------------- |
| Service Auth | Include | Service Token | `<TOKEN-NAME>` |
| Action | Rule type | Selector | Value |
| ------------ | --------- | ------------- | -------------- |
| Service Auth | Include | Service Token | `<TOKEN-NAME>` |

### 3. Add a service provider integration

To create a custom service-to-service integration:

<Render file="posture/add-service-provider" params={{ provider: "Custom service provider" }} />
5. In **Access client ID** and **Access client secret**, enter the Access service token used to authenticate to your external API.
6. In **Rest API URL**, enter the external API endpoint that Cloudflare will query for posture information (for example, `https://api.example.com`). For more information, refer to [External API requirements](#external-api-requirements).
7. In **Polling frequency**, choose how often Cloudflare Zero Trust should query the external API for information.
8. Select **Test and save**. The test checks if Cloudflare can authenticate to the API URL using the provided Access credentials.
<Render
file="posture/add-service-provider"
params={{ provider: "Custom service provider" }}
/>
5. In **Access client ID** and **Access client secret**, enter the Access
service token used to authenticate to your external API. 6. In **Rest API URL**,
enter the external API endpoint that Cloudflare will query for posture
information (for example, `https://api.example.com`). For more information,
refer to [External API requirements](#external-api-requirements). 7. In
**Polling frequency**, choose how often Cloudflare Zero Trust should query the
external API for information. 8. Select **Test and save**. The test checks if
Cloudflare can authenticate to the API URL using the provided Access
credentials.

Next, [configure a device posture check](#4-configure-the-posture-check) to determine if a given posture score constitutes a pass or fail.

### 4. Configure the posture check

<Render file="posture/configure-posture-check" params={{ one: "Custom service provider" }} />
<Render
file="posture/configure-posture-check"
params={{ one: "Custom service provider" }}
/>

## Device posture attributes

| Selector | Description | Value |
| ------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Score | Posture score returned by external API | `0` to `100` |
| Selector | Description | Value |
| -------- | -------------------------------------- | ------------ |
| Score | Posture score returned by external API | `0` to `100` |
40 changes: 24 additions & 16 deletions src/content/docs/cloudflare-one/identity/devices/service-providers/sentinelone.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,34 +6,39 @@ sidebar:
head:
- tag: title
content: SentinelOne - Posture checks

---

import { Render } from "~/components"
import { Render } from "~/components";

Cloudflare Zero Trust can integrate with SentinelOne to require that users connect to certain applications from managed devices. Our service-to-service posture check identifies devices based on their serial numbers.
Cloudflare Zero Trust can integrate with SentinelOne to require that users connect to certain applications from managed devices. Our service-to-service posture check identifies devices based on their serial numbers. If multiple devices have the same serial number, we cannot accurately match a Cloudflare device with a third-party provider device. You must ensure that each of your devices has a unique serial number.

## Prerequisites

* SentinelOne agent is deployed on the device.
* <Render file="posture/prereqs-warp-is-deployed" params={{ name: "Service providers", link: "/cloudflare-one/identity/devices/service-providers/" }} />
- SentinelOne agent is deployed on the device.
- <Render
file="posture/prereqs-warp-is-deployed"
params={{
name: "Service providers",
link: "/cloudflare-one/identity/devices/service-providers/",
}}
/>

## Set up SentinelOne as a service provider

### 1. Obtain SentinelOne settings

The following SentinelOne values are needed to set up the SentinelOne posture check:

* API Token
* REST API URL
- API Token
- REST API URL

To retrieve those values:

1. Log in to your SentinelOne Dashboard.
2. Go to **Settings** > **Users** > **Create new Service User**.
3. Select **Create New Service User**.
4. Enter a **Name** and **Expiration Date** and select **Next**.
5. Set **Scope of Access** to *Viewer*.
5. Set **Scope of Access** to _Viewer_.
6. Select **Create User**. SentinelOne will generate an API Token for this user.
7. Copy the **API Token** to a safe location.
8. Select **Close**.
Expand All @@ -49,19 +54,22 @@ To retrieve those values:

### 3. Configure the posture check

<Render file="posture/configure-posture-check" params={{ one: "SentinelOne" }} />
<Render
file="posture/configure-posture-check"
params={{ one: "SentinelOne" }}
/>

## Device posture attributes

Device posture data is gathered from the SentinelOne Management APIs. For more information, refer to `https://<S1-DOMAIN>.sentinelone.net/api-doc/overview`.

| Selector | Description |
| -------------- | --------------------------------------------------------------------- |
| Infected | Whether the device is infected |
| Active Threats | Number of active threats on the device |
| Is Active | Whether the SentinelOne Agent is active |
| Network status | Whether the SentinelOne Agent is connected to the SentinelOne service |
| Operational State | The [operational state](https://community.sentinelone.com/s/login/?ec=302&startURL=%2Fs%2Farticle%2F000005285) of the SentinelOne Agent.|
| Selector | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Infected | Whether the device is infected |
| Active Threats | Number of active threats on the device |
| Is Active | Whether the SentinelOne Agent is active |
| Network status | Whether the SentinelOne Agent is connected to the SentinelOne service |
| Operational State | The [operational state](https://community.sentinelone.com/s/login/?ec=302&startURL=%2Fs%2Farticle%2F000005285) of the SentinelOne Agent. |

### Detect user risk behavior

Expand Down
5 changes: 2 additions & 3 deletions src/content/partials/cloudflare-one/posture/service-provider-intro.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
---
inputParameters: param1

---

import { Markdown } from "~/components"
import { Markdown } from "~/components";

Cloudflare Zero Trust can integrate with {props.one} to require that users connect to certain applications from managed devices. This service-to-service posture check uses the WARP client to read endpoint data from {props.one}. Devices are identified by their serial numbers.
Cloudflare Zero Trust can integrate with {props.one} to require that users connect to certain applications from managed devices. This service-to-service posture check uses the WARP client to read endpoint data from {props.one}. Devices are identified by their serial numbers. If multiple devices have the same serial number, we cannot accurately match a Cloudflare device with a third-party provider device. You must ensure that each of your devices has a unique serial number.
Copy link
Contributor Author

@deadlypants1973 deadlypants1973 May 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Justin Lu to review

Copy link

@jlu-cloudflare jlu-cloudflare Jun 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The statement is accurate, but maybe it could be changed to 3rd person to match the rest of the docs. Something like:
"If multiple devices have the same serial number, it is not possible to accurately match a Cloudflare device with a third-party provider device. It is essential to ensure that each device has a unique serial number."

Loading