Skip to content

[Fundamentals] Added User Groups docs #22596

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

Closed
wants to merge 5 commits into from
Closed

[Fundamentals] Added User Groups docs #22596

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cf03799
Added User Groups docs
dcpena May 21, 2025
a30e125
Added additional content
dcpena May 21, 2025
06f9663
Fixed typo and added link to User Groups docs
dcpena May 21, 2025
fbe7b94
Fixed duplicate content in tabs
dcpena May 21, 2025
559259b
Split out SCIM provisioning
dcpena May 29, 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
183 changes: 138 additions & 45 deletions src/content/docs/fundamentals/setup/account/account-security/scim-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This section covers SCIM provisioning for the Cloudflare dashboard only. If you

## Prerequisites

- Cloudflare provisioning with SCIM is only available to Enterprise customers using Okta or Microsoft Entra.
- Cloudflare provisioning with SCIM is only available to Enterprise customers using Okta or Microsoft Entra ID.
- You must be a [Super Administrator](/fundamentals/setup/manage-members/roles/) on the account.
- In your identity provider, you must have the ability to create applications and groups.

Expand Down Expand Up @@ -47,13 +47,11 @@ To start, you will need to collect a couple of pieces of data from Cloudflare an
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/).
:::

2. Under **Account Resources**, select the specific account to include or exclude from the dropdown menu, if applicable.
2. Select **Continue to summary**.

3. Select **Continue to summary**.
3. Validate the permissions and select **Create Token**.

4. Validate the permissions and select **Create Token**.

5. Copy the token value.
4. Copy the token value.

---

Expand Down Expand Up @@ -81,43 +79,28 @@ The **Update User Attributes** option is not supported.

1. In your integration page, go to **Provisioning** > **Configure API Integration**.
2. Enable **Enable API Integration**.
3. In SCIM 2.0 Base URL, enter: `https://api.cloudflare.com/client/v4/accounts/<accountID>/scim/v2`.
4. In OAuth Bearer Token, enter your API token value.
5. Select **Save**.
3. In SCIM 2.0 Base URL, enter: `https://api.cloudflare.com/client/v4/accounts/<accountID>/scim/v2`, substituting `accountID` for your [Cloudflare Account ID](/fundamentals/setup/account/account-security/scim-setup/#get-your-account-id).
4. In the **OAuth Bearer Token** field, enter your API token value.
5. Deselect **Import Groups**.


### Set up your SCIM users
### Set up your SCIM users and groups

1. In **Provisioning to App**, select **Edit**.
2. Enable **Create Users** and **Deactivate Users**. Select **Save**.
3. In the integration page, go to **Assignments** > **Assign** > **Assign to Groups**.
4. Choose the group(s) that you want to provision to Cloudflare.
5. Select **Done**.

This will provision all of the users in the group(s) affected to your Cloudflare account with "minimal account access."
3. Select **Done**.
4. In the Assignments tab, add the users you want to synchronize with Cloudflare Dash. You can add users in batches by assigning a group. If a user is removed from the application assignment via either direct user assignment or removed from the group that was assigned to the app, this will trigger a deprovisioning event from Okta to Cloudflare.
5. In the Push Groups tab, add the Okta groups you want to synchronize with Cloudflare Dash. You can view these groups in the dash under Manage Account > Manage members > Members > User Groups.

### Configure user permissions

Two options exist for managing user permissions:

* Manage your user permissions on a per-user basis in the Cloudflare dashboard, API, or using Terraform.
* Map your IdP groups to a Cloudflare built-in [Role](/fundamentals/setup/manage-members/roles/). Groups may only be linked to one role.
:::note
You must have opted into the Cloudflare User Groups Public Beta to synchronize groups from Okta to Cloudflare. Refer to the [User Groups](/fundamentals/setup/manage-members/user-groups/) documentation for more information.
:::

1. Go to your SCIM application in the App Integration Catalog, then select **Provisioning**.
2. Under **To App*, select **Edit**.
3. Enable **Create Users** and **Deactivate Users**. Select **Save**.
4. Go to **Push Groups**.
5. Select **+ Push Groups**, then **Find groups by name**.
6. Enter the name of the group(s) that you want to sync to Cloudflare.
7. Choose **Link Group**.
8. Cloudflare provisioned user groups are named in the pattern `CF-<accountID> - <Role Name>`. Choose the appropriate group that maps to your target role.
9. Disable **Rename groups**. Select **Save**.
10. Within the **Push Groups** tab, select **Push Groups**.
11. Add the groups you created.
12. Select **Save**.
To verify the integration, select **View Logs** in the Okta SCIM application, and check the Cloudflare Dash Audit Logs by navigating to **Manage Account** > **Audit Log**.

Adding any users to these groups will grant them the role. Removing the users from the identity provider will remove them from the associated role.
To grant permissions to Users & Groups in Cloudflare, refer to the Permission Policies guide.

---
This will provision all of the users in the group(s) affected to your Cloudflare account with "minimal account access."

## Provision with Microsoft Entra ID

Expand All @@ -137,24 +120,134 @@ Adding any users to these groups will grant them the role. Removing the users fr

### Configure user permissions in Microsoft Entra ID

Currently, groups need to match a specific format to provision specific Cloudflare account-level roles. Cloudflare is in the process of adding Cloudflare Groups, which can take in freeform group names in the future.
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.)

These permissions work on an exact string match with the form `CF-<your_account_ID> - <Role_Name>`
:::note
You must have opted into the Cloudflare User Groups Public Beta to synchronize groups from Okta to Cloudflare. Refer to the [User Groups](/fundamentals/setup/manage-members/user-groups/) documentation for more information.

Refer to the list of [Roles](/fundamentals/setup/manage-members/roles/) for more details.
Currently, groups need to match a specific format to provision specific Cloudflare account-level roles. Cloudflare is in the process of adding Cloudflare Groups, which can take in freeform group names in the future.
:::

1. To ensure that only required groups are provisioned, go to your Microsoft Entra ID instance.
2. Under Manage on the sidebar menu, select **Provisioning**.
3. Select **Provision Entra Groups** in Mappings.
4. Select **All records** under Source Object Scope.
5. Select **Add scoping filter** and create the appropriate filtering criteria to capture only the necessary groups.
6. Save the Attribute Mapping by selecting **OK** and return to the Enterprise Application Provisioning overview page.
7. Select **Start provisioning** to view the new users and groups populated on the Cloudflare dashboard.
2. To begin syncing your Users & Groups into Cloudflare, navigate back to **Provisioning**, and under **Provisioning Status**, check *On*, then select **Save**.

:::note
To successfully provision with Microsoft Entra ID, the `user principal name` and `email` fields must match. These values are case-sensitive.
:::

3. To check which users and groups were synchronized, select **Provisioning logs**.
4. To verify the integration, select **Provisioning Logs** in Entra ID application, and check the Cloudflare Dash Audit Logs by navigating to **Manage Account** > **Audit Log**.
5. To grant permissions to Users & Groups in Cloudflare, refer to the Permission Policies guide.


### Automate Cloudflare's SCIM integration

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.

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.

1. Get an access token

Get an Entra access token. Note that the example below is using the Azure CLI.
Copy link
Contributor

@bnelz bnelz May 21, 2025

Choose a reason for hiding this comment

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

[blocking, suggestion] Do we want to provide another blurb, warning, or caveat notice that these instructions are for Entra specifically? Should we also produce equivalent steps for other IdP integrations? Should we create some new sections that categorize our IdP specific guidance within these docs?

Copy link
Collaborator Author

@dcpena dcpena May 21, 2025

Choose a reason for hiding this comment

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

Yep, totally happy to add in additional info that will make this as clear as we can to users.

I definitely think we should create equivalent sections if it makes sense.

Also, something to consider: if this page page may grow to include multiple IdP integrations over time, would it also be easier to consume as a user if we had a page devoted to Microsoft Provisioning and a separate for Okta? I feel like this page is on the verge of being a lot to scroll through. Thoughts?

Copy link
Contributor

@mcescalante mcescalante May 21, 2025

Choose a reason for hiding this comment

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

yeah, IMO we should have (newly created) separate dedicated pages for detailed instructions for Microsoft and Okta, similar to what ZT developer docs have for SSO integration IdPs. If we do this, we can still keep this page as an introduction and overview and maybe use something like a table to list IdPs we support and link out to the dedicated pages?

That said, I think the "Automate Entra via API" section is probably more of a reference implementation. So:

  1. Yes from me to dedicated pages per IdP. Cleaner structure, keeps pages smaller, and scales nicely.
  2. We should adjust (or remove) the Entra specific "automate" instructions to make it very clear that they are more of a reference implementation. Given how much IdP setups can vary, steering users towards Microsoft docs is probably a better bet.


```
# Using azure-cli
az login
az account get-access-token --resource https://graph.microsoft.com

(payload with accessToken returned)
```
2. Create a new application via template.

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.
Copy link
Contributor

@bnelz bnelz May 21, 2025

Choose a reason for hiding this comment

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

[non-blocking, suggestion] Should this link to the guidance in the Microsoft documentation in the event it is updated or deeper understanding is desirable by the customer?

Copy link
Collaborator Author

@dcpena dcpena May 21, 2025

Choose a reason for hiding this comment

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

I'm a fan of linking out to Microsoft docs in areas like that were there's the potential for their docs to update/change.

Copy link
Contributor

@mcescalante mcescalante May 21, 2025

Choose a reason for hiding this comment

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

I'm also a fan of linking out but for whatever it's worth in my experience with Entra SCIM docs is that they are dense and there is a lot of clicking around to find what I want. Mentioning this because in order to find this template ID I had to read multiple documents and fail a few times to sort out what the right ID was.

Echoing myself on an above comment: The Entra automation instructions are more of a reference implementation that could change.


```curl title="Example request"
curl -X POST 'https://graph.microsoft.com/v1.0/applicationTemplates/8adf8e6e-67b2-4cf2-a259-e3dc5476c621/instantiate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <accessToken>' \
--data-raw '{
"displayName": "Entra API create application test"
}'
```

```curl title="Example response"
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.applicationServicePrincipal",
"application": {
"id": "343a8552-f9d9-471c-b677-d37062117cc8", //
"appId": "03d8207b-e837-4be9-b4e6-180492eb3b61",
"applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
"createdDateTime": "2025-01-30T00:37:44Z",
"deletedDateTime": null,
"displayName": "Entra API create application test",
"description": null,
// ... snipped rest of large application payload
},
"servicePrincipal": {
"id": "a8cb133d-f841-4eb9-8bc9-c8e9e8c0d417", // Note this ID for the subsequent request
"deletedDateTime": null,
"accountEnabled": true,
"appId": "03d8207b-e837-4be9-b4e6-180492eb3b61",
"applicationTemplateId": "8adf8e6e-67b2-4cf2-a259-e3dc5476c621",
"appDisplayName": "Entra API create application test",
// ...snipped rest of JSON payload
}
```

3. Create a provisioning job

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.

```curl title="Example request"
curl -X POST 'https://graph.microsoft.com/v1.0/servicePrincipals/<SERVICE_PRINCIPAL_ID>/synchronization/jobs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <accessToken>' \
--data-raw '{
"templateId": "scim"
}'
```

```curl title="Example response"
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('a8cb133d-f841-4eb9-8bc9-c8e9e8c0d417')/synchronization/jobs/$entity",
"id": "scim.5b223a2cc249463bbd9a791550f11c76.03d8207b-e837-4be9-b4e6-180492eb3b61",
"templateId": "scim",
"schedule": {
"expiration": null,
"interval": "PT40M",
"state": "Disabled"
},
// ... snipped rest of JSON payload
```

4. Configure the SCIM provisioning URL and API token

Next, configure the Tenant URL (Cloudflare SCIM endpoint) and API token (SCIM Provisioning API Token).

Replace `<accessToken>`, `<ACCOUNT_ID>`, `<SCIM_PROVISIONING_API_TOKEN_VALUE>` with your values.

```curl title="Example request"
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <accessToken>' \
--data-raw '{
"value": [
{
"key": "BaseAddress",
"value": "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/scim/v2"
},
{
"key": "SecretToken",
"value": "<SCIM_PROVISIONING_API_TOKEN_VALUE>"
}
]
}'
```

After completing the tasks above, the next steps in Entra include:

- Additional group/provisioning configuration
- Test and save after updating the config.
- Provisioning after configuration is complete

## Expected behaviors

Expectations for user lifecycle management with SCIM:
Expand Down
Loading
Loading