docs(access-management): document SCIM provisioning and user groups - #84388
docs(access-management): document SCIM provisioning and user groups#84388Ian Alton (ian-at-airbyte) wants to merge 4 commits into
Conversation
Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
👋 Greetings, Airbyte Team Member!Here are some helpful tips and reminders for your convenience. 💡 Show Tips and TricksPR Slash CommandsAirbyte Maintainers (that's you!) can execute the following slash commands on your PR:
📚 Show Repo GuidanceHelpful Resources
|
|
Deploy preview for airbyte-docs ready!
Deployed with vercel-action |
|
|
||
| 5. Click **Activate SSO**. --> | ||
|
|
||
| For the next step, see [Set up SCIM using Entra ID](../scim-providers/azure-entra-id). |
There was a problem hiding this comment.
Place this under its own heading. It's not necessarily a logical next step if you're not using SCIM.
There was a problem hiding this comment.
👍 On it. Same fix as the Okta page — own optional heading, not a trailing "next step".
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in b1a761d. Same optional section here.
|
|
||
| 5. Click **Activate SSO**. --> | ||
|
|
||
| For the next step, see [Set up SCIM using Okta](../scim-providers/okta). |
There was a problem hiding this comment.
Place this under its own heading. It's not necessarily a logical next step if you're not using SCIM.
There was a problem hiding this comment.
👍 On it. Moving it out of the SSO flow and under its own optional heading so it doesn't read as a required next step.
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in b1a761d. SCIM now lives under its own ## Optional: Add SCIM provisioning section that says SSO works without it.
| - Password synchronization. Airbyte ignores any password your IdP sends. | ||
| - Bulk operations, sorting, and ETags. | ||
|
|
||
| Airbyte returns at most 200 resources per page and 100 by default, so configure your IdP to page through results. |
There was a problem hiding this comment.
Just to be clear, we're talking about the maximum size of the user base that Airbyte is able to sync from the idp at once?
There was a problem hiding this comment.
👍 On it — and no, it's not a cap on the user base. This is response page size only: Airbyte's SCIM list endpoints return 100 resources per page by default and clamp a requested count to 200, and the IdP walks the rest with startIndex. There's no limit on how many users or groups you can provision in total. Rewriting the sentence to say that explicitly.
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in b1a761d. Now states it's the size of a single SCIM response page, that a requested count above 200 gets clamped, that the IdP requests further pages, and that it doesn't limit how many users or groups you can provision.
| After you reactivate someone, your IdP must re-add them to their groups, and an organization admin must re-grant any individual roles they had. Otherwise, they can sign in but only see what an organization member sees. | ||
| ::: | ||
|
|
||
| ## Provision users who already have Airbyte accounts |
There was a problem hiding this comment.
What happens if someone is a member of multiple organizations, but one or more of those organizations doesn't use SCIM or SSO? Are they able to continue to sign in?
There was a problem hiding this comment.
👍 On it. Yes, they keep signing in — SCIM never gates authentication. It issues no credentials, and deactivation is scoped to the provisioning organization: it removes that org's permissions, its workspace permissions, and its group memberships, and leaves the account and every other org's access alone.
What can force a sign-in path is SSO domain enforcement, not SCIM. UserHandler.handleSSORestrictions/isAllowedDomain rejects a login with SSORequiredProblem when the user's email domain is claimed by an SSO organization and the session didn't come through that organization's SSO realm (gated by the RestrictLoginsForSSODomains flag). That's a property of the account's email domain, so someone whose domain is claimed has to come in through that org's SSO — and once in, the same account still reaches their non-SSO orgs normally.
Adding a short "people in more than one organization" note to the lifecycle section that says this, and pointing at SSO rather than implying SCIM is what restricts login.
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in 727ebe9. New "People in multiple organizations" subsection in the lifecycle section: SCIM doesn't control sign-in, deactivation is scoped to the provisioning organization, and whether someone signs in with SSO follows from SSO domain verification rather than SCIM — with the same account still reaching organizations that use neither.
|
|
||
| Set up SSO before SCIM. Users your IdP provisions can only sign in with the credentials your IdP manages. | ||
|
|
||
| ## Enable SCIM in Airbyte |
There was a problem hiding this comment.
I think it's worth starting this discussion with a warning that you should delete user groups before enabling SCIM. As I understand it, once SCIM is enabled, user groups are managed fully by the IDP and you can't later delete or modify groups that aren't being managed by the IDP.
There was a problem hiding this comment.
👍 On it — adding that warning before the enable steps. One correction to the mechanism, because the code makes the recommendation slightly narrower than "everything locks":
The lock is per group, keyed on whether that group has a SCIM mapping (GroupServiceDataImpl.verifyAirbyteMutationAllowed), not org-wide. So:
- Groups that predate SCIM and never get mapped stay fully renamable, editable, and deletable in Airbyte even while SCIM is on.
- Any group your IdP created or adopted can't be renamed or have its membership changed while SCIM is enabled, and can't be deleted in Airbyte at all while the mapping exists — including after you disable SCIM (that's PLAT-1094).
- Your IdP can never adopt a same-named pre-existing group: creation keeps failing with
409until the Airbyte group is renamed or deleted.
The advice still lands the same way — clear out pre-existing groups first — so I'll say that up front and give the 409 as the reason rather than claiming the old groups become uneditable.
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in b1a761d. Warning added directly under Enable SCIM in Airbyte, before step 1: clear out or rename groups your IdP should provision, with the 409 as the reason and the mapped-group lock (no rename or membership change while SCIM is on, no deletion while the mapping exists — including after disabling) spelled out. It also says never-mapped groups stay editable, so nobody reads it as "everything freezes". The disable/re-enable list picked up the matching clause.
| While SCIM is enabled, you can't rename a group, change its membership, or delete it in Airbyte. Make those changes in your identity provider instead. | ||
|
|
||
| :::warning | ||
| Your identity provider can't adopt an existing Airbyte group with the same name. Provisioning for that group fails with a `409` response until you rename or delete the Airbyte group. |
There was a problem hiding this comment.
I made a similar comment on the scim.md article, but basically, I think we should encourage people to delete existing user groups before enabling SCIM. This avoids a number of problems, including the one you outline here.
There was a problem hiding this comment.
👍 On it. Adding the "delete pre-existing groups before you enable SCIM" recommendation here too, with the enable-flow warning in scim.md as the primary home and this page keeping the 409 collision detail. See my reply on that thread for the one place the mechanism differs from your description — unmapped legacy groups do stay editable; it's the mapped ones that lock.
Session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
There was a problem hiding this comment.
☑️ Resolved in b1a761d. This page now carries the recommendation alongside the 409 detail and links to the enable section for the full guidance.
Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
Co-Authored-By: ian.alton@airbyte.io <ian.alton@airbyte.io>
1 participant
What
Public-facing documentation for SCIM v2 provisioning and user groups, requested by Ian Alton in DOCS-74.
New pages:
access-management/scim.md— concepts, prerequisites, enable flow, token handling, disable/re-enable, supported SCIM surface, lifecycle behavior, troubleshooting.access-management/user-groups.md— what a group is, the identity-provider/Airbyte ownership split, assigning permissions, how permissions combine.access-management/scim-providers/okta.mdand.../azure-entra-id.md— provider setup (Okta app integration, Entra custom non-gallery app).All four pages are
products: cloud-teams, which renders Pro + Enterprise Flex badges. Per the ticket, existing SSO and RBAC content isn't duplicated — the surrounding pages only get pointers.How
Behavior was taken from the implementation in
airbyte-platform-internalrather than the technical spec, per the ticket. The claims that a reviewer should sanity-check hardest:POST /Usersis rejected unless the organization holds a verifiedorganization_domain_verificationrecord for that email domain, so the docs make SSO + domain verification a hard prerequisite.organization_member. Workspace roles, elevated organization roles, and group memberships must be re-established.409), the enable flow now opens with a warning to clear out pre-existing groups first.airbyte_scim_<64 hex>, shown once, no expiry, rotation invalidates the previous token immediately with no grace period. Docs tell admins to copy the SCIM base URL Airbyte displays instead of hard-coding a host, since it's derived fromAIRBYTE_URL.User/Groupschemas, PATCH and filtering supported, no bulk/sort/ETag/password sync/nested groups. Page size is 100 resources per response by default with a requestedcountclamped to 200 — a response page size, not a ceiling on how many users or groups can be provisioned.Review guide
docs/platform/access-management/scim.md— the anchor page; everything else defers to it.docs/platform/access-management/user-groups.mddocs/platform/access-management/scim-providers/okta.md,.../azure-entra-id.mdrbac.md,sso.md,role-mapping.md, and the two existing SSO provider guides, where SCIM is linked from its own optional section rather than as a trailing next step.docusaurus/sidebar-platform.jsNeeds confirmation before this publishes
These features are still in development, so the affected passages are written to what's shipped today and should be re-checked when the work lands:
GroupServiceDataImplenforces today.Provider UI navigation in the two SCIM provider guides is written at a level defensible from Airbyte's code plus Okta's and Microsoft's public docs, and points to those docs rather than prescribing edition-specific menu paths. HTML comments in each file list what still needs a pass against a live tenant.
Also unverified: whether SCIM's effect on a pending Airbyte invitation is anything at all — no interaction exists in the code, so the docs make no claim.
User Impact
Pro and Enterprise Flex customers get setup and behavior documentation for SCIM and user groups where none existed. Docs-only change; no product behavior changes.
Can this PR be safely reverted and rolled back?
Test plan
pnpm buildfromdocusaurus/passes (pnpm 9.4.0 via Corepack; the system pnpm is incompatible with the lockfile). The build is the real gate here since Docusaurus fails on broken links, and every new link target and sidebar ID was checked. The pre-existing broken-anchor warnings elsewhere in the docs are unchanged. MarkdownLint and Vale weren't available locally, so the Vercel preview is worth a look for rendering of the new sidebar category.Link to Devin session: https://app.devin.ai/sessions/e30c3d6fb324419f9478107e8ad9cc1a
Requested by: Ian Alton (ian.alton@airbyte.io)
Requested by: Ian Alton (@ian-at-airbyte)