Adding user auto-provisioning & SCIM API sections to server manage us…

…ers page, and making other small updates based on current positioning

docs/guides/hosting/manage-users.md

@@ -4,42 +4,59 @@ displayed_sidebar: default
 # Manage users
 Manage W&B users in your organization or team.
 
-:::info
-Users are classified as either an _admin_ or _member_. Admins can add and remove other admins or members.
-:::
+W&B strongly recommends and encourages that users authenticate to an enterprise W&B Server instance using Single Sign-On (SSO). To learn more about how to setup SSO with W&B Server, refer to the [SSO Configuration documentation](./sso.md).
 
-W&B strongly recommends and encourages user management with Single Sign-On (SSO). To learn more about how to setup SSO with W&B Server, refer to the [SSO Configuration documentation](./sso.md).
+:::note
+Whenever you see a mention of `W&B Server`, it refers to both **Dedicated Cloud** or **Self-managed** hosting options.
+:::
 
+:::note
+When you see the the mention of `instance` or `organization`, they currently mean one and the same thing in the context of W&B Server. 
 
+We are working to add the support for multiple organizations in an enterprise instance of W&B Server. If you're interested in utilizing that capability, reach out to your W&B team.
+:::
 
 ## Instance Admins
+The first user to sign up after the W&B Server instance is initially deployed, is automatically assigned the instance `admin` role. The admin can then add additional users to the organization and create teams.
 
-The first user to sign up to W&B, after you have deployed the W&B Server, is automatically assigned admin permissions. The admin can then add additional users to the instance and create teams.
 ## Manage your organization
-As an admin, you can invite, remove, and change a user's role. To do so, navigate to the Organization dashboard and follow the instructions described below.
+As an instance admin, you can invite, remove, and change a user's role. To do so, navigate to the Organization dashboard and follow the instructions described below.
 
 1. Select your profile image in the upper right hand corner.
 2. A dropdown will appear, click on **Organization dashboard**.
 
 ![](/images/hosting/how_get_to_dashboard.png)
 
 ### Invite users
-
 1. Navigate to the W&B Organization dashboard.
 2. Click the **Add user** button.
 3. Add the user's email in the Email field.
-4. Select the user role type you want to apply to the user. By default, all users are assigned a Member role.
+4. Select the role you want to assign to the user, from `Admin, Member or Viewer`. By default, all users are assigned a `Member` role.
+    - Admin: A instance admin who can add or remove other users to the organization, change user roles, manage custom roles, add teams and more. W&B recommends more than one admin for an enterprise W&B server instance.
+    - Member - A regular user of the organization, invited by an instance admin. A organization user cannot invite other users or manage existing users in the organization. `Team admins` could add specific organization users to their respective teams (team-level roles described below in **Team roles**).
+    - Viewer - A view-only user of your organization, invited by an instance admin. A viewer only has read access to the organization and the underlying teams that they are added to by the respective `Team admins`.
 5. Click the **Add new user** button.
 
 ![](/images/hosting/org_dashboard_add_user.png)
 
+An invite link will be sent to the user by email. Once the user accepts the invite, they will have access to the W&B instance (organization).
+
 :::info
-Note that an option may be greyed out if there are no more seats in the license.
+Note that the add user option may be greyed out if there are no more seats in the license. Reach out to your W&B team in such a case.
 :::
 
-An invite link will be sent to the user by email. The new admin or member will now have access to the W&B instance.
+:::note
+W&B uses a third-party email server to send the user invites. If you've a self-managed W&B Server instance and your organization firewall rules restrict sending traffic outside the corporate network, W&B provides an option to configure an internal SMTP server in the instance. Please refer to [these instructions](./smtp.md) to setup the SMTP server.
+:::
 
-W&B uses third-party email server to send these invite emails. If your organization firewall rules prohibit from sending traffic outside the corporate network, W&B provides an option to set up internal SMTP server. Please refer to [these instructions](./smtp.md) to setup the SMTP server.
+### User auto-provisioning
+If Single Sign-On (SSO) is setup for your enterprise W&B Server instance, any user in your company who has access to the instance URL can sign-in to the organization, provided the settings in your SSO provider allow so. When a user signs in for the first time using SSO, their W&B organization user will be automatically created without needing an instance admin to generate a user invite. This is a good alternative for adding users to your W&B organization at scale.
+
+User auto-provisioning with SSO is turned on by default for W&B Server. It is possible to turn it `off` if you would like to selectively add specific users to your W&B organization. If you're on **Dedicated Cloud**, reach out to your W&B team. If you've a **Self-managed** deployment, you can configure the setting `DISABLE_SSO_PROVISIONING=true` for your W&B Server instance.
+
+:::note
+If auto-provisioning is on for your W&B Server instance, there may be a way to control which specific users can sign-in to the organization with your SSO provider to restrict the product use to relevant personnel. Extent of that configurability will depend on your SSO provider and is outside the scope of W&B documentation.
+:::
 
 ### Remove a user
 1. Navigate to the W&B Organization dashboard.
@@ -49,27 +66,22 @@ W&B uses third-party email server to send these invite emails. If your organizat
 
 ![](/images/hosting/remove_user_from_org.png)
 
-### Change a user's role
-
+### Change a user's organization-level role
 1. Navigate to the W&B Organization dashboard.
 2. Search for the user you want to modify in the search bar.
 3. Hover your mouse to the **Role** column. Click on the pencil icon that appears.
-4. From the dropdown, select the new role you want to assign.
-
-
-
+4. From the dropdown, select a different role you want to assign.
 
 ## Manage a team
-Use a team home page as a central hub to explore projects, reports, and runs. Within the team home page there is a **Settings** tab. Use the Settings tab to manage members, set a team avatar, adjust privacy settings, set up alerts, track usage, and more. For more information, see the [Team settings](../app/settings-page/team-settings.md) page.
+Use a team home page as a central hub to explore projects, reports, and runs. Within the team home page there is a **Settings** tab. Use the Settings tab to manage users, set a team avatar, adjust privacy settings, set up alerts, track usage, and more. For more information, see the [Team settings](../app/settings-page/team-settings.md) page.
 
 :::tip
-Admins can add and remove team members. A team member is invited by email by the team admin. A team member cannot invite other members.
+Team admins can add and remove users in their teams. A user is invited to a team using email or their organization-level username by the respective team admin. A non-admin user in a team cannot invite other users to that team.
 
-For more information on team roles and permissions, [see Team Roles and Permissions](../app/features/teams.md#team-roles-and-permissions).
+See **Team roles** below for what roles are available at the team-level.
 :::
 
 ### Create a team
-
 1. Navigate to the W&B Organization dashboard.
 2. Select the **Create new team** button on the left navigation panel.
 ![](/images/hosting/create_new_team.png)
@@ -80,13 +92,13 @@ For more information on team roles and permissions, [see Team Roles and Permissi
 This will redirect you to a newly created Team home page. 
 
 ### Team roles
-When you invite a user to a team you can assign them one of the following roles:
+When you (team admin) invite a user to a team you can assign them one of the following roles:
 
 | Role      | Definition                                                                                                                                                                                                                                                                                       |
 |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Admin     | A team member who can add and remove other admins and members of the team.                                                                                                                                                                                                                       |
-| Member    | A regular member of your team, invited by email by the team admin. A team member cannot invite other members to the team.                                                                                                                                                                        |
-| View-Only (Enterprise-only feature) | A view-only member of your team, invited by email by the team admin. A view-only member only has read access to the team and its contents.                                                                                                                                                       |
+| Admin     | A user who can add and remove other users in the team, change user roles, and configure team settings.                                                                                                                                                                                                                       |
+| Member    | A regular user of a team, invited by email or their organization-level username by the team admin. A member user cannot invite other users to the team.                                                                                                                                                                        |
+| View-Only (Enterprise-only feature) | A view-only user of a team, invited by email or their organization-level username by the team admin. A view-only user only has read access to the team and its contents.                                                                                                                                                       |
 | Service (Enterprise-only feature)   | A service worker or service account is an API key that is useful for utilizing W&B with your run automation tools. If you use an API key from a service account for your team, ensure that the environment variable `WANDB_USERNAME` is set to correctly attribute runs to the appropriate user. |
 | Custom Roles (Enterprise-only feature)   | Custom roles allow organization admins to compose new roles by inheriting from the above View-Only or Member roles, and adding additional permissions to achieve fine-grained access control. Team admins can then assign any of those custom roles to users in their respective teams. Refer to [this article](https://wandb.ai/wandb_fc/announcements/reports/Introducing-Custom-Roles-for-W-B-Teams--Vmlldzo2MTMxMjQ3) for details. |
 
@@ -98,41 +110,56 @@ Refer to [Team Service Account Behavior](../app/features/teams.md#team-service-a
 If you're on W&B Server (Dedicated Cloud or Self-managed deployment), you will need an updated enterprise license to use the **Custom Roles** feature.
 :::
 
-### Invite members to a team
-Use the Team's settings page to invite members.
+### Invite users to a team
+Use the Team's settings page to invite users to your team.
 
 :::info
-Members must first be part of the instance before they can be invited to a team.
+If a user is not already a part of the organization when being added to a team, they will be automatically added at the organization-level as well.
 :::
 
 1. Navigate to the Team's Settings page.
 2. Select the **Members** tab.
 3. Enter an email or W&B username in the search bar.
 4. Once you have found the user, click the **Invite** button.
 
+### Remove users from a team
+Use the Team's settings page to remove users from your team.
 
-### Remove members from a team
+1. Navigate to the Team's settings page.
+2. Select the Delete button next the to user's name.
 
-Use the Team's settings page to remove members.
+:::info
+W&B runs logged by team users remain after a team user is removed.
+:::
 
-1. Navigate to the Team's settings page.
-2. Select the Delete button next the to member's name.
+## SCIM API
+User management within a W&B organization and its underlying teams can be done in a more efficient and repeatable way using the [SCIM API](./scim.md). It is especially useful when managing user provisioning & de-provisioning at scale, or when looking to do so from a [SCIM](https://scim.cloud/)-supporting Identity Provider. There are broadly two categories of SCIM API - **User** and **Group**.
+
+### User SCIM API
+[User SCIM API](./scim.md#user-resource) allows for creating, disabling or getting the details of a user (or listing all users) in a W&B organization.
 
 :::info
-W&B runs logged by team members remain after a team member is removed.
+With the `DELETE User` endpoint, the user is disabled in the W&B organization such that they are not able to sign-in anymore, but they are still shown in the user list. To fully remove a disabled user from the user list, you must [remove the user from the oganization](#remove-a-user).
+
+It's not possible to re-enable a disabled user directly. Remove the user completely, and then add them again using the invite or auto-provisioning flows.
 :::
 
+### Group SCIM API
+[Group SCIM API](./scim.md#group-resource) allows for creating or removing a W&B team in a organization. The `PATCH Group` endpoint can be used to **add** or **remove** users in an existing team.
+
+:::info
+There's no notion of a `group of users` having the same role within W&B Server yet. A W&B team closely resembles a group, but it should rather be seen as a mechanism that allows a mix of diverse personas with different roles work collaboratively on a set of related projects. So in a way, a team is meant to be comprised of different groups of users with each group assigned the roles of team admins, members, viewers, and custom roles. Due to this resemblance, The Group SCIM API endpoints map to W&B teams.
+:::
 
 ## View organization usage of W&B
-Use the organization dashboard to get a holistic view of members that belong to your organization, how members of your organization use W&B, along with properties such as:
+Use the organization dashboard to get a holistic view of users that belong to your organization, how users of your organization use W&B, along with properties such as:
 
 * **Name**: The name of the user and their W&B username.
 * **Last active**: The time the user last used W&B. This includes any activity that requires authentication, including viewing pages in the product, logging runs or taking any other action, or logging in.
 * **Role**: The role of the user. 
 * **Email**: The email of the user.
 * **Team**: The names of teams the user belongs to.
 
-
 ### View the status of a user
 The **Last Active** column shows if a user is pending an invitation or an active user.  A user is one of three states:
 
@@ -145,7 +172,6 @@ The **Last Active** column shows if a user is pending an invitation or an active
 The **Role** column will display **Deactivated** if a user was deactivated. 
 
 ### View and share how your organization uses W&B
-
 View how your organization uses W&B in CSV format.
 
 1. Select the three dots next to the **Add user** button.