Administrator documentation for Pages access control
What does this MR do?
Documents Pages access control from the admin's point of view.
What are the relevant issue numbers?
- https://gitlab.com/gitlab-org/gitlab-ce/issues/33422
- gitlab-pages!94 (merged)
- https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18589
Does this MR meet the acceptance criteria?
-
Changelog entry added, if necessary -
Documentation created/updated - [-] Tests added for this feature/bug
- [-] Conforms to the code review guidelines
- [-] Conforms to the merge request performance guidelines
- [-] Conforms to the style guides
- [-] Conforms to the database guides
Merge request reports
Activity
mentioned in issue gitlab-development-kit#403
added 34 commits
-
29dc820d...88fa9a3c - 33 commits from branch
gitlab-org:master
- a7559ffc - Add administrator documentation for Pages access control
-
29dc820d...88fa9a3c - 33 commits from branch
added 1 commit
- 197da6bd - Add administrator documentation for Pages access control
mentioned in merge request omnibus-gitlab!2583 (merged)
Hi @nick.thomas,
Please add labels to your merge request, this helps triage community merge requests.
Thanks for your help!
You are welcome to help improve this comment.
added auto updated label
added Create [DEPRECATED] devopsrelease [DEPRECATED] labels
removed auto updated label
I don't have access to the fork/branch to be able to update the documentation. I wrote about how to enable the access control when using Omnibus and moved the source install configuration to the pages for source installation doc. I also added a note about the secrets in the HA install case. Here is the diff:
diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index f16ae835ced..c903d6c533e 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -118,6 +118,16 @@ need some extra configuration. gitlab_rails['db_key_base'] = 'bf2e47b68d6cafaef1d767e628b619365becf27571e10f196f98dc85e7771042b9203199d39aff91fcb6837c8ed83f2a912b278da50999bb11a2fbc0fba52964' ``` +1. **Optional** If you are using Pages and want to enable access control, you should also + configure pages access control related secrets. Obtain these values from the primary GitLab server's + `/etc/gitlab/gitlab-secrets.json`. Add them to `/etc/gitlab/gitlab.rb` **prior to** running the first `reconfigure`. + + ```ruby + gitlab_pages['gitlab_id'] = '5be59b02538e1fa6cae8f93f7fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359ed23355341cea2b93600dab6d6c3edcdced558fc6d739860' + gitlab_pages['gitlab_secret'] = 'b710a5ef0a801348c8a357f07aa72bbd58e25a84b8f29fe119132c7810908bba18315259ed12888d4f5ee5430c42a776d840a396799b47a25c72f539c7a6c5fa' + gitlab_pages['auth_secret'] = 'e61caf95b48a6d703cb53c112bc01ebd197a85da81b18e29682040e99b4f26594772a4a2c98c6d6e657410d57c71b4fc3ed0d694e7842b1895a8b401d812c17f' + ``` + 1. Run `touch /etc/gitlab/skip-auto-migrations` to prevent database migrations from running on upgrade. Only the primary GitLab application server should handle migrations. diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 34c00c7f334..534c0dab2ad 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -260,24 +260,19 @@ 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 -do the following: +Pages access control configuration was [introduced][omnibus-mr-2583] in +Omnibus GitLab 11.5. -1. Add `access_control: enabled` to the `pages:` section of `gitlab.yml` -1. Create a new system OAuth application. 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: +1. Pages access control is currently disabled by default. To enable it edit `/etc/gitlab/gitlab.rb`: ```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> + gitlab_pages['access_control'] = true ``` -Omnibus will [automatically configure][omnibus-mr-2583] access control in a -future release. +1. [Reconfigure GitLab][reconfigure] + +NOTE: **Note:** +If you are running HA instances, see also the [Configuring GitLab for HA][configuring-ha]. ## Activate verbose logging for daemon @@ -391,3 +386,4 @@ latest previous version. [restart]: ../restart_gitlab.md#installations-from-source [gitlab-pages]: https://gitlab.com/gitlab-org/gitlab-pages/tree/v0.2.4 [video-admin]: https://youtu.be/dD8c7WNcc6s +[configuring-ha]: ../high_availability/gitlab.md diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 295905a7625..de3ff06ce5f 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -349,6 +349,34 @@ world. Custom domains and TLS are supported. 1. Restart NGINX 1. [Restart GitLab][restart] +### Access control + +Since 11.4 GitLab Pages supports access control. This allows the +Pages sites for a public project to be made private, or for Pages sites for a +private project to be made public. It can be configured per-project. + +1. Edit the `gitlab.yml` and under the `pages` setting, set `access_control` to `true`. + + ```yaml + ## GitLab Pages + pages: + enabled: true + access_control: true + ``` + +1. Create a new system OAuth application. 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-id <OAuth application id generated by GitLab> \ + -auth-client-secret <OAuth application secret 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
Edited by Tuomo Ala-Vannesluoma- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
- Resolved by Nick Thomas
Hi @nick.thomas. I've added some inline comments. A couple of other things:
- I like @tuomoa suggestion of providing example YAML. It's good for copy/paste configuration.
- We have the GitLab Pages doco split for Source and Omnibus installations. I think we need to merge them (not in this MR!!!), but for the meantime, I think all of this content is actually meant for https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/administration/pages/source.md.
- It seems like most of the documentation is right for this admin section. However, there is a bit (the
gitlab-ci.yml
bit) that is user-y. Like if my GitLab admin does their bit, I can uplift my projects for Access control myself as a user in the YAML file. So perhaps either a bit in here https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user/project/pages somewhere (configuring YAML is mentioned in a bunch of places) or at least an explicit link back to here mentioning Access control needs some extra configuration. - @mikelewis suggested our documentation on Permissions might need updating: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/permissions.md. Pages functionality is already mentioned there, so it seems like it might be likely.
Edited by Evan Readadded documentation label
@gl-docsteam FYI.
@eread aye, I intend to to complete this once the Omnibus MR is merged. Thanks for the feedback!
@nick.thomas : We need a docs update for the non-omnibus portion of the feature that is already merged and will be shipped in 11.4. (Let me know if I'm getting this wrong since I'm just jumping in now.) In particular, we are linking to the docs in the release post. See https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/15078/diffs?diff_id=25467257&start_sha=cb9fdf6d0f9bc6118e2170f096319fd841feb8e0 and https://gitlab.slack.com/archives/C3TRESYPJ/p1539916025000100
Could we merge this mr or at least open a separate mr that has the non-omnibus portion and get that merged as soon as we can so that it is linkable form the blog post to be released on the 22nd? Thanks!
@victorwu what we have in 11.4 is only the Rails configuration interface, which is of no use whatsoever without the updated Pages daemon. An install-from-source user could set the following in their
config/gitlab.yml
:pages: access_control: true
This would allow them to get a neat slider in project settings that would claim to make their Pages private or public, but that slider wouldn't actually change the visibility of their pages. The setting is not available in omnibus for %11.4.
I don't think we'd want to pick documentation into %11.4 that would say this. I don't think there's any value to mentioning that it exists at all, anywhere, including the release post.
Thanks for the clarification @nick.thomas ! I'm deleting the associated sections in the post then.
added 881 commits
-
197da6bd...a84469a3 - 880 commits from branch
gitlab-org:master
- 4366d5b7 - Add administrator documentation for Pages access control
-
197da6bd...a84469a3 - 880 commits from branch
marked the checklist item Documentation created/updated as completed
changed milestone to %11.5
added 1 commit
- 5b78aaf1 - Add administrator documentation for Pages access control
assigned to @rspeicher
@rspeicher can you review these added docs?
@nick.thomas LGTM, thanks!
mentioned in commit 6d8c0ed1
mentioned in merge request !22798 (merged)
mentioned in issue gitlab-org/quality/triage-ops#84 (closed)
mentioned in issue #54143 (closed)
mentioned in merge request !23145 (merged)