debian-mirror-gitlab/doc/user/admin_area/settings/external_authorization.md

138 lines
5.8 KiB
Markdown
Raw Normal View History

2019-09-04 21:01:54 +05:30
---
2021-01-29 00:20:46 +05:30
stage: none
group: unassigned
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2019-09-04 21:01:54 +05:30
type: reference
---
2019-09-30 21:07:59 +05:30
# External authorization control **(CORE ONLY)**
2019-07-07 11:18:12 +05:30
2020-06-23 00:09:42 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4216) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.6.
2020-04-22 19:07:51 +05:30
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27056) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.10.
2019-07-07 11:18:12 +05:30
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
2021-02-22 17:27:13 +05:30
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.
2019-07-07 11:18:12 +05:30
2021-02-22 17:27:13 +05:30
If the external authorization is enabled, GitLab further blocks pages and
2019-07-07 11:18:12 +05:30
functionality that render cross-project data. That includes:
2020-11-24 15:15:51 +05:30
- 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).
2021-02-22 17:27:13 +05:30
- Global and Group search are disabled.
2019-07-07 11:18:12 +05:30
This is to prevent performing to many requests at once to the external
authorization service.
2020-06-23 00:09:42 +05:30
Whenever access is granted or denied this is logged in a log file called
2021-02-22 17:27:13 +05:30
`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).
2019-07-07 11:18:12 +05:30
## Configuration
2021-02-22 17:27:13 +05:30
The external authorization service can be enabled by an administrator on the GitLab
2020-03-13 15:44:24 +05:30
**Admin Area > Settings > General** page:
2019-07-07 11:18:12 +05:30
![Enable external authorization service](img/external_authorization_service_settings.png)
The available required properties are:
- **Service URL**: The URL to make authorization requests to. When leaving the
2021-02-22 17:27:13 +05:30
URL blank, cross project features remain available while still being able
2019-07-07 11:18:12 +05:30
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
to the user.
- **Client authentication certificate**: The certificate to use to authenticate
with the external authorization service.
- **Client authentication key**: Private key for the certificate when
authentication is required for the external authorization service, this is
encrypted when stored.
2021-02-22 17:27:13 +05:30
- **Client authentication key password**: Passphrase to use for the private key
when authenticating with the external service this is encrypted when stored.
2019-07-07 11:18:12 +05:30
- **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
2021-02-22 17:27:13 +05:30
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`.
2019-07-07 11:18:12 +05:30
## How it works
2021-02-22 17:27:13 +05:30
When GitLab requests access, it sends a JSON POST request to the external
2019-07-07 11:18:12 +05:30
service with this body:
```json
{
"user_identifier": "jane@acme.org",
"project_classification_label": "project-label",
2019-09-30 21:07:59 +05:30
"user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme",
"identities": [
{ "provider": "ldap", "extern_uid": "CN=Jane Doe,CN=admin,DC=acme" },
{ "provider": "bitbucket", "extern_uid": "2435223452345" }
]
2019-07-07 11:18:12 +05:30
}
```
2021-02-22 17:27:13 +05:30
The `user_ldap_dn` is optional and is only sent when the user is signed in
2019-07-07 11:18:12 +05:30
through LDAP.
2021-02-22 17:27:13 +05:30
`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.
2019-09-30 21:07:59 +05:30
2019-07-07 11:18:12 +05:30
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
2021-02-22 17:27:13 +05:30
401 or 403, the user is denied access. In any case, the request is cached for
six hours.
2019-07-07 11:18:12 +05:30
When denying access, a `reason` can be optionally specified in the JSON body:
```json
{
"reason": "You are not allowed access to this project."
}
```
2021-02-22 17:27:13 +05:30
Any other status code than 200, 401 or 403 also deny access to the user, but the
response isn't cached.
2019-07-07 11:18:12 +05:30
If the service times out (after 500ms), a message "External Policy Server did
2021-02-22 17:27:13 +05:30
not respond" is displayed.
2019-07-07 11:18:12 +05:30
## 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
2021-02-22 17:27:13 +05:30
label defined in the [global settings](#configuration) is used.
2019-07-07 11:18:12 +05:30
2021-02-22 17:27:13 +05:30
The label is shown on all project pages in the upper right corner.
2019-07-07 11:18:12 +05:30
![classification label on project page](img/classification_label_on_project_page.png)
2019-09-04 21:01:54 +05:30
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->