Skip to content
Snippets Groups Projects

Administrator documentation for Pages access control

Merged Nick Thomas requested to merge (removed):pages-access-control-docs into master
All threads resolved!

What does this MR do?

Documents Pages access control from the admin's point of view.

What are the relevant issue numbers?

Does this MR meet the acceptance criteria?

Edited by Achilleas Pipinellis

Merge request reports

Loading
Loading

Activity

Filter activity
  • Approvals
  • Assignees & reviewers
  • Comments (from bots)
  • Comments (from users)
  • Commits & branches
  • Edits
  • Labels
  • Lock status
  • Mentions
  • Merge request status
  • Tracking
  • Nick Thomas added 34 commits

    added 34 commits

    Compare with previous version

  • Nick Thomas added 1 commit

    added 1 commit

    • 197da6bd - Add administrator documentation for Pages access control

    Compare with previous version

  • 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! :black_heart:


    You are welcome to help improve this comment.

  • 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
  • Evan Read
  • Evan Read
  • Evan Read
  • Evan Read
  • Evan Read
  • Evan Read
  • Evan Read
  • Evan Read
  • Hi @nick.thomas. I've added some inline comments. A couple of other things:

    Edited by Evan Read
  • Author Contributor

    @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!

  • Author Contributor

    @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.

  • Nick Thomas added 881 commits

    added 881 commits

    Compare with previous version

  • Nick Thomas resolved all discussions

    resolved all discussions

  • Nick Thomas unmarked as a Work In Progress

    unmarked as a Work In Progress

  • Nick Thomas marked the checklist item Documentation created/updated as completed

    marked the checklist item Documentation created/updated as completed

  • Nick Thomas changed the description

    changed the description

  • Nick Thomas changed milestone to %11.5

    changed milestone to %11.5

  • Nick Thomas added 1 commit

    added 1 commit

    • 5b78aaf1 - Add administrator documentation for Pages access control

    Compare with previous version

  • assigned to @rspeicher

  • Author Contributor

    @rspeicher can you review these added docs?

  • Robert Speicher approved this merge request

    approved this merge request

  • @nick.thomas LGTM, thanks! :thumbsup: :green_heart:

  • Robert Speicher mentioned in commit 6d8c0ed1

    mentioned in commit 6d8c0ed1

  • Evan Read mentioned in merge request !22798 (merged)

    mentioned in merge request !22798 (merged)

  • Achilleas Pipinellis changed the description

    changed the description

  • mentioned in issue #54143 (closed)

  • mentioned in merge request !23145 (merged)

  • Please register or sign in to reply
    Loading