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 1 commit
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
109 changes: 109 additions & 0 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 @@ -155,6 +155,115 @@ Refer to the list of [Roles](/fundamentals/setup/manage-members/roles/) for more
To successfully provision with Microsoft Entra ID, the `user principal name` and `email` fields must match. These values are case-sensitive.
:::

### 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