Skip to content

Commit c49ae8f

Browse files
dcpenaAdamBouhmaddeadlypants1973angelampcosta
authored and
sdnts
committed
[Fundamentals] Added User Groups docs (cloudflare#22766)
* Added User Groups * Split out SCIM content * Applying Adam's feedback Co-authored-by: Adam Bouhmad <[email protected]> * Additional feedback edits * Updated note and other feedback * Fixing broken links * Apply suggestions from code review Co-authored-by: Kate Tungusova <[email protected]> Co-authored-by: angelampcosta <[email protected]> * Last bits of feedback from review --------- Co-authored-by: Adam Bouhmad <[email protected]> Co-authored-by: Kate Tungusova <[email protected]> Co-authored-by: angelampcosta <[email protected]>
1 parent c4c1026 commit c49ae8f

File tree

7 files changed

+541
-168
lines changed

7 files changed

+541
-168
lines changed

‎public/__redirects‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -711,6 +711,7 @@
711711
/fundamentals/setup/account/customize-account/appearance/ /fundamentals/account/customize-account/ 301
712712
/fundamentals/setup/account/customize-account/communication-preference/ /fundamentals/account/customize-account/ 301
713713
/fundamentals/setup/account/customize-account/language-preference/ /fundamentals/account/customize-account/ 301
714+
714715
/fundamentals/setup/account/* /fundamentals/account/:splat 301
715716
/fundamentals/setup/manage-domains/* /fundamentals//manage-domains/:splat 301
716717
/fundamentals/setup/manage-members/* /fundamentals/manage-members/:splat 301

‎src/content/docs/fundamentals/account/account-security/scim-setup.mdx‎

Lines changed: 0 additions & 168 deletions
This file was deleted.

‎src/content/docs/fundamentals/account/account-security/scim-setup/entra.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Provision with Microsoft Entra
4+
sidebar:
5+
label: Microsoft Entra
6+
---
7+
8+
import { Render } from "~/components";
9+
10+
<Render file="idp-group-deprecation" />
11+
12+
## Set up the Enterprise application
13+
14+
1. Go to your Microsoft Entra ID instance and select **Enterprise Applications**.
15+
2. Select **Create your own application** and name your application.
16+
3. Select **Integrate any other application you do not find in the gallery (Non-gallery)**.
17+
4. Select **Create**.
18+
19+
## Provision the Enterprise application
20+
21+
1. Under **Manage** on the sidebar menu, select **Provisioning**.
22+
2. Select **Automatic** on the dropdown menu for the Provisioning Mode.
23+
3. Enter your API token value and the tenant URL: `https://api.cloudflare.com/client/v4/accounts/<your_account_ID>/scim/v2`.
24+
4. Select **Test Connection**, then select **Save**.
25+
26+
## Configure user & group sync in Microsoft Entra ID application
27+
28+
1. Once the SCIM application is created, [assign users and groups to the application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal?pivots=portal).
29+
2. To begin syncing your Users & Groups into Cloudflare, navigate back to **Provisioning**, and under **Provisioning Status**, check *On*, then select **Save**.
30+
31+
:::note
32+
To successfully provision with Microsoft Entra ID, the `user principal name` and `email` fields must match. These values are case-sensitive.
33+
:::
34+
35+
3. To validate which users and groups were synchronized, select **Provisioning logs** in Microsoft Entra. You can also check the Cloudflare dashboard Audit Logs by navigating to **Manage Account** > **Audit Log**.
36+
4. To grant permissions to Users & Groups in Cloudflare, refer to the Permission Policies guide.
37+
38+
39+
## (Optional) Automate Cloudflare's SCIM integration
40+
41+
Cloudflare's SCIM integration requires one external application per account. Customers with many accounts may want to automate part of the setup to save time and reduce the amount of time spent in the Entra administrative UI.
42+
43+
The initial setup of creating the non-gallery applications and adding the provisioning URL and API key are scriptable via API, but the rest of the setup is dependent on your specific need and IDP configuration.
44+
45+
**1. Get an access token**
46+
47+
Get an Entra access token. Note that the example below is using the Azure CLI.
48+
49+
```
50+
# Using azure-cli
51+
az login
52+
az account get-access-token --resource https://graph.microsoft.com
53+
54+
(payload with accessToken returned)
55+
```
56+
**2. Create a new application via template.**
57+
58+
The template ID 8adf8e6e-67b2-4cf2-a259-e3dc5476c621 is the suggested template to create non-gallery apps in the Entra docs. Replace `<accessToken>` and `displayName` with your values.
59+
60+
```curl title="Example request"
61+
curl -X POST 'https://graph.microsoft.com/v1.0/applicationTemplates/8adf8e6e-67b2-4cf2-a259-e3dc5476c621/instantiate' \
62+
--header 'Content-Type: application/json' \
63+
--header 'Authorization: Bearer <accessToken>' \
64+
--data-raw '{
65+
"displayName": "Entra API create application test"
66+
}'
67+
```
68+
69+
```curl title="Example response"
70+
{
71+
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.applicationServicePrincipal",
72+
"application": {
73+
"id": "343a8552-f9d9-471c-b677-d37062117cc8", //
74+
"appId": "03d8207b-e837-4be9-b4e6-180492eb3b61",
75+
"applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
76+
"createdDateTime": "2025-01-30T00:37:44Z",
77+
"deletedDateTime": null,
78+
"displayName": "Entra API create application test",
79+
"description": null,
80+
// ... snipped rest of large application payload
81+
},
82+
"servicePrincipal": {
83+
"id": "a8cb133d-f841-4eb9-8bc9-c8e9e8c0d417", // Note this ID for the subsequent request
84+
"deletedDateTime": null,
85+
"accountEnabled": true,
86+
"appId": "03d8207b-e837-4be9-b4e6-180492eb3b61",
87+
"applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
88+
"appDisplayName": "Entra API create application test",
89+
// ...snipped rest of JSON payload
90+
}
91+
```
92+
93+
**3. Create a provisioning job**
94+
95+
To enable provisioning, you will also need to create a job. Note the SERVICE_PRINCIPAL_ID in the previous request will be used in the request below. The SCIM templateId is an Entra provided template.
96+
97+
```curl title="Example request"
98+
curl -X POST 'https://graph.microsoft.com/v1.0/servicePrincipals/<SERVICE_PRINCIPAL_ID>/synchronization/jobs' \
99+
--header 'Content-Type: application/json' \
100+
--header 'Authorization: Bearer <accessToken>' \
101+
--data-raw '{
102+
"templateId": "scim"
103+
}'
104+
```
105+
106+
```curl title="Example response"
107+
{
108+
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('a8cb133d-f841-4eb9-8bc9-c8e9e8c0d417')/synchronization/jobs/$entity",
109+
"id": "scim.5b223a2cc249463bbd9a791550f11c76.03d8207b-e837-4be9-b4e6-180492eb3b61",
110+
"templateId": "scim",
111+
"schedule": {
112+
"expiration": null,
113+
"interval": "PT40M",
114+
"state": "Disabled"
115+
},
116+
// ... snipped rest of JSON payload
117+
```
118+
119+
**4. Configure the SCIM provisioning URL and API token**
120+
121+
Next, configure the Tenant URL (Cloudflare SCIM endpoint) and API token (SCIM Provisioning API Token).
122+
123+
Replace `<accessToken>`, `<ACCOUNT_ID>`, `<SCIM_PROVISIONING_API_TOKEN_VALUE>` with your values.
124+
125+
```curl title="Example request"
126+
--header 'Content-Type: application/json' \
127+
--header 'Authorization: Bearer <accessToken>' \
128+
--data-raw '{
129+
"value": [
130+
{
131+
"key": "BaseAddress",
132+
"value": "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/scim/v2"
133+
},
134+
{
135+
"key": "SecretToken",
136+
"value": "<SCIM_PROVISIONING_API_TOKEN_VALUE>"
137+
}
138+
]
139+
}'
140+
```
141+
142+
After completing the tasks above, the next steps in Entra include:
143+
144+
- Additional group/provisioning configuration
145+
- Test and save after updating the config.
146+
- Provisioning after configuration is complete

‎src/content/docs/fundamentals/account/account-security/scim-setup/index.mdx‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
pcx_content_type: how-to
3+
title: SCIM provisioning
4+
5+
---
6+
7+
Cloudflare supports bulk provisioning of users into the Cloudflare dashboard by using the System for Cross-domain Identity Management (SCIM) protocol. This allows you to connect your external identity provider (IdP) to Cloudflare and quickly onboard and manage users and their permissions. Cloudflare supports SCIM onboarding with Okta and Microsoft Entra.
8+
9+
:::note
10+
This section covers SCIM provisioning for the Cloudflare dashboard only. If you need to provision SCIM for Cloudflare Zero Trust, refer to [Zero Trust SCIM provisioning](/cloudflare-one/identity/users/scim/).
11+
:::
12+
13+
## Expected behaviors
14+
15+
Expectations for user lifecycle management with SCIM:
16+
17+
| Expected Cloudflare dash behavior | Identity provider action |
18+
| --------------------------------- | ------------------------- |
19+
| User is added to account as member | Assign the user to a SCIM application. They will be assigned the Minimal Account Access role so that their dash experience is not broken. |
20+
| User is removed from account as member | Unassign the user from the SCIM application. |
21+
| Add role to user | Add the user to a group in the IdP which is pushed via SCIM. They must also be assigned to the SCIM application and exist as an account member. |
22+
| Remove role from user | Remove the user from the corresponding group in the IdP. |
23+
| Retain user in account but with no permissions | Remove the user from all role groups but leave them assigned to the SCIM application. They will be an account member with only the role Minimal Account Access. |
24+
25+
## Limitations
26+
27+
- If a user is the only Super Administrator on an Enterprise account, they will not be deprovisioned.
28+
29+
## Prerequisites
30+
31+
- Cloudflare provisioning with SCIM is only available to Enterprise customers using Okta or Microsoft Entra.
32+
- You must be a [Super Administrator](/fundamentals/manage-members/roles/) on the account.
33+
- In your identity provider, you must have the ability to create applications and groups.
34+
35+
---
36+
## Gather the required data
37+
38+
To start, you will need to collect a couple of pieces of data from Cloudflare and set these aside for later use.
39+
40+
### Get your Account ID
41+
42+
1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to the Cloudflare account that you want to configure for SCIM provisioning.
43+
2. Copy your account ID from the account home page.
44+
45+
### Create an API token
46+
47+
1. [Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions:
48+
49+
| Type | Item | Permission |
50+
| ------- | ----------------- | ---------- |
51+
| Account | SCIM Provisioning | Edit |
52+
53+
:::note
54+
55+
Cloudflare recommends using Account Owned API Tokens for SCIM Provisioning. Using user-specific API tokens, while supported, will lead to a broken SCIM connection in the event that the user's policies are revoked from the account with the SCIM integration. Learn more about [account owned tokens](/fundamentals/api/get-started/account-owned-tokens/).
56+
:::
57+
58+
2. Under **Account Resources**, select the specific account to include or exclude from the dropdown menu, if applicable.
59+
3. Select **Continue to summary**.
60+
4. Validate the permissions and select **Create Token**.
61+
5. Copy the token value.

0 commit comments

Comments
 (0)