Skip to content

Commit 7b8de16

Browse files
ranbelranbel
committed
add new service provider page
1 parent d90d6ee commit 7b8de16

File tree

2 files changed

+120
-0
lines changed

2 files changed

+120
-0
lines changed

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

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

0 commit comments

Comments
 (0)