Merge branch 'bvl-ext-auth-docs' into 'master'

Add documentation for external authorization

See merge request gitlab-org/gitlab-ee!4977

doc/administration/index.md

@@ -47,6 +47,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 [source installations](../install/installation.md#installation-from-source).
 - [Environment variables](environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab.
 - **(Starter/Premium)** [Elasticsearch](../integration/elasticsearch.md): Enable Elasticsearch to empower GitLab's Advanced Global Search. Useful when you deal with a huge amount of data.
+- **(Premium)** [External Classification Policy Authorization](../user/admin_area/settings/external_authorization.md)
 
 #### Customizing GitLab's appearance
 

doc/api/settings.md

@@ -170,6 +170,9 @@ PUT /application/settings
 | `user_default_external`                  | boolean          | no                                            | Newly registered users will by default be external                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `user_oauth_applications`                | boolean          | no                                            | Allow users to register any application to use GitLab as an OAuth provider                                                                                                                                                                                                                                                                                                                                                                                |
 | `version_check_enabled`                  | boolean          | no                                            | Let GitLab inform you when an update is available.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `external_authorization_service_enabled` | boolean | no | Enable using an external authorization service for accessing projects |
+| `external_authorization_service_url` | string | no | URL to which authorization requests will be directed |
+| `external_authorization_service_default_label` | string | no | The default classification label to use when requesting authorization and no classification label has been specified on the project |
 
 ```bash
 curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal
@@ -207,6 +210,9 @@ Example response:
   "plantuml_enabled": false,
   "plantuml_url": null,
   "terminal_max_session_time": 0,
-  "polling_interval_multiplier": 1.0
+  "polling_interval_multiplier": 1.0,
+  "external_authorization_service_enabled": true,
+  "external_authorization_service_url": "https://authorize.me",
+  "external_authorization_service_default_label": "default"
 }
 ```

doc/user/admin_area/settings/external_authorization.md

+# External authorization control
+
+>
+[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in
+[GitLab Premium](https://about.gitlab.com/pricing) 10.6.
+
+In highly controlled environments, it may be necessary for access policy to be
+controlled by an external service that permits access based on project
+classification and user access. GitLab provides a way to check project
+authorization with your own defined service.
+
+## Overview
+
+Once the external service is configured and enabled, when a project is accessed,
+a request is made to the external service with the user information and project
+classification label assigned to the project. When the service replies with a
+known response, the result is cached for 6 hours.
+
+If the external authorization is enabled, GitLab will further block pages and
+functionality that render cross-project data. That includes:
+
+- most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge
+  requests, Assigned issues, Todos)
+- under a specific group (Activity, Contribution analytics, Issues, Issue boards,
+  Labels, Milestones, Merge requests)
+- Global and Group search will be disabled
+
+This is to prevent performing to many requests at once to the external
+authorization service.
+
+## Configuration
+
+The external authorization service can be enabled by an admin on the GitLab's
+admin area under the settings page:
+
+![Enable external authorization service](img/external_authorization_service_settings.png)
+
+The available required properties are:
+
+- **Service URL**: The URL to make authorization requests to
+- **Default classification label**: The classification label to use when
+  requesting authorization if no specific label is defined on the project
+
+## How it works
+
+When GitLab requests access, it will send a JSON POST request to the external
+service with this body:
+
+```json
+{
+  "user_identifier": "jane@acme.org",
+  "project_classification_label": "project-label",
+  "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme"
+}
+```
+
+The `user_ldap_dn` is optional and is only sent when the user is logged in
+through LDAP.
+
+When the external authorization service responds with a status code 200, the
+user is granted access. When the external service responds with a status code
+401, the user is denied access. In any case, the request is cached for 6 hours.
+
+When denying access, a `reason` can be optionally specified in the JSON body:
+
+```json
+{
+  "reason": "You are not allowed access to this project."
+}
+```
+
+Any other status code than 401 or 200 will also deny access to the user, but the
+response will not be cached.
+
+If the service times out (after 500ms), a message "External Policy Server did
+not respond" will be displayed.
+
+## Classification labels
+
+You can use your own classification label in the project's
+**Settings > General > General project settings** page in the "Classification
+label" box. When no classification label is specified on a project, the default
+label defined in the [global settings](#configuration) will be used.
+
+The label will be shown on all project pages in the upper right corner.
+
+![classification label on project page](img/classification_label_on_project_page.png)

ee/app/views/admin/application_settings/_external_authorization_service_form.html.haml

@@ -11,7 +11,7 @@
         %span.help-block
           If enabled, access to projects will be validated on an external service
           using their classification label.
-          = link_to icon('question-circle'), help_page_path('#')
+          = link_to icon('question-circle'), help_page_path('user/admin_area/settings/external_authorization')
     .form-group
       = f.label :external_authorization_service_url, _('Service URL'), class: 'control-label col-sm-2'
       .col-sm-10