Add documentation for external authorization

doc/administration/external_authorization.md

+# External authorization service
+
+ > [Introduced][ee-3709] GitLab Enterprise Edition 10.6.
+
+ To provide more granular access control GitLab provides a way to check project
+ authorization with an external service.
+
+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.
+
+Enabeling this feature disables all cross project features in GitLab: This is to
+prevent performing to many requests at once to the external authorization
+service.
+
+## Enabling external authorization service
+
+The external authorization service can be enabled by an admin on the settings
+page:
+
+![Enable external authorization service](img/external_authorization_service_settings.png)
+
+The available 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.
+
+## The external authorization service
+
+### The request
+
+When GitLab requests access, it will send a JSON POST request 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, it is only sent when the user is logged in
+through LDAP.
+
+### The response
+
+#### Access allowed
+
+When the external authorization service responds with a status code 200, the
+user is granted access and the result is cached for 6 hours.
+
+#### Denying access
+
+When the external service responds with a status code 401, the user is denied
+access and the request is cached for 6 hours.
+
+Optionally a reason can be 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.
+
+## Classification labels
+
+The classification label used for a project will be shown on all project pages:
+
+![classification label on project page](img/classification_label_on_project_page.png)
+
+When the external authorization service is enabled, a classification label can
+be specified for a project on the project settings page
+
+![classification label project setting](img/classification_label_project_setting.png)
+
+When no classification label is specified on a project, the default label
+defined in the global settings is used.
+
+[ee-3709]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3709

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](external_authorization.md)
 
 #### Customizing GitLab's appearance
 

doc/api/settings.md

@@ -170,6 +170,10 @@ 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_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 +211,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"
 }
 ```