Skip to content

Commit 3ddd8f9

Browse files
ranbelranbel
authored
[ZT] Terraform device profiles (#22148)
* add default profile settings * default device profile * custom device profile * fix indentation * device profile selectors * link to idp group docs
1 parent 15c6b3b commit 3ddd8f9

File tree

10 files changed

+217
-59
lines changed

10 files changed

+217
-59
lines changed

‎src/content/docs/cloudflare-one/connections/connect-devices/warp/configure-warp/device-profiles.mdx‎

Lines changed: 131 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ sidebar:
55
order: 2
66
---
77

8-
import { Render, TabItem, Tabs } from "~/components";
8+
import { Render, TabItem, Tabs, APIRequest } from "~/components";
99

1010
<Render file="warp/device-profiles-intro" />
1111

@@ -32,34 +32,70 @@ Your profile will appear in the **Profile settings** list. You can rearrange the
3232

3333
<TabItem label="API">
3434

35-
Send a `POST` request to the [Devices endpoint](/api/resources/zero_trust/subresources/devices/subresources/policies/subresources/custom/methods/create/):
36-
37-
```bash
38-
curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/devices/policy \
39-
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
40-
--header "Content-Type: application/json" \
41-
--data '{
42-
"allow_mode_switch": false,
43-
"allow_updates": false,
44-
"allowed_to_leave": false,
45-
"auto_connect": 900,
46-
"captive_portal": 180,
47-
"description": "Cloudflare'\''s basic device settings profile, recommended in the implementation documentation. For details, refer to https://developers.cloudflare.com/learning-paths/replace-vpn/configure-device-agent/device-profiles/",
48-
"disable_auto_fallback": true,
49-
"enabled": true,
50-
"exclude_office_ips": false,
51-
"match": "identity.email == \"[email protected]\"",
52-
"name": "Cloudflare basic device profile",
53-
"precedence": 101,
54-
"service_mode_v2": {
55-
"mode": "warp"
56-
},
57-
"support_url": "https://it.company.com/help",
58-
"switch_locked": true
59-
}'
60-
```
35+
Send a `POST` request to the [Devices API](/api/resources/zero_trust/subresources/devices/subresources/policies/subresources/custom/methods/create/):
36+
37+
<APIRequest
38+
path="/accounts/{account_id}/devices/policy"
39+
method="POST"
40+
json={{
41+
"allow_mode_switch": false,
42+
"allow_updates": false,
43+
"allowed_to_leave": false,
44+
"auto_connect": 600,
45+
"captive_portal": 180,
46+
"description": "Example device profile recommended in the implementation documentation. For details, refer to https://developers.cloudflare.com/learning-paths/replace-vpn/configure-device-agent/device-profiles/",
47+
"disable_auto_fallback": true,
48+
"enabled": true,
49+
"exclude_office_ips": false,
50+
"match": "identity.email in {\"[email protected]\"} or any(identity.groups.name[*] in {\"developers\" \"admin\"}) and os.name == \"windows\"",
51+
"name": "Example device profile",
52+
"precedence": 101,
53+
"service_mode_v2": {
54+
"mode": "warp"
55+
},
56+
"support_url": "https://support.example.com",
57+
"switch_locked": true
58+
}}
59+
/>
6160

62-
</TabItem> </Tabs>
61+
</TabItem>
62+
<TabItem label="Terraform (v5)">
63+
64+
1. Add the following permission to your [`cloudflare_api_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token):
65+
- `Zero Trust Write`
66+
67+
2. Create a new profile using the [`cloudflare_zero_trust_device_custom_profile`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_custom_profile) resource:
68+
69+
```tf
70+
resource "cloudflare_zero_trust_device_custom_profile" "example" {
71+
account_id = var.cloudflare_account_id
72+
name = "Example device profile"
73+
description = "Example device profile recommended in the implementation documentation. For details, refer to https://developers.cloudflare.com/learning-paths/replace-vpn/configure-device-agent/device-profiles/"
74+
allow_mode_switch = false
75+
allow_updates = false
76+
allowed_to_leave = false
77+
auto_connect = 600
78+
captive_portal = 180
79+
disable_auto_fallback = true
80+
enabled = true
81+
exclude_office_ips = false
82+
precedence = 101
83+
service_mode_v2 = {mode = "warp"}
84+
support_url = "https://support.example.com"
85+
switch_locked = true
86+
tunnel_protocol = "wireguard"
87+
88+
match = trimspace(replace(<<-EOT
89+
identity.email in {"[email protected]"}
90+
or any(identity.groups.name[*] in {"developers" "admin"})
91+
and os.name == "windows"
92+
EOT
93+
, "\n", " "))
94+
}
95+
```
96+
97+
</TabItem>
98+
</Tabs>
6399

64100
## Edit profile settings
65101

@@ -94,20 +130,76 @@ Alternatively, if you do not have access to the CLI, you can use [DEX remote cap
94130

95131
## Selectors
96132

97-
| Selector | Description | WARP mode required |
98-
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
99-
| User email | Email address of a user <br /> `[email protected]` | Gateway with WARP |
100-
| User group emails | Email address of an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) <br /> `[email protected]` | Gateway with WARP |
101-
| User group IDs | ID of an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) <br /> `12jf495bhjd7893ml09o` | Gateway with WARP |
102-
| User group names | Name of an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) <br /> `developers` | Gateway with WARP |
103-
| Operating system | Operating system of the device <br /> `macOS` | Any mode |
104-
| Operating system version | [OS version](/cloudflare-one/identity/devices/warp-client-checks/os-version/#determine-the-os-version) specified in Semver format <br /> `1.2.0` | Any mode |
105-
| Managed network | [Network location](/cloudflare-one/connections/connect-devices/warp/configure-warp/managed-networks/) of the device | Any mode |
106-
| SAML Attributes | Attribute name and value from a [SAML IdP](/cloudflare-one/policies/gateway/identity-selectors/#generic-saml-idp) | Gateway with WARP |
107-
| Service Token | [Service token](/cloudflare-one/connections/connect-devices/warp/deployment/device-enrollment/#check-for-service-token) used to enroll the device | Any mode |
133+
You can configure device profiles to match against the following selectors, or criteria. Identity-based selectors are only available if the user [enrolled the device](/cloudflare-one/connections/connect-devices/warp/deployment/manual-deployment/) by logging in to an identity provider (IdP).
134+
135+
### User email
136+
137+
Apply a device profile based on the user's email.
138+
139+
<Render file="gateway/selectors/user-email" params={{ UIname: "User email" }}/>
140+
141+
### User group emails
142+
143+
Apply a device profile based on an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) email address of which the user is configured as a member in the IdP.
144+
145+
<Render file="gateway/selectors/user-group-email" params={{ UIname: "User group emails" }}/>
146+
147+
### User group IDs
148+
149+
Apply a device profile based on an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) ID of which the user is configured as a member in the IdP.
150+
151+
<Render file="gateway/selectors/user-group-ids" params={{ UIname: "User group IDs" }}/>
152+
153+
### User group names
154+
155+
Apply a device profile based on an [IdP group](/cloudflare-one/policies/gateway/identity-selectors/#idp-groups-in-gateway) name of which the user is configured as a member in the IdP.
156+
157+
<Render file="gateway/selectors/user-group-names" params={{ UIname: "User group names" }}/>
158+
159+
### Operating system
160+
161+
Apply a device profile based on the operating system of the device.
162+
163+
| UI name | API example |
164+
| --------------- | ------------------------------------------------- |
165+
| Operating system | `os.name in {\"windows\" \"mac\"}` |
166+
167+
### Operating system version
168+
169+
Apply a device profile based on the [OS version](/cloudflare-one/identity/devices/warp-client-checks/os-version/#determine-the-os-version) of the device.
170+
171+
| UI name | API example |
172+
| --------------- | ------------------------------------------------- |
173+
| Operating system version | `os.version == \"1.2.0\"` |
174+
175+
<Render file="warp/os-version-semver" />
176+
177+
### Managed network
178+
179+
Apply a device profile based on the [managed network](/cloudflare-one/connections/connect-devices/warp/configure-warp/managed-networks/) that the device is connected to.
180+
181+
| UI name | API example |
182+
| --------------- | ------------------------------------------------- |
183+
| Managed network | `network == \"Austin office\"` |
184+
185+
### SAML attributes
186+
187+
Apply a device profile based on an attribute name and value from a [SAML IdP](/cloudflare-one/policies/gateway/identity-selectors/#generic-saml-idp).
188+
189+
<Render file="gateway/selectors/saml-attributes" />
190+
191+
### Service token
192+
193+
Apply a device profile based on the [service token](/cloudflare-one/connections/connect-devices/warp/deployment/device-enrollment/#check-for-service-token) used to enroll the device.
194+
195+
| UI name | API example |
196+
| --------------- | ------------------------------------------------- |
197+
| Service Token | `identity.service_token_uuid == \"f174e90a-fafe-4643-bbbc-4a0ed4fc8415\"` |
108198

109199
## Comparison operators
110200

201+
Comparison operators determine how device profiles match a selector.
202+
111203
| Operator | Meaning |
112204
| -------- | ------------------------------------------ |
113205
| is | equals the defined value |

‎src/content/docs/cloudflare-one/identity/devices/warp-client-checks/os-version.mdx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,9 @@ The OS Version device posture attribute checks whether the version of a device's
2525
2. Scroll down to **WARP client checks** and select **Add new**.
2626
3. Select **OS version**.
2727
4. Configure the **Operating system**, **Operator**, and **Version** fields to specify the [OS version](#determine-the-os-version) you want devices to match.
28-
:::note
2928

30-
The OS version must be specified as a valid [Semver](https://semver.org/). For example, if your device is running OS version `1.2`, you must enter `1.2.0`.
31-
:::
29+
<Render file="warp/os-version-semver" />
30+
3231
5. (Optional) Configure additional OS-specific fields:
3332

3433
<Tabs> <TabItem label="macOS">

‎src/content/docs/cloudflare-one/policies/gateway/identity-selectors.mdx‎

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,41 +36,31 @@ Gateway will automatically detect changes in user name, title, and group members
3636

3737
Specify a value from the SAML Attribute Assertion.
3838

39-
| UI name | API example |
40-
| --------------- | ------------------------------------------------- |
41-
| SAML Attributes | `identity.saml_attributes == "\"group=finance\""` |
39+
<Render file="gateway/selectors/saml-attributes" />
4240

4341
### User Email
4442

4543
Use this selector to create identity-based Gateway rules based on a user's email.
4644

47-
| UI name | API example value |
48-
| ---------- | ------------------------------------------- |
49-
| User Email | `identity.email == "[email protected]"` |
45+
<Render file="gateway/selectors/user-email" params={{ UIname: "User Email" }}/>
5046

5147
### User Group IDs
5248

5349
Use this selector to create identity-based Gateway rules based on an IdP group ID of which the user is configured as a member in the IdP.
5450

55-
| UI name | API example |
56-
| -------------- | ---------------------------------------------- |
57-
| User Group IDs | `identity.groups.id == "12jf495bhjd7893ml09o"` |
51+
<Render file="gateway/selectors/user-group-ids" params={{ UIname: "User Group IDs" }}/>
5852

5953
### User Group Email
6054

6155
Use this selector to create identity-based Gateway rules based on an IdP group email address of which the user is configured as a member in the IdP.
6256

63-
| UI name | API example |
64-
| ---------------- | ------------------------------------------------- |
65-
| User Group Email | `identity.groups.id == "[email protected]"` |
57+
<Render file="gateway/selectors/user-group-email" params={{ UIname: "User Group Email" }}/>
6658

6759
### User Group Names
6860

6961
Use this selector to create identity-based Gateway rules based on an IdP group name of which the user is configured as a member in the IdP.
7062

71-
| UI name | API example |
72-
| ---------------- | --------------------------------------- |
73-
| User Group Names | `identity.groups.name == "\"finance\""` |
63+
<Render file="gateway/selectors/user-group-names" params={{ UIname: "User Group Names" }}/>
7464

7565
### User Name
7666

‎src/content/partials/cloudflare-one/gateway/selectors/saml-attributes.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
{}
3+
---
4+
5+
| UI name | API example |
6+
| --------------- | ------------------------------------------------- |
7+
| SAML Attributes | `identity.saml_attributes == "\"group=finance\""` |

‎src/content/partials/cloudflare-one/gateway/selectors/user-email.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
params:
3+
- UIname
4+
---
5+
6+
| UI name | API example value |
7+
| ---------- | ------------------------------------------- |
8+
| {props.UIname} | `identity.email == "[email protected]"` |

‎src/content/partials/cloudflare-one/gateway/selectors/user-group-email.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
params:
3+
- UIname
4+
---
5+
6+
| UI name | API example |
7+
| ---------------- | ------------------------------------------------- |
8+
| {props.UIname} | `identity.groups.email == "[email protected]"` |

‎src/content/partials/cloudflare-one/gateway/selectors/user-group-ids.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
params:
3+
- UIname
4+
---
5+
6+
| UI name | API example |
7+
| ---------------- | ------------------------------------------------- |
8+
| {props.UIname} | `identity.groups.id == "12jf495bhjd7893ml09o"` |

‎src/content/partials/cloudflare-one/gateway/selectors/user-group-names.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
params:
3+
- UIname
4+
---
5+
6+
| UI name | API example |
7+
| ---------------- | ------------------------------------------------- |
8+
| {props.UIname} | `identity.groups.name == "\"finance\""` |

‎src/content/partials/cloudflare-one/warp/os-version-semver.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
{}
3+
4+
---
5+
6+
:::note
7+
8+
The OS version must be specified as a valid [Semver](https://semver.org/). For example, if your device is running OS version `1.2`, you must enter `1.2.0`.
9+
10+
:::

‎src/content/partials/learning-paths/zero-trust/device-profiles.mdx‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ To customize the default settings:
3636

3737
4. Save the profile.
3838

39-
5. Under **Global settings**,
39+
5. Under [**Global settings**](/cloudflare-one/connections/connect-devices/warp/configure-warp/warp-settings/#global-settings),
4040
1. (Recommended) Enable **Admin override code** if you turned on **Lock WARP switch**.
4141
2. Enable **Install CA to system certificate store** if you want users to see a [custom block page](/cloudflare-one/policies/gateway/block-page/).
4242

@@ -80,7 +80,35 @@ https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/devices/settings \
8080
}'
8181
```
8282

83-
</TabItem> </Tabs>
83+
</TabItem>
84+
<TabItem label="Terraform (v5)">
85+
86+
1. Add the following permission to your [`cloudflare_api_token`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token):
87+
- `Zero Trust Write`
88+
89+
2. Configure default profile settings using the [`cloudflare_zero_trust_device_default_profile`](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_default_profile) resource:
90+
91+
```tf
92+
resource "cloudflare_zero_trust_device_default_profile" "default_profile" {
93+
account_id = var.cloudflare_account_id
94+
allow_mode_switch = false
95+
allow_updates = false
96+
allowed_to_leave = false
97+
auto_connect = 600
98+
captive_portal = 180
99+
disable_auto_fallback = true
100+
exclude_office_ips = false
101+
service_mode_v2 = {mode = "warp"}
102+
support_url = "https://support.example.com"
103+
switch_locked = true
104+
tunnel_protocol = "wireguard"
105+
}
106+
```
107+
108+
3. [Global settings](/cloudflare-one/connections/connect-devices/warp/configure-warp/warp-settings/#global-settings) are not currently supported by the Terraform v5 provider (as of version 5.3.0). To turn on **Admin override code** and **Install CA to system certificate store**, use the dashboard or API.
109+
110+
</TabItem>
111+
</Tabs>
84112

85113
## (Optional) Create an office profile
86114

0 commit comments

Comments
 (0)