Merge branch '4009-external-users' into 'master'

External Users

The user has the rights of a public user execpt it can never create a project, group, or team. Also it cant view internal projects.

Partially fix for both #4009 and #13938 (except the LDAP sync or a pattern to detect external users)


![Screen_Shot_2016-03-14_at_22.02.52](/uploads/486a84ab3acb98c6cfb71a4ec7d268e2/Screen_Shot_2016-03-14_at_22.02.52.png)

See merge request !3171

3 files changed, 25 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..383e7c76ab0 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
 
@@ -219,6 +220,7 @@ Parameters:
 - `bio`                         - User's biography
 - `admin` (optional)            - User is admin - true or false (default)
 - `can_create_group` (optional) - User can create groups - true or false
+- `external` (optional)         - Flags the user as external - true or false(default)
 
 Note, at the moment this method does only return a 404 error,
 even in cases where a 409 (Conflict) would be more appropriate,
@@ -560,7 +562,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..3d375e47c8e 100644
--- a/doc/permissions/permissions.md
+++ b/doc/permissions/permissions.md
@@ -71,3 +71,24 @@ 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 only to some internal or
+private projects, there is the option of creating **External Users**. This
+feature may be useful when for example a contractor is working on a given
+project and should only have access to that project.
+
+External users can only access projects to which they are explicitly granted
+access, thus hiding all other internal or private ones from them. Access can be
+granted by adding the user as member to the project or group.
+
+They will, like usual users, receive a role in the project or group with all
+the abilities that are mentioned in the table above. They cannot however create
+groups or projects, and they have the same access as logged out users in all
+other cases.
+
+An administrator can flag a user as external [through the API](../api/users.md)
+or by checking the checkbox on the admin panel. As an administrator, navigate
+to **Admin > Users** to create a new user or edit an existing one. There, you
+will find the option to flag the user as external.