diff options
Diffstat (limited to 'doc/user/admin_area/settings/external_authorization.md')
| -rw-r--r-- | doc/user/admin_area/settings/external_authorization.md | 51 |
1 files changed, 28 insertions, 23 deletions
diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index 80bca6f5b2c..6e32d15d8f4 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -17,26 +17,26 @@ 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. +After 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 six hours. -If the external authorization is enabled, GitLab will further block pages and +If the external authorization is enabled, GitLab further blocks pages and functionality that render cross-project data. That includes: - Most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge requests, Assigned issues, To-Do List). - Under a specific group (Activity, Contribution analytics, Issues, Issue boards, Labels, Milestones, Merge requests). -- Global and Group search will be disabled. +- Global and Group search are disabled. This is to prevent performing to many requests at once to the external authorization service. Whenever access is granted or denied this is logged in a log file called -`external-policy-access-control.log`. -Read more about logs GitLab keeps in the [omnibus documentation](https://docs.gitlab.com/omnibus/settings/logs.html). +`external-policy-access-control.log`. Read more about the logs GitLab keeps in +the [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/logs.html). ## Configuration @@ -48,7 +48,7 @@ The external authorization service can be enabled by an admin on the GitLab's The available required properties are: - **Service URL**: The URL to make authorization requests to. When leaving the - URL blank, cross project features will remain available while still being able + URL blank, cross project features remain available while still being able to specify classification labels for projects. - **External authorization request timeout**: The timeout after which an authorization request is aborted. When a request times out, access is denied @@ -58,19 +58,21 @@ The available required properties are: - **Client authentication key**: Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored. -- **Client authentication key password**: Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. +- **Client authentication key password**: Passphrase to use for the private key + when authenticating with the external service this is encrypted when stored. - **Default classification label**: The classification label to use when requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trusted by the OpenSSL installation. When using GitLab installed using -Omnibus, learn to install a custom CA in the -[omnibus documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). Alternatively learn where to install -custom certificates using `openssl version -d`. +needs to be trusted by the OpenSSL installation. When using GitLab installed +using Omnibus, learn to install a custom CA in the +[Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/ssl.html). +Alternatively, learn where to install custom certificates by using +`openssl version -d`. ## How it works -When GitLab requests access, it will send a JSON POST request to the external +When GitLab requests access, it sends a JSON POST request to the external service with this body: ```json @@ -85,14 +87,17 @@ service with this body: } ``` -The `user_ldap_dn` is optional and is only sent when the user is logged in +The `user_ldap_dn` is optional and is only sent when the user is signed in through LDAP. -`identities` will contain the details of all the identities associated with the user. This will be an empty array if there are no identities associated with the user. +`identities` contains the details of all the identities associated with the +user. This is an empty array if there are no identities associated with the +user. 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 or 403, the user is denied access. In any case, the request is cached for 6 hours. +401 or 403, the user is denied access. In any case, the request is cached for +six hours. When denying access, a `reason` can be optionally specified in the JSON body: @@ -102,20 +107,20 @@ When denying access, a `reason` can be optionally specified in the JSON body: } ``` -Any other status code than 200, 401 or 403 will also deny access to the user, but the -response will not be cached. +Any other status code than 200, 401 or 403 also deny access to the user, but the +response isn't cached. If the service times out (after 500ms), a message "External Policy Server did -not respond" will be displayed. +not respond" is 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. +label defined in the [global settings](#configuration) is used. -The label will be shown on all project pages in the upper right corner. +The label is shown on all project pages in the upper right corner.  |