docs(access-management): document SCIM provisioning and user groups

docs/platform/access-management/rbac.md

@@ -41,6 +41,10 @@ Both roles can create and modify connections, and both can run syncs. Neither ro
 - At the workspace level, assign higher roles for individual workspaces as needed to override organization role within that workspace.
 - Don't assign admin roles frivolously. Once someone is an admin, you can't demote them.
 
+## Permissions from user groups
+
+Group permissions combine with a person's individual permissions. Airbyte uses the highest permission from the person's own permissions and the permissions from all their groups. The person must still be an organization member for group permissions to apply. For more information, see [User groups](user-groups).
+
 ## Setting roles
 
 1. In the navigation bar, click **Workspace settings** or **Organization settings** > **Members**.

docs/platform/access-management/role-mapping.md

@@ -6,6 +6,8 @@ products: cloud-teams
 
 Role-Based Access Control (RBAC) role mapping allows automatic assignment of specific permissions to Airbyte users based on existing roles in your organization. It ensures users have appropriate Airbyte access without manual oversight.
 
+API-based role mapping assigns permissions per user through the Airbyte API. SCIM-driven [user groups](user-groups) keep group names and membership in your identity provider while Airbyte assigns permissions to the group, so every member receives the group's access.
+
 Enabling role mapping in Airbyte requires use of the [Airbyte API](/developers/api-documentation). The Airbyte API exposes endpoints that allow you to retrieve and update user permissions. These endpoints can be used to build automation that manages user access to different workspaces. This functionality is currently limited to the Airbyte API, and is not available in the Terraform Provider.
 
 To enable the Airbyte API in Airbyte Pro or Enterprise Flex, follow these [prerequisites](../using-airbyte/configuring-api-access).

docs/platform/access-management/scim-providers/azure-entra-id.md

@@ -0,0 +1,71 @@
+---
+sidebar_label: Entra ID
+products: cloud-teams
+---
+
+# Set up SCIM using Entra ID
+
+This guide shows you how to configure SCIM provisioning with a custom, non-gallery Microsoft Entra enterprise application. It assumes that you already set up SSO with Entra ID. For SSO setup, see [Set up single sign on using Entra ID](../sso-providers/azure-entra-id).
+
+This guide uses Airbyte's long-lived bearer token. Gallery applications and client-credentials or OAuth provisioning flows are out of scope.
+
+## Before you start
+
+You need:
+
+- Organization admin permissions in Airbyte.
+- Permission to manage enterprise applications in Entra ID.
+- SCIM enabled for your Airbyte organization.
+- A verified email domain in Airbyte for every domain you plan to provision.
+
+## Create or reuse an enterprise application
+
+Create or reuse a custom, non-gallery enterprise application for Airbyte. See Microsoft's [automatic user provisioning documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal) for Entra's current application setup flow.
+
+If you create a new application, use the application type that lets you configure automatic provisioning with a tenant URL and secret token.
+
+## Configure automatic provisioning
+
+1. In Entra ID, open the Airbyte enterprise application.
+
+2. Open **Provisioning** and select **Automatic**.
+
+3. Set **Tenant URL** to the **SCIM base URL** shown in Airbyte.
+
+4. Set **Secret Token** to the Airbyte **Bearer token**.
+
+5. Select **Test Connection**.
+
+6. Save the provisioning configuration after the connection succeeds.
+
+Airbyte shows the SCIM base URL after setup, but it shows the bearer token only during the enable or token-rotation flow.
+
+## Review attribute mappings
+
+Before you start provisioning, review the **Mappings** for users and groups. Entra ID's default mappings can send attributes that Airbyte does not support. Airbyte returns `400` for unsupported attributes or invalid values.
+
+Trim the mappings to the supported attributes listed in [SCIM provisioning](../scim#what-your-identity-provider-can-manage). In particular, make sure your mappings use:
+
+- `userName`
+- `externalId`, when you need it
+- `active`
+- `emails`
+- Supported `name` fields
+- `displayName` for groups
+- `members` for groups
+
+Airbyte does not support nested groups. Group members must be users that Entra ID provisions into the same Airbyte organization.
+
+## Scope and start provisioning
+
+Choose the users and groups that Entra ID should provision in the application's provisioning scope. Review the resulting users and groups in **Mappings**, then start provisioning.
+
+Entra ID owns group names and membership. Airbyte owns permissions assigned to groups. For more information, see [User groups](../user-groups).
+
+## Deactivate and delete users
+
+Use Entra ID's provisioning state to deactivate a user when you want to remove their organization access through SCIM; Airbyte also accepts SCIM `DELETE /Users/{id}`, but that is a protocol operation rather than a button in Entra ID.
+
+When a user is deactivated, Airbyte removes their organization permissions, workspace permissions, and group memberships in that organization. Reactivating the user restores only baseline organization-member access. Entra ID must provision group membership again.
+
+<!-- Review against a live Entra ID tenant: confirm the exact enterprise-application creation flow, **Provisioning** menu labels, **Mappings** controls, scoping controls, and start-provisioning action. Microsoft can change these labels and the available application types. -->

docs/platform/access-management/scim-providers/okta.md

@@ -0,0 +1,70 @@
+---
+sidebar_label: Okta
+products: cloud-teams
+---
+
+# Set up SCIM using Okta
+
+This guide shows you how to configure SCIM provisioning for the existing Airbyte Okta application. It assumes that you already set up SSO with Okta. For SSO setup, see [Set up single sign on using Okta](../sso-providers/okta).
+
+## Before you start
+
+You need:
+
+- Organization admin permissions in Airbyte.
+- Administrator permissions in Okta.
+- SCIM enabled for your Airbyte organization.
+- A verified email domain in Airbyte for every domain you plan to provision.
+
+Before you configure Okta, [enable SCIM in Airbyte](../scim#enable-scim-in-airbyte) and copy the SCIM base URL and bearer token.
+
+## Configure the Okta application
+
+Use Okta's [SCIM provisioning documentation](https://help.okta.com/en-us/content/topics/provisioning/lcm/lcm-provisioning-scim-configure.htm) for the exact Okta UI labels and application navigation. The names can vary by Okta edition.
+
+When you configure provisioning for the existing Airbyte application, use these values:
+
+- **SCIM connector base URL**: The **SCIM base URL** from Airbyte.
+- **Unique identifier field**: `userName`.
+- **Authentication mode**: HTTP Header.
+- **HTTP Header**: The Airbyte **Bearer token**.
+
+Enable the provisioning capabilities that you need:
+
+- Push new users.
+- Push profile updates.
+- Push groups.
+
+If Okta offers password synchronization for the application, turn it off. Airbyte ignores passwords sent through SCIM.
+
+## Test the connector
+
+After you enter the base URL and bearer token, use Okta's connector test action to test the configuration. Resolve any connection or authentication errors before you enable provisioning.
+
+## Enable user provisioning
+
+When the connector test succeeds:
+
+1. In Okta, open the Airbyte application's **Provisioning** settings.
+
+2. Under **To App**, enable **Create users**, **Update users**, and **Deactivate users** as needed.
+
+3. Assign the people who should access Airbyte to the application.
+
+4. Save the provisioning settings.
+
+Okta sends changes for the people assigned to the application. An assigned, active user becomes an organization member in Airbyte.
+
+## Push groups
+
+If you enabled **Push groups**, select the groups you want Okta to provision to Airbyte. Okta owns the group name and membership after provisioning. Airbyte owns permissions assigned to the group.
+
+Group members must be users provisioned into the same Airbyte organization. For group behavior and permissions, see [User groups](../user-groups).
+
+## Deactivate and delete users
+
+Use Okta deactivation to remove a user's organization access through SCIM; Airbyte also accepts SCIM `DELETE /Users/{id}`, but that is a protocol operation rather than a button in Okta.
+
+When a user is deactivated, Airbyte removes their organization permissions, workspace permissions, and group memberships in that organization. Reactivating the user restores only baseline organization-member access. Your IdP must provision group membership again.
+
+<!-- Review against a live Okta tenant: confirm the exact Okta menu names, connector test location, provisioning capability labels, and group-push workflow against the Okta edition. This guide intentionally points to Okta's documentation instead of prescribing edition-specific navigation. -->

docs/platform/access-management/scim.md

@@ -0,0 +1,165 @@
+---
+products: cloud-teams
+---
+
+# SCIM provisioning
+
+System for Cross-domain Identity Management (SCIM) lets your identity provider (IdP) create, update, and deactivate Airbyte users, and create [user groups](user-groups) and manage their membership, without an administrator doing that work in Airbyte.
+
+SCIM is an add-on to [single sign on](sso). To use it, contact Airbyte to enable SCIM for your organization.
+
+## How SCIM changes Airbyte
+
+When SCIM is enabled, your IdP owns who belongs to your organization and which groups they're in. Airbyte still owns what those people and groups can do.
+
+| Airbyte object                   | Owner when SCIM is enabled                                   |
+| -------------------------------- | ------------------------------------------------------------ |
+| Organization membership          | Your IdP                                                     |
+| User profile details, like names | Your IdP                                                     |
+| Group names                      | Your IdP                                                     |
+| Group membership                 | Your IdP                                                     |
+| Group permissions                | Airbyte, set by an organization admin                        |
+| Individual user permissions      | Airbyte, set by an organization admin                        |
+
+Because your IdP is the source of truth for membership, the **Members** page in Airbyte hides invitations while SCIM is enabled. To add or remove someone, assign or unassign them in your IdP.
+
+Airbyte never receives passwords through SCIM. People still sign in with SSO.
+
+## Before you start
+
+You need the following:
+
+- The Pro or Enterprise Flex plan, with SCIM enabled for your organization.
+- Organization admin permissions in Airbyte.
+- Permission to configure provisioning in Okta or Microsoft Entra ID.
+- A **verified domain** in Airbyte for every email domain you plan to provision. Airbyte rejects any user whose email domain your organization hasn't verified. Add and verify domains in **Organization settings** > **SSO**. See the [Okta](sso-providers/okta) or [Entra ID](sso-providers/azure-entra-id) SSO guide for the DNS steps.
+
+Set up SSO before SCIM. Users your IdP provisions can only sign in with the credentials your IdP manages.
+
+## Enable SCIM in Airbyte
+
+:::warning
+Before you enable SCIM, review your existing Airbyte user groups and delete or rename any groups that your IdP should provision. Your IdP can't adopt an Airbyte group with the same name, so provisioning for that group keeps failing with a `409` response until you rename or delete the Airbyte group. After a group is created or adopted through SCIM, you can't rename it or change its membership in Airbyte while SCIM is enabled, and you can't delete it in Airbyte while its SCIM mapping exists, even after you disable SCIM. Groups that have never been mapped through SCIM remain editable and deletable in Airbyte.
+:::
+
+1. In Airbyte, click **Organization settings** > **SSO**.
+
+2. In the SCIM section, choose your **Identity provider**: **Okta** or **Microsoft Entra ID**.
+
+    :::warning
+    You can't change the identity provider later. To switch providers, [contact support](https://support.airbyte.com).
+    :::
+
+3. Click **Enable SCIM**. Airbyte shows you a **SCIM base URL** and a **Bearer token**.
+
+4. Copy both values. Airbyte shows the token only once. If you lose it, you must generate a new one.
+
+    :::warning
+    The bearer token grants your IdP the ability to create, modify, and deactivate users in your organization. Treat it like a password and store it in a secrets manager or password manager.
+    :::
+
+5. Paste the base URL and token into your IdP. Follow the guide for your provider.
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+```
+
+Airbyte continues to display the base URL in the SCIM section after setup, but not the token.
+
+## Manage the bearer token
+
+The token doesn't expire, but you can replace it at any time.
+
+1. Click **Organization settings** > **SSO**.
+
+2. In the SCIM section, click **Generate new token**, then confirm.
+
+The previous token stops working immediately, so your IdP can't provision anyone until you paste the new token into it. Like the first token, Airbyte shows the replacement only once.
+
+## Disable and re-enable SCIM
+
+Click **Disable SCIM** to stop your IdP from provisioning. Airbyte invalidates the token, and:
+
+- Existing users, groups, and group memberships remain as they are.
+- Group names and membership become editable in Airbyte again.
+- SCIM-mapped groups remain undeletable in Airbyte while their mapping exists.
+- Nobody loses access.
+
+To resume provisioning, enable SCIM again with the same identity provider. Airbyte issues a new token, which you must paste into your IdP.
+
+When you re-enable SCIM, Airbyte reconciles any users your IdP had already deactivated: those users lose their permissions and group memberships in this organization, the same way they would have if they were deactivated while SCIM was enabled.
+
+## What your identity provider can manage
+
+Airbyte implements SCIM 2.0 with the core `User` and `Group` schemas.
+
+Users:
+
+- Create, update, deactivate, reactivate, and delete users.
+- Supported user attributes are `userName`, `externalId`, `active`, `emails`, `name` (including `givenName`, `familyName`, `formatted`, `middleName`, and honorific prefixes and suffixes), `displayName`, `nickName`, `profileUrl`, `title`, `userType`, `preferredLanguage`, `locale`, and `timezone`.
+- Every user needs a `userName` and at least one email. Airbyte uses the primary email, or the single work email if none is primary.
+- Group membership is read-only on the user resource. Change membership on the group.
+
+Groups:
+
+- Create, rename, delete, and change membership.
+- Supported group attributes are `displayName`, `externalId`, and `members`.
+- Members must be active users that SCIM provisioned in the same organization.
+
+Airbyte doesn't support the following:
+
+- Assigning Airbyte permissions or roles through SCIM. An organization admin assigns permissions to groups in Airbyte. See [user groups](user-groups).
+- Nested groups.
+- Password synchronization. Airbyte ignores any password your IdP sends.
+- Bulk operations, sorting, and ETags.
+
+Airbyte returns 100 resources per SCIM response page by default. If your IdP requests a `count` above 200, Airbyte clamps it to 200. Your IdP must request additional pages to retrieve the remaining resources; this page size does not limit the total number of users or groups you can provision.
+
+## How deactivation affects access
+
+Deactivating or deleting a user is destructive within the organization that provisioned them. Airbyte removes:
+
+- Their organization permissions.
+- Their permissions in every workspace in the organization.
+- Their membership in every group in the organization.
+
+Airbyte keeps their user account and their access in any other organization they belong to. It also keeps the SCIM record, so your IdP can reactivate them later.
+
+Reactivating a user only restores the baseline organization member permission. Airbyte doesn't restore the workspace roles, elevated organization roles, or group memberships they had before.
+
+:::warning
+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.
+:::
+
+### People in multiple organizations
+
+SCIM doesn't control sign-in. It issues no credentials, and deactivation only affects the organization that provisioned the person, so they keep their account and their access in every other organization they belong to.
+
+Whether someone signs in with SSO depends on [SSO](sso), not SCIM. If an organization that uses SSO has verified their email domain, they sign in through that organization's SSO, and that same account still gives them access to their other organizations, including any that don't use SSO or SCIM.
+
+## Provision users who already have Airbyte accounts
+
+If someone already has an Airbyte account with the email address your IdP provisions, Airbyte links the SCIM record to that existing account instead of creating a duplicate. The account keeps any elevated access it already had in your organization.
+
+If you provision someone before they've ever signed in, Airbyte attaches their identity to the record the first time they sign in with a verified matching email address.
+
+## Troubleshoot
+
+Your IdP surfaces the status code Airbyte returns. Use these to narrow down the cause.
+
+| Status | Meaning                                                                                                                                                                     |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 400    | Airbyte rejected the request body, an attribute it doesn't support, or an unsupported filter. Trim your IdP's attribute mappings to the supported attributes above.          |
+| 401    | The bearer token is missing, malformed, or no longer valid. This happens after you generate a new token or disable SCIM. Paste the current token into your IdP.              |
+| 403    | SCIM isn't enabled for your organization, or your plan doesn't include it. Contact Airbyte.                                                                                  |
+| 404    | The user or group no longer exists in Airbyte. This is common after someone deletes a group in Airbyte while SCIM was disabled.                                              |
+| 409    | Another record already uses that `userName`, email, `externalId`, or group name. Airbyte also returns this when your IdP tries to create a group that already exists in Airbyte. |
+| 500    | An unexpected Airbyte error. The response includes a reference ID. Send it to [support](https://support.airbyte.com).                                                        |
+
+Other things to check:
+
+- **A user can't be created.** Verify that Airbyte has verified the domain of that user's email address.
+- **One group never provisions.** Your IdP can't take over a group that already exists in Airbyte. Rename or delete the Airbyte group, then let your IdP create it.
+- **Nobody is syncing.** Confirm SCIM is still enabled in **Organization settings** > **SSO**, and that your IdP has the current token and the base URL Airbyte shows there.

docs/platform/access-management/sso-providers/azure-entra-id.md

@@ -146,3 +146,7 @@ If you no longer need a domain for SSO purposes, delete its verification.
 4. Click **Test your connection** to verify the updated credentials work correctly.
 
 5. Click **Activate SSO**. -->
+
+## Optional: Add SCIM provisioning
+
+SCIM is an optional add-on to SSO for organizations that want Entra ID to provision users and groups in Airbyte. SSO works without SCIM. If you want to use SCIM, see [Set up SCIM using Entra ID](../scim-providers/azure-entra-id).