scim: clarify admin role timing on first provisioning call

[james-ha-bruno]

Why

A customer (Okta SCIM, admin provisioning) configured Admin Role Mapping correctly and still had a user provisioned as a licensed user rather than an admin.

Their brunoRole attribute was written by a group rule triggered by the same group that granted the app assignment. Okta schedules the attribute write and the assignment push independently, so the account creation went out ~11 seconds before the role value existed. The user was created as a licensed user, and the later role push promoted them to admin while the license stayed in place.

Two documentation gaps caused this:

1. No page stated that the admin role must be present on the first provisioning call.
2. The Okta guide recommended reading a stored directory attribute, which is timing-dependent. The Entra ID guide uses an App Role resolved through SingleAppRoleAssignment(...), which resolves at push time and is not exposed to this. The two guides were not conceptually equivalent, and Okta's was the fragile one.

What changed

Overview — new "Provisioning administrators" section (between "Enabling SCIM Provisioning" and "Next Steps"). The page previously made no mention of admin provisioning, so readers only discovered the capability by opening a provider-specific guide. Covers what an admin gets, the decision table for admin vs. licensed user, exact-match semantics, and the first-call requirement.

Okta — the bulk of the change:

• First-call warning plus exact-match / Users-list notes at the top of "Configure Admin Role Mapping"
• Restructured into Option A (group-membership expression, resolved at push time, recommended) and Option B (stored profile attribute, with the timing caveat and a pointer to Option A)
• The shared roles app-profile attribute step (and its externalNamespace warning) is hoisted above the A/B split, since both options need it
• New "Verify an administrator provisioned correctly" block and a "Troubleshooting" section

Entra ID — first-call warning, verification block, and a Common issues entry. The SingleAppRoleAssignment(...) guidance is deliberately untouched; it is correct as it stands.

Both provider pages now document the correct remedy for an affected user: remove the license under Users in the portal, since re-provisioning through the IdP does not remove an already-issued license.

Notes for review

• Only v4 (root) pages are edited. Admin Role Mapping does not exist in the v3/ or v2/ copies, so there is nothing for these changes to attach to there.
• The promotion behaviour is described as designed behaviour, not a bug or limitation — Bruno does not revoke an already-issued license so that a user already working in Bruno desktop is never cut off. No future changes are promised anywhere in the copy.
• Anchor slugs use Option A: … rather than an em dash, so the generated slug is unambiguous under either dashing behaviour. All in-page anchors were verified to resolve against the final heading slugs.
• No screenshots were lost in the Okta restructure — the referenced image set is identical to main. Option B's former ### headings became bold sub-steps to keep the heading hierarchy sane under the new #### options.
• Formatting left alone. prettier --check fails on these files, but it also fails on them at main and on the untouched bruno-scim-api.mdx, so the drift is pre-existing. Running --write would have buried the content diff in whole-file reformatting — worth a separate pass if you want the directory clean.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
bruno-docs-main	🟢 Ready	View Preview	Sep 9, 2026, 3:08 PM