Skip to content

Commit d396e3d

Browse files
ranbelmarciocloudflare
ranbel
and
marciocloudflare
authored
[ZT] Generic s2s (#16698)
* create add-service-provider partial * update UI * update posture check steps * add new service provider page * link to device posture policy info * update tutorials layout * create new tutorial placeholder * access jwt verification * remove Worker references * clarify test button * fix front matter * fix score * Update src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx Co-authored-by: marciocloudflare <[email protected]> * Update src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx Co-authored-by: marciocloudflare <[email protected]> * Update src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx Co-authored-by: marciocloudflare <[email protected]> * Update src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx Co-authored-by: marciocloudflare <[email protected]> * link to Workers example * update partial frontmatter --------- Co-authored-by: marciocloudflare <[email protected]>
1 parent 8a882d0 commit d396e3d

File tree

13 files changed

+157
-35
lines changed

13 files changed

+157
-35
lines changed

‎src/content/docs/cloudflare-one/identity/devices/service-providers/crowdstrike.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,10 +51,7 @@ To retrieve those values:
5151

5252
### 2. Add CrowdStrike as a service provider
5353

54-
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **WARP Client**.
55-
2. Scroll down to **Device posture providers** and select **Add new**.
56-
3. Select **CrowdStrike**.
57-
4. Enter any name for the provider. This name will be used throughout the dashboard to reference this connection.
54+
<Render file="posture/add-service-provider" params={{ provider: "Crowdstrike" }} />
5855
5. Enter the **Client ID** and **Client secret** you noted down above.
5956
6. Enter your **Rest API URL**.
6057
7. Enter your **Customer ID**.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/custom.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Custom device posture integration
4+
sidebar:
5+
label: Custom integration
6+
order: 1
7+
hidden: true
8+
9+
---
10+
11+
import { Render } from "~/components"
12+
13+
Cloudflare Zero Trust allows you to enforce custom device posture checks on your applications. This involves configuring a WARP service-to-service integration that periodially 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`.
14+
15+
```mermaid
16+
sequenceDiagram
17+
participant WARP
18+
participant Cloudflare Access
19+
participant External API
20+
WARP->>Cloudflare Access: Client ID and Secret
21+
Cloudflare Access->>External API: Application token
22+
WARP->>External API: JSON with user and device identity
23+
External API-->>WARP: JSON with 0-100 result
24+
```
25+
26+
## External API requirements
27+
28+
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).
29+
30+
### Authentication
31+
32+
The WARP client authenticates to the external API through Cloudflare Access. The external API should [validate the application token](/cloudflare-one/identity/authorization-cookie/validating-json/) issued by Cloudflare Access to ensure that any requests which bypass Access (for example, due to a network misconfiguration) are rejected.
33+
34+
### Data passed to external API
35+
36+
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.
37+
38+
| Field | Description |
39+
| ----- | ----------- |
40+
| `device_id` | Device UUID assigned by the WARP client |
41+
| `email` | Email address used to authenticate the WARP client |
42+
| `serial_number` | Device serial number |
43+
| `mac_address` | Device MAC address |
44+
| `virtual_ipv4` | Device virtual IPv4 address |
45+
| `hostname` | Device name |
46+
47+
Example request body:
48+
```json
49+
{
50+
"devices": {
51+
[
52+
{
53+
"device_id": "9ece5fab-7398-488a-a575-e25a9a3dec07",
54+
"email": "[email protected]",
55+
"serial_number": "jdR44P3d",
56+
"mac_address": "74:1d:3e:23:e0:fe",
57+
"virtual_ipv4": "100.96.0.10",
58+
"hostname": "string",
59+
},
60+
{...},
61+
{...}
62+
]
63+
}
64+
}
65+
```
66+
67+
### Expected response from external API
68+
69+
For each Cloudflare `device_id`, the API service is expected to return a posture score and optionally a third-party device ID.
70+
71+
| Field | Description |
72+
| ----- | ----------- |
73+
| `s2s_id` | Third party device ID (empty string if unavailable) |
74+
| `score` | Integer value between `0` - `100` |
75+
76+
Example response body:
77+
```json
78+
{
79+
"result": {
80+
"9ece5fab-7398-488a-a575-e25a9a3dec07": {
81+
"s2s_id": "",
82+
"score": 10
83+
},
84+
"device_id2": {...},
85+
"device_id3": {...}
86+
}
87+
}
88+
```
89+
90+
## Set up custom device posture checks
91+
92+
### 1. Create a service token
93+
94+
WARP uses an Access Client ID and Access Client Secret to securely authenticate to the external API. If you do not already have an Access Client ID and Access Client Secret, [create a new service token](/cloudflare-one/identity/service-tokens/#create-a-service-token).
95+
96+
### 2. Create an Access application
97+
98+
Next, secure the external API behind Cloudflare Access so that WARP can authenticate with the service token. To add the API endpoint to Access:
99+
100+
1. [Create a self-hosted application](/cloudflare-one/applications/configure-apps/self-hosted-apps/) for your API endpoint.
101+
2. Add the following Access policy to the application. Make sure that **Action** is set to _Service Auth_ (not _Allow_).
102+
103+
| Action | Rule type | Selector | Value |
104+
| ------ | --------- | ----------------- | ------------------------------------- |
105+
| Service Auth | Include | Service Token | `<TOKEN-NAME>` |
106+
107+
### 3. Add a service provider integration
108+
109+
To create a custom service-to-service integration:
110+
111+
<Render file="posture/add-service-provider" params={{ provider: "Custom service provider" }} />
112+
5. In **Access client ID** and **Access client secret**, enter the Access service token used to authenticate to your external API.
113+
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).
114+
7. In **Polling frequency**, choose how often Cloudflare Zero Trust should query the external API for information.
115+
8. Select **Test and save**. The test checks if Cloudflare can authenticate to the API URL using the provided Access credentials.
116+
117+
Next, [configure a device posture check](#configure-the-posture-check) to determine if a given posture score constitutes a pass or fail.
118+
119+
### 4. Configure the posture check
120+
121+
<Render file="posture/configure-posture-check" params={{ one: "Custom service provider" }} />
122+
123+
## Device posture attributes
124+
125+
| Selector | Description | Value |
126+
| ------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
127+
| Score | Posture score returned by external API | `0` to `100` |

‎src/content/docs/cloudflare-one/identity/devices/service-providers/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Service-to-service integrations allow the WARP client to get device posture data
1818

1919
| Device posture check | macOS | Windows | Linux | iOS | Android/ChromeOS |
2020
| ------------------------------------------------------------------------------------------- | ----- | ------- | ----- | --- | ---------------- |
21+
| [Custom service provider](/cloudflare-one/identity/devices/service-providers/custom/) | ✅ | ✅ | ✅ | ✅ | ✅ |
2122
| [Crowdstrike](/cloudflare-one/identity/devices/service-providers/crowdstrike/) | ✅ | ✅ | ✅ | ❌ | ❌ |
2223
| [Kolide](/cloudflare-one/identity/devices/service-providers/kolide/) | ✅ | ✅ | ✅ | ❌ | ❌ |
2324
| [Microsoft Endpoint Manager](/cloudflare-one/identity/devices/service-providers/microsoft/) | ✅ | ✅ | ❌ | ❌ | ❌ |

‎src/content/docs/cloudflare-one/identity/devices/service-providers/kolide.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,7 @@ import { Render } from "~/components"
2727

2828
### 2. Add Kolide as a service provider
2929

30-
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **WARP Client**.
31-
2. Scroll down to **Device posture providers** and select **Add new**.
32-
3. Select **Kolide**.
33-
4. Enter any name for the provider. This name will be used throughout the dashboard to reference this connection.
30+
<Render file="posture/add-service-provider" params={{ provider: "Kolide" }} />
3431
5. Enter the **Client secret** you noted down above.
3532
6. Choose a **Polling frequency** for how often Cloudflare Zero Trust should query Kolide for information.
3633
7. Select **Save**.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/microsoft.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,7 @@ To retrieve those values:
4343

4444
## 2. Add Intune as a service provider
4545

46-
1. Go to **Settings** > **WARP Client**.
47-
2. Scroll down to **Device posture providers** and select **Add new**.
48-
3. Select **Microsoft Endpoint Manager**.
49-
4. Give your provider a name. This name will be used throughout the dashboard to reference this connection.
46+
<Render file="posture/add-service-provider" params={{ provider: "Microsoft Endpoint Manager" }} />
5047
5. Enter the **Client ID**, **Client secret** and **Customer ID** as you noted down above.
5148
6. Select a **Polling frequency** for how often Cloudflare Zero Trust should query Microsoft Graph API for information.
5249
7. Select **Save**.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/sentinelone.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,7 @@ To retrieve those values:
4141

4242
### 2. Add SentinelOne as a service provider
4343

44-
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **WARP Client**.
45-
2. Scroll down to **Device posture providers** and select **Add new**.
46-
3. Select **SentinelOne**.
47-
4. Enter any name for the provider. This name will be used throughout the dashboard to reference this connection.
44+
<Render file="posture/add-service-provider" params={{ provider: "SentinelOne" }} />
4845
5. In **Client Secret**, enter your **API Token**.
4946
6. In **Rest API URL**, enter `https://<S1-DOMAIN>.sentinelone.net`.
5047
7. Choose a **Polling frequency** for how often Cloudflare Zero Trust should query SentinelOne for information.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/taniums2s.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,7 @@ To retrieve those values:
4040

4141
### 2. Add Tanium as a service provider
4242

43-
1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Settings** > **WARP Client**.
44-
2. Scroll down to **Device posture providers** and select **Add new**.
45-
3. Select **Tanium**.
46-
4. Enter any name for the provider. This name will be used throughout the dashboard to reference this connection.
43+
<Render file="posture/add-service-provider" params={{ provider: "Tanium" }} />
4744
5. Enter the **Client Secret** and **Rest API URL** you noted down above.
4845
6. Choose a **Polling frequency** for how often Cloudflare Zero Trust should query Tanium for information.
4946
7. Select **Save**.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/uptycs.mdx‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,7 @@ To obtain these values:
3131

3232
## 2. Add Uptycs as a service provider
3333

34-
1. Go to **Settings** > **WARP Client**.
35-
2. Scroll down to **Device posture providers** and select **Add new**.
36-
3. Select **Uptycs**.
37-
4. Give your provider a name. This name will be used throughout the dashboard to reference this connection.
34+
<Render file="posture/add-service-provider" params={{ provider: "Uptycs" }} />
3835
5. Enter the **Client ID**, **Client secret** and **Customer ID** as you noted down above.
3936
6. Select a **Polling frequency** for how often Cloudflare Zero Trust should query Uptycs for information.
4037
7. Select **Save**.

‎src/content/docs/cloudflare-one/identity/devices/service-providers/workspace-one.mdx‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,11 @@ To retrieve those values:
4040

4141
## 2. Add Workspace ONE as a service provider
4242

43-
1. Go to **Settings** > **Devices** > **Device posture providers** and select **Add new**.
44-
2. Select **Workspace ONE**.
45-
3. Give your provider a name. This name will be used throughout the dashboard to reference this connection.
46-
4. Enter the **Client ID** and **Client secret** you noted down above.
47-
5. Select a **Polling frequency** for how often Cloudflare Zero Trust should query Workspace ONE for information.
48-
6. Enter the **Region-specific token URL** and **REST API URL** you noted down above.
49-
7. Select **Save**.
43+
<Render file="posture/add-service-provider" params={{ provider: "Workspace ONE" }} />
44+
5. Enter the **Client ID** and **Client secret** you noted down above.
45+
6. Select a **Polling frequency** for how often Cloudflare Zero Trust should query Workspace ONE for information.
46+
7. Enter the **Region-specific token URL** and **REST API URL** you noted down above.
47+
8. Select **Save**.
5048

5149
<Render file="posture/test-posture-provider" />
5250

‎src/content/docs/cloudflare-one/tutorials/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ column_param: category
88
sidebar:
99
order: 11
1010
head: []
11+
tableOfContents: false
1112
description: View tutorials for Cloudflare Zero Trust.
1213

1314
---

0 commit comments

Comments
 (0)