User management documentation

docs/concepts/user-management/README.md

@@ -0,0 +1,36 @@
+# 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 out [Login Policies](../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](../user-management/admin.md#slack-integration) for selected [Spaces](../spaces/README.md).
+
+- **Read** - cannot create or modify stacks or any attachable entities, but can view them
+- **Write** - can perform actions like triggering runs, but cannot create or modify Spacelift resources
+- **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.
+
+## IdP group mapping
+
+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 application.
+
+## 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 the **root** space. This badge does not take group or integration permissions into account.
+- **USER** - users without admin permissions to the **root** space.
+
+### Space
+
+The number of spaces that the user has at least read access to. This only takes direct user permissions into account, and does not include permissions inherited from groups.
+
+### 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
+
+The Identity Provider that was used for authenticating the 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. Spacelift invitation is active for 24h. 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 the Identity Provider for your account has changed. The user needs to be invited again and must 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 a pending or expired invite for a given email address already exists.
+
+### 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 the [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 the 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 the [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

@@ -153,11 +153,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 "Create policy" button in the top-right corner.
+### User management
 
-![](<./assets/screenshots/CreatePolicyGS.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 issued and access rules assigned won’t work until you [change user management strategy](concepts/user-management/README.md#migrating-from-login-policy) from login policy to user management.
+
+### Login policy
+
+Another way of adding users to Spacelift is using a login policy.
+
+Go to the "Organization settings" page that can be found in the user dropdown in the bottom of the left sidebar. Once 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.
 
@@ -199,7 +210,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/api.md

@@ -92,36 +92,39 @@ There are currently three ways of obtaining this token:
 
 ### Spacelift API Key > Token
 
-Spacelift supports creating and managing machine users with programmatic access to the Spacelift GraphQL API. These "machine users" are called API Keys and can be created by Spacelift admins through the _Settings_ panel.
+Spacelift supports creating and managing machine users with programmatic access to the Spacelift GraphQL API. These "machine users" are called API Keys and can be created by Spacelift admins through the _Organization settings_ panel.
 
 !!! note
     API keys are **virtual** **users** and are billed like regular users, too. Thus, **each API key used** (exchanged for a token) during any given billing cycle counts against the total number of users.
 
 Steps to create API key in the UI:
 
-Click on Settings in the bottom left corner of the UI
+Click on Organization settings inside user dropdown menu in the bottom left corner of the UI
 
 <p align="center">
-  <img src="../assets/screenshots/api-key-creation-01.png"/>
+  <img src="../assets/screenshots/new-api-create-1.png"/>
 </p>
 
-Choose API Keys menu and click on Add new API key
+Choose API Keys menu and click on Create API key
 
 <p align="center">
-  <img src="../assets/screenshots/api-key-creation-02.png"/>
+  <img src="../assets/screenshots/new-api-create-2.png"/>
 </p>
 
-The API key creation form will allow you to specify an arbitrary key name, along with the _Admin_ setting and the list of _teams_. If the key is given admin privileges, it has full access to the Spacelift API and won't be subject to [access policies](../concepts/policy/stack-access-policy.md).
+The API key creation form will allow you to specify an arbitrary key name, along with the _Space_ access rule setting and the list of _groups_. If the key is given root space access with admin role it have admin privileges, it has full access to the Spacelift API and won't be subject to [access policies](../concepts/policy/stack-access-policy.md).
 
-For non-administrative keys, you may want to add a **virtual** list of teams that the key should "belong to" so that existing access policies based on [GitHub teams](source-control/github.md#team-based-access) or [SAML assertions](single-sign-on/README.md#setting-up-the-integration) can work with your API keys just as they do with regular users.
+!!! warning
+     You can create different space access rules but they won't take effect until you switch to [user management](../concepts/user-management/README.md)
+
+For non-administrative keys, you may want to add a **virtual** list of groups that the key should "belong to" so that existing access policies based on [GitHub teams](source-control/github.md#team-based-access) or [SAML assertions](single-sign-on/README.md#setting-up-the-integration) can work with your API keys just as they do with regular users.
 
 Without further ado, let's create a non-administrative API key with virtual membership in two teams: _Developers_ and _DevOps:_
 
 <p align="center">
-  <img src="../assets/screenshots/api-key-creation-03.png"/>
+  <img src="../assets/screenshots/new-api-create-3.png"/>
 </p>
 
-Once you click the _Add Key_ button, the API Key will be generated and a file will be automatically downloaded. The file contains the API token in two forms - one to be used with our API, and the other one as a `.terraformrc` snippet to access your [private modules](../vendors/terraform/module-registry.md) outside of Spacelift:
+Once you click the _Create_ button, the API Key will be generated and a file will be automatically downloaded. The file contains the API token in two forms - one to be used with our API, and the other one as a `.terraformrc` snippet to access your [private modules](../vendors/terraform/module-registry.md) outside of Spacelift:
 
 <p align="center">
   <img src="../assets/screenshots/api-key-creation-04.png"/>