User management documentation

docs/concepts/user-management/README.md

@@ -0,0 +1,42 @@
+# User Management
+
+Spacelift is made for collaboration. In order to collaborate, you need collaborators. User Management is an easy way to invite new members to your organization and manage their permissions, together with third-party integrations and group access. If you prefer to write a policy rather than using our UI, please check [Login Policy](../policy/login-policy.md).
+
+!!! warning
+    User Management doesn't affect GitHub organization or [SSO](../../integrations/single-sign-on/README.md) admins and private account owners who always get admin access to their respective Spacelift accounts. This is to avoid a situation where a mistake in User Management locks out everyone from the account.
+
+## Roles
+
+User Management works by setting one of the following roles for users, groups and integrations for selected [Spaces](../spaces/README.md).
+
+- **Read** - cannot create or modify neither stacks nor any attachable entities, but can view them
+- **Write** - an extension to Read, as it can trigger runs in the stacks it sees
+- **Admin** - can create and modify stacks and attachable entities, as well as trigger runs
+
+## User
+
+Users are individuals invited through their email and authenticated using your account's Identity Provider. Users can have personal permissions assigned.
+
+## Group
+
+Group is a group of users as provided by your Identity Provider. If you assign permissions to a Group, all users that your Identity Provider reports as being members of a given group will have the same access, unless the user's permissions are higher than the ones they would get from being a member of a Group.
+
+## Invitation process
+
+New users can be invited through email by account admins and owners. Detailed instructions can be found on [the Admin page](admin.md) of this documentation.
+
+Once a user is invited, they will receive an email from Spacelift that will take them to your identity provider page.
+
+![invitation email containing a button to accept the invitation](<../../assets/screenshots/user-management/invitation-email.png>)
+
+Once the user authenticates with your identity provider, they will be redirected to a landing page that asks for a confirmation code sent to their email.
+
+![confirmation code landing page with an input box for confirmation code](<../../assets/screenshots/user-management/confirmation-landing.png>)
+
+Alternatively, instead of typing the code manually, the user can click the button found in the confirmation code email to confirm the email address ownership.
+
+![confirmation code email with confirmation code and button to confirm email address ownership](<../../assets/screenshots/user-management/confirmation-email.png>)
+
+## Migrating from Login Policy
+
+If you were previously using [Login Policy](../policy/login-policy.md) you can queue invites to User Management for your users while still having Login Policy enabled. Once you switch to the User Management strategy, the invites will be sent to your users' emails and allow them to sign in through your Identity Provider. Remember, that you can always go back if it turns out something was misconfigured.

docs/concepts/user-management/admin.md

@@ -0,0 +1,84 @@
+# Admin / Owner
+
+Users with **Owner** and **root Admin** roles have access to **Organization settings**. This means they can manage access for the rest of the collaborators within your Spacelift account. The following article details the configuration options and user invitation procedures available to them.
+
+## Access settings
+
+Access settings can be found by clicking the button in the lower-left corner with your avatar and selecting **Organization settings**.
+
+## Select your Management Strategy
+
+Account administrators can choose between User management and Login policy strategies in **Management strategy** tab. Once selected, the rules from the other strategy no longer apply.
+
+!!! warning
+    Strategy selection does not affect GitHub organization or [SSO](../../integrations/single-sign-on/README.md) admins and private account owners who always get admin access to their respective Spacelift accounts. This is to avoid a situation where a bad management strategy locks out everyone from the account.
+
+!!! danger
+    Changing your Management Strategy will invalidate all active sessions, except the session making the change.
+
+## Users
+
+The user list can be accessed by selecting **Users** tab in the left drawer.
+
+The user list consists of all individuals who have or had access to your account through the User Management access strategy.
+
+Below is a longer description of fields that we believe might not be obvious at first glance.
+
+### Role
+
+The displayed Role badge is different than the space access role. It describes the user's role within the organization, instead of specific space permissions. This badge can have one of three values:
+
+- **OWNER** - account admin, SSO admin or GitHub organization being the owner of an account.
+- **ADMIN** - a user who has direct admin permissions to **root** space. This badge does not take group or integration permissions into account.
+- **USER** - users without admin permissions to **root** space.
+
+### Space
+
+The number of spaces that the user has direct permission to read (or more). Does not take Groups into account.
+
+### Group
+
+The number of groups that the user was a member of during the last login, as reported by the account's Identity Provider.
+
+### Login method
+
+Identity Provider that was used for authenticating given user. It will usually be the same as the account's current Identity Provider, but on a rare occasion that Identity Provider changes, this will allow for auditing old access or transferring permissions to users within the new Identity Provider.
+
+### Status
+
+- **QUEUED** - user invitation was issued and will be sent once Management Strategy is changed from Login Policy to User Management
+- **PENDING** - user invitation was sent and can be accepted or the user still needs to confirm their ownership of the invitation email with a code found in the confirmation code email.
+- **EXPIRED** - user invitation was sent, but the user did not accept it before it expired. A new invitation must be issued for a user to be able to access your Spacelift account.
+- **ACTIVE** - user has accepted an invitation to your Spacelift account and has permissions set in User Management as long as User Management is the selected access strategy.
+- **INACTIVE** - the user was previously able to access your Spacelift account, but Identity Provider changed and so this user needs to be invited again and login through the new Identity Provider to continue using Spacelift.
+
+## Inviting new users
+
+To invite new users to your account, click on the 'Invite user' button located in the top right corner. You will be able to send them an email invitation link and determine their access level during the invitation process.
+
+### Resending user invitation
+
+If a user did not receive an invitation email or their invitation has expired, you can select **Resend invite** from the three dots menu. Issuing a new invite is not possible if there already exists a pending or expired invite for a given email address.
+
+### Revoking user invitation
+
+At any time you can revoke a user invitation by choosing **Revoke invite** from the three dots menu. Once the invitation is revoked, it will no longer allow user access to your account. If you wish to invite a user with a given email at a later date, you can issue a new invitation.
+
+## Managing user access
+
+You can manage access rules for anyone who logs into your account by selecting the **Access details** option from the three dots menu.
+
+### Slack integration
+
+After setting up [Slack integration](../../integrations/chatops/slack.md), you can provide the user's Slack ID to give them the same permissions when interacting through Slack as they would have when interacting through the Spacelift website.
+
+## IdP group mapping
+
+Groups are reported by your Identity Provider for each user during authentication. You can add permissions to those groups that will be honored inside Spacelift. To do that, go to **IdP group mapping** tab and click **Map IdP group**. Then select appropriate Spaces and Roles the same way you would for a single User.
+
+!!! warning
+    Group permissions will only be applied to the user if the group name in Spacelift exactly matches the group name in your Identity Provider including capital letters and whitespaces.
+
+### Slack integration
+
+After setting up [Slack integration](../../integrations/chatops/slack.md) you can also grant permissions to entire Slack channels after selecting **Integrations** tab and clicking **Manage access** button in Slack card. You can input a human-readable name along the Slack channel ID. You can then add Space permissions the same way you would for Users and Groups.

docs/concepts/user-management/user.md

@@ -0,0 +1,21 @@
+# User
+
+We consider **Users** to be all entities that can access Spacelift through the account's Identity Provider after going through the invitation flow, as described on the [User Management page](README.md).
+
+## Access settings
+
+Access settings can be found by clicking the button in the lower-left corner with your avatar and selecting **Personal settings**.
+
+## Requesting an invitation
+
+If a user wants another user to be invited, they can use **Collaborate with your team** banner, to request an invitation for a specified email address. This request will be delivered to account owners and admins to evaluate the request.
+
+## Spaces
+
+This page displays a list of spaces the user has access to, along with the role user has within that spaces. The list of roles and their descriptions can be found on the [User Management page](README.md).
+
+In addition to displaying existing permissions, the user can request a role change for a space they have access to, either directly or by inheritance, by clicking **Request role change** button to the left of desired space. You can read more about [Spaces](../spaces/README.md) and [Access Control](../spaces/access-control.md) in linked articles from this documentation.
+
+## Groups
+
+A list of Groups reported by the Identity Provider on the most recent login will be displayed in this list.

docs/getting-started.md

@@ -149,11 +149,22 @@ Now it is time to add other users to your Spacelift account.
 
 Now comes the moment when you want to show Spacelift to your colleagues. There are a few different ways to grant users access to your Spacelift account but in the beginning, we are going to add them as single users.
 
-Go to the "Policies" page that can be found on the left sidebar and click the "Add policy" button in the top-right corner.
+### User management
 
-![](./assets/screenshots/add-policy.png)
+Using [user management](concepts/user-management/README.md) is the simplest way to invite new users to Spacelift. You can follow the invitation process as described [here](concepts/user-management/README.md#invitation-process).
 
-Name the policy and select "Login policy" as the type.
+!!! note
+    It's important to know that all invites sent and access rules assigned won’t work until you [change management](concepts/user-management/README.md#migrating-from-login-policy) strategy from login policy to user management.
+
+### Login policy
+
+Another way of adding users to Spacelift is using login policy.
+
+Go to the "Organization settings" page that can be found in the user dropdown in the bottom of the left sidebar. Once you there, choose "Login policy" from settings menu and click the "Create policy" button in the top-right corner.
+
+![](./assets/screenshots/creating-login-policy.png)
+
+Name the policy and click "Continue" button.
 
 Then copy/paste and edit the example below that matches the identity provider you used to sign up for the Spacelift account.
 
@@ -195,7 +206,7 @@ Now your colleagues should be able to access your Spacelift account as well!
 !!! note
     While the approach above is fine to get started and try Spacelift, granting access to individuals is less safe than granting access to teams and restricting access to account members. In the latter case, when they lose access to your organization, they automatically lose access to Spacelift while when whitelisting individuals and not restricting access to members only, you'll need to remember to explicitly remove them from your Spacelift Login policy, too.
 
-    Before you go live in production with Spacelift, we recommend that you switch to using teams in [Login policies](./concepts/policy/login-policy.md) and consider configuring the [Single Sign-On (SSO) integration](./integrations/single-sign-on/README.md), if applicable.
+    Before you go live in production with Spacelift, we recommend that you switch to using teams in [Login policies](./concepts/policy/login-policy.md) or [User management](./concepts/user-management/admin.md#idp-group-mappingE.md), if applicable.
 
 ## Additional Reading
 

docs/integrations/chatops/slack.md

@@ -14,41 +14,39 @@ Here are examples of messages the Spacelift application sends to Slack;
 
 ## Linking your Spacelift account to the Slack workspace
 
-As a Spacelift and Slack admin, you can link your Spacelift account to the Slack workspace by going to the _Slack_ section of the _Settings_ screen.
+As a Spacelift and Slack admin, you can link your Spacelift account to the Slack workspace by going to the _Integrations_ section of the _Organization settings_ screen.
 
-The integration is an OAuth2 exchange which installs Slack Spacelift app in your workspace.
+The Slack integration is an OAuth2 exchange which installs Slack Spacelift app in your workspace.
 
-Once you install the Spacelift app, the account-level integration is finished and the _Slack_ section of the _Settings_ screen informs you that the two are talking to one another:
+Once you install the Spacelift app, the account-level integration is finished and the _Slack_ of the _Integrations_ screen informs you that the two are talking to one another:
 
-![](../../assets/screenshots/Mouse_Highlight_Overlay_and_Slack_integration_·_spacelift-io.png)
+![](../../assets/screenshots/slack-integration.png)
 
 Installing the Slack app doesn't automatically cause Spacelift to flood your Slack channels with torrents of notifications. These are set up on a per-stack basis using [Slack commands](slack.md#available-commands) and the management uses the Slack interface.
 
 Though before that happens, you need to allow requests coming from Slack to access Spacelift stacks.
 
-## Managing access to Stacks with policies
+## Managing access to Stacks
 
 Our Slack integration allows users in the Slack workspace to interact with stacks by adding the ability
 to change their run state or view changes that are planned or were applied.
 
-Similar to regular requests to our HTTP APIs, requests and actions coming from Slack are subject to the policy-based access validation. If you haven't had a chance to review the [policy](../../concepts/policy/README.md) and [Spaces](../../concepts/spaces/README.md) documentation yet, please do it now before proceeding any further - you're risking a chance of getting lost.
-
 ### Available actions
 
 Currently, we allow:
 
 - Confirming and discarding tracked runs.
 - Viewing planned and actual changes.
 
-Both of these actions require specific permissions to be configured using the login policy.
+Both of these actions require specific permissions to be configured using the login policy or granted via Slack manage access view.
 Confirming or discarding runs requires _Write_ level permissions while viewing changes requires _Read_ level permissions. The documentation sections about policies below describe how to setup and manage these permissions.
 
 !!! info
     The default login policy decision for Slack requests is to deny all access.
 
 ### Login policy
 
-Using [login policies](../../concepts/policy/login-policy.md) is the preferred way to control access for the Slack integration. Using them you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md).
+Using [login policies](../../concepts/policy/login-policy.md) is the first way to control access for the Slack integration. Using them you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md).
 
 They allow for granular space access control using the provided policy data such as slack workspace details, Slack team information and user which interacted with the message data. Using the Login policy you can define rules which
 would allow to have _Read_ or _Write_ level permissions for certain actions.
@@ -143,6 +141,19 @@ space_write["Y"] {
 }
 ```
 
+### Manage Slack access page
+
+Using Manage Slack access page is another way to control access for the Slack integration. Using this method you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md) and based that access on specific Slack channel.
+
+!!! warning
+    It's important to know that all access rules assigned won’t work until you [change management](../../concepts/user-management/README.md#migrating-from-login-policy) strategy from login policy to user management.
+
+To manage slack access as account admin you should go to _Organization Settings_ _Integrations_ section and click on _Manage access_ button on _Slack_ card.
+
+You can than add new access rule by clicking _Grant access_ button and filling out the form.
+
+![](../../assets/screenshots/slack-access-form.png)
+
 ## Available slash commands
 
 !!! warning

nav.yaml

@@ -53,6 +53,10 @@ nav:
           - concepts/spaces/deleting-a-space.md
           - concepts/spaces/structuring-your-spaces-tree.md
           - concepts/spaces/migrating-out-of-the-legacy-space.md
+      - User Management:
+          - concepts/user-management/README.md
+          - concepts/user-management/admin.md
+          - concepts/user-management/user.md
       - concepts/vcs-agent-pools.md
   - 🛰️ Platforms:
       - Terraform: