Merge branch 'pages-access-control-docs' into 'master'

Administrator documentation for Pages access control

See merge request gitlab-org/gitlab-ce!22146

2 files changed, 65 insertions, 0 deletions

diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md
index 2952a98626a..d8345f2d6bd 100644
--- a/doc/administration/pages/index.md
+++ b/doc/administration/pages/index.md
@@ -242,6 +242,33 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck
 **Require users to prove ownership of custom domains** in the Pages section.
 This setting is enabled by default.
 
+### Access control
+
+Access control was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422)
+in GitLab 11.5. It can be configured per-project, and allows access to a Pages
+site to be controlled based on a user's membership to that project.
+
+Access control works by registering the Pages daemon as an OAuth application
+with GitLab. Whenever a request to access a private Pages site is made by an
+unauthenticated user, the Pages daemon redirects the user to GitLab. If
+authentication is successful, the user is redirected back to Pages with a token,
+which is persisted in a cookie. The cookies are signed with a secret key, so
+tampering can be detected.
+
+Each request to view a resource in a private site is authenticated by Pages
+using that token. For each request it receives, it makes a request to the GitLab
+API to check that the user is authorized to read that site.
+
+Pages access control is currently disabled by default. To enable it, you must:
+
+1. Enable it in `/etc/gitlab/gitlab.rb`
+
+    ```ruby
+    gitlab_pages['access_control'] = true
+    ```
+
+1. [Reconfigure GitLab][reconfigure]
+
 ## Activate verbose logging for daemon
 
 Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/2533) in
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index 295905a7625..ddff54be575 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -391,6 +391,44 @@ the first one with a backslash (\). For example `pages.example.io` would be:
 server_name ~^.*\.pages\.example\.io$;
 ```
 
+## Access control
+
+Access control was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422)
+in GitLab 11.5. It can be configured per-project, and allows access to a Pages
+site to be controlled based on a user's membership to that project.
+
+Access control works by registering the Pages daemon as an OAuth application
+with GitLab. Whenever a request to access a private Pages site is made by an
+unauthenticated user, the Pages daemon redirects the user to GitLab. If
+authentication is successful, the user is redirected back to Pages with a token,
+which is persisted in a cookie. The cookies are signed with a secret key, so
+tampering can be detected.
+
+Each request to view a resource in a private site is authenticated by Pages
+using that token. For each request it receives, it makes a request to the GitLab
+API to check that the user is authorized to read that site.
+
+Pages access control is currently disabled by default. To enable it, you must:
+
+1. Modify your `config/gitlab.yml` file:
+    ```yaml
+    pages:
+      access_control: true
+    ```
+1. [Restart GitLab][restart]
+1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile)
+   This should be called `GitLab Pages` and have a `Redirect URL` of
+   `https://projects.example.io/auth`. It does not need to be a "trusted"
+   application, but it does need the "api" scope.
+1. Start the Pages daemon with the following additional arguments:
+
+    ```shell
+      -auth-client-secret <OAuth code generated by GitLab> \
+      -auth-redirect-uri http://projects.example.io/auth \
+      -auth-secret <40 random hex characters> \
+      -auth-server <URL of the GitLab instance>
+    ```
+
 ## Change storage path
 
 Follow the steps below to change the default path where GitLab Pages' contents