Update SCIM documentation with role mapping details

docs/v3/how-to-guides/cloud/manage-users/configure-sso.mdx

@@ -47,5 +47,54 @@ Prefect Cloud resources. This allows your IT team to control access to Prefect C
 
 ## SCIM Provisioning
 
-Enterprise plans have access to SCIM for user provisioning.
-The SSO tab provides access to enable SCIM provisioning.
+Enterprise plans have access to SCIM (System for Cross-domain Identity Management) for automated user and team provisioning.
+
+SCIM enables automatic provisioning and de-provisioning of users and teams based on your identity provider's directory.
+When users are added, removed, or have their group memberships changed in your identity provider, these changes are
+automatically reflected in Prefect Cloud.
+
+### Enable SCIM provisioning
+
+The SSO tab provides access to enable SCIM provisioning for your account.
+
+### Role mapping
+
+SCIM supports role mapping, which allows you to automatically assign Prefect Cloud account roles based on directory
+group memberships configured in your identity provider.
+
+#### Account roles
+
+Directory groups can be mapped to the following Prefect Cloud account roles:
+
+- **Owner**: Full account control including billing and account management
+- **Admin**: Account management capabilities, can invite users and manage workspaces
+- **Member**: Basic account access with workspace-level permissions
+
+#### Configure role mapping
+
+Role mapping is configured in your WorkOS organization dashboard:
+
+1. Navigate to your WorkOS dashboard
+2. Select your organization
+3. Go to Directory Sync settings
+4. Click "Configure role assignment"
+5. Map your identity provider groups to Prefect Cloud roles
+
+When role mapping is configured:
+- New users automatically receive the appropriate role based on their group memberships
+- Users with multiple group memberships receive the role with the highest priority
+- Users not in any mapped group receive the default "Member" role
+- Role changes in your identity provider are reflected in Prefect Cloud automatically
+
+#### Team management
+
+Directory groups are automatically synchronized as teams in Prefect Cloud. See [Teams](/v3/how-to-guides/cloud/manage-users/manage-teams/)
+for more information about SCIM team management.
+
+### Supported operations
+
+SCIM provisioning supports the following operations:
+- **User provisioning**: Automatic creation and updates of user accounts
+- **User deprovisioning**: Automatic removal of user access when removed from the directory
+- **Group/team synchronization**: Automatic creation and management of teams based on directory groups
+- **Role assignment**: Automatic role assignment based on group memberships

docs/v3/how-to-guides/cloud/manage-users/index.mdx

@@ -42,7 +42,7 @@ Prefect Cloud API key that is not associated with a user account.
 
 Enterprise tier plans offer [single sign-on (SSO)](/v3/how-to-guides/cloud/manage-users/configure-sso/)
 integration with your team's identity provider, including options for
-[directory sync and SCIM provisioning](/v3/how-to-guides/cloud/manage-users/configure-sso/#directory-sync).
+[directory sync and SCIM provisioning](/v3/how-to-guides/cloud/manage-users/configure-sso/#scim-provisioning).
 
 ## Audit log (Pro) (Enterprise)
 

docs/v3/how-to-guides/cloud/manage-users/manage-teams.mdx

@@ -10,7 +10,28 @@ Account Admins can configure teams and team membership from the account settings
 Teams are composed of users and service accounts.
 Teams can be added to workspaces or object access control lists just like users and service accounts.
 
-If SCIM is enabled on your account, the set of teams and the users within them is governed by your IDP.
-Prefect Cloud service accounts, which are not governed by your IDP, can be still be added to your existing set of teams.
+## SCIM team management
+
+If SCIM is enabled on your account, teams and team memberships are automatically managed by your identity provider.
+
+### Automatic team creation
+
+When SCIM is enabled:
+- Directory groups from your identity provider are automatically synchronized as teams in Prefect Cloud
+- Teams are created with the same name as the directory group
+- Team names are updated automatically if changed in the identity provider
+
+### Automatic membership management
+
+Team memberships are automatically managed based on directory group memberships:
+- Users added to a directory group automatically become team members in Prefect Cloud
+- Users removed from a directory group automatically lose team membership
+- Changes are synchronized in real-time when your identity provider sends SCIM events
+
+### Service accounts
+
+Prefect Cloud service accounts are not governed by your identity provider and can still be manually added to teams.
+Service accounts provide a way to access Prefect Cloud programmatically without requiring individual user credentials.
+
 
 See the [Prefect Cloud plans](https://www.prefect.io/pricing) to learn more about options for supporting teams.