SCIM setup is under-documented for the admins who run it: we have reference pages per IdP, but nothing that walks through concepts, preparation, and best practices end to end. The SCIM request log that shipped in org admin settings (Settings → SCIM → Request log) has no docs at all, so the self-serve debugging it was built for still routes back to support.
This topic warrants a guide (not tutorial or docs/reference), with a section on reading the request log.
Impact
- SCIM tickets are among our most involved support investigations; the "wrong role after provisioning" case is the most common shape
- The request log exists so customers can answer "what did my IdP send and how did Lightdash respond" themselves, but nobody will find it or know how to read it without docs
- Enterprise prospects evaluating SCIM look for a guide-shaped page before committing to setup
Scope of the guide
- Concepts: users, groups, roles, tokens, how IdP sync cycles map to Lightdash entities
- Preparation checklist before turning on provisioning (roles and groups planned, verified domain, token ownership, SSO already working)
- Best practices and known IdP differences (Okta vs Entra sync cadence, role assignment shapes)
- Reading the request log: what each action label means, target identity, affected roles, status and
scimType badges, and when to check the IdP's own provisioning logs for full payloads
- Troubleshooting flow that starts with the request log rather than a support ticket
Additional agent context
Where to start
- Request log feature and its exact columns, action labels, retention, and gating: lightdash/lightdash PR #28415 (Product ticket PROD-10826 has the full spec)
- Existing SCIM reference pages in mintlify-docs under the security and permissions area; the guide links to them rather than repeating IdP click-paths
Verifications
- A reader who has never set up SCIM can go from "nothing" to a working, verified sync following only the guide and the linked reference pages
- Every column and badge in the request log tab is explained
- The troubleshooting section resolves the "user has the wrong role" case without contacting support
Scope
- No new reference pages; this is one guide plus a request-log section, linked from the existing SCIM pages
SCIM setup is under-documented for the admins who run it: we have reference pages per IdP, but nothing that walks through concepts, preparation, and best practices end to end. The SCIM request log that shipped in org admin settings (Settings → SCIM → Request log) has no docs at all, so the self-serve debugging it was built for still routes back to support.
This topic warrants a guide (not tutorial or docs/reference), with a section on reading the request log.
Impact
Scope of the guide
scimTypebadges, and when to check the IdP's own provisioning logs for full payloadsAdditional agent context
Where to start
Verifications
Scope