Doc external users feature

3 files changed, 20 insertions, 2 deletions

diff --git a/doc/README.md b/doc/README.md
index 0ca30e4e0f2..db19c3de8d1 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -8,7 +8,7 @@
 - [Importing to GitLab](workflow/importing/README.md).
 - [Markdown](markdown/markdown.md) GitLab's advanced formatting system.
 - [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab
-- [Permissions](permissions/permissions.md) Learn what each role in a project (guest/reporter/developer/master/owner) can do.
+- [Permissions](permissions/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
 - [Profile Settings](profile/README.md)
 - [Project Services](project_services/project_services.md) Integrate a project with external services, such as CI and chat.
 - [Public access](public_access/public_access.md) Learn how you can allow public and internal access to projects.
diff --git a/doc/api/users.md b/doc/api/users.md
index 82c57a2fd43..44a29da5ecc 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -194,6 +194,7 @@ Parameters:
 - `admin` (optional)            - User is admin - true or false (default)
 - `can_create_group` (optional) - User can create groups - true or false
 - `confirm` (optional)          - Require confirmation - true (default) or false
+- `external` (optional)         - Flags the user as external - true or false(default)
 
 ## User modification
 
@@ -560,7 +561,7 @@ Parameters:
 
 - `uid` (required) - id of specified user
 
-Will return `200 OK` on success, `404 User Not Found` is user cannot be found or 
+Will return `200 OK` on success, `404 User Not Found` is user cannot be found or
 `403 Forbidden` when trying to block an already blocked user by LDAP synchronization.
 
 ## Unblock user
diff --git a/doc/permissions/permissions.md b/doc/permissions/permissions.md
index ac0fd3d1756..2dfd08755ba 100644
--- a/doc/permissions/permissions.md
+++ b/doc/permissions/permissions.md
@@ -71,3 +71,20 @@ Any user can remove themselves from a group, unless they are the last Owner of t
 | Create project in group |       |          |           | ✓      | ✓     |
 | Manage group members    |       |          |           |        | ✓     |
 | Remove group            |       |          |           |        | ✓     |
+
+## External Users
+
+In cases where it is desired that a user has access to some internal or private projects, but others
+should remain hidden from this user, there is the option of creating `External Users`.
+An administrator can flag a user as external through the API or by checking the checkbox on the admin panel.
+
+In the case of a new user: navigate to the **Admin** area and click the **New User** button. If you would like to
+edit a user, go to the user list on the **Admin** area and click the **Edit** button.
+
+External users can only access projects to which they are explicitly granted access, thus hiding all internal projects.
+Access can be granted by adding the users as member to the project or by including this user in a group. External users will, like usual users, receive
+a role in the project or group with all the abilities that are mentioned in the table above.
+
+External users cannot create groups or projects, and have the same access as logged out users in all other cases. This feature may be
+useful when for example a contractor is working on a given project and should only access the given project and public
+projects.