Document GitLab's required scope if using allowed_gitlab_groups or not

[consideRatio]

GitLabOAuthenticator is making some checks against GitLab's REST API following a user has authenticated, in order to decide if the user is authorized. These requests against the GitLab REST API that follows authentication, are made with the access token that resulted from the authentication process.

This access token can get various degrees of permissions, which is influenced by the requested scopes, and will be seen by the user during the authentication phase. This issue is about these scopes, and that we need to request too powerful permissions through them, just because we maybe want to authorize the user because it belongs to a specific group in gitlab with certain status in this group.

Here are some of the scopes with GitLab specific meaning we can make use of.

AH! I notice now that we can make use of read_api instead of api which is just the way too powerful option! It would be great to reduce it even further to something like read_groups or similarly, but this is far much better than write. Okay!

Action points to close issue

• [ ] Update documentation to clarify what scope is needed if we are using and if we are not using the allowed_gitlab_groups configuration, it will be different because only if we configure that do we end up needing to make certain REST API requests to GitLab (as seen here).

Related

• PR that escalated the permission requirements
• Issue about the escalated permission requirements

[consideRatio]

Guess

I think read_user,openid,profile,email or read_api,openid,profile,email will be sufficient depending on if we need to probe the GitLab's REST API for group membership or not, but is this the minimal and sufficient amount of scope? It would be great to get that verified and documented.

[CJCShadowsan]

Sorry - i'm confused. Where am I setting these permissions?

I've got a helm chart that has auth inside it:

auth:
  type: gitlab
  gitlab:
    clientId: "*****"
    clientSecret: "****"
    callbackUrl: "https://test-server/hub/oauth_callback"
    gitlabHost: "https://gitlab/"
    gitlabApiUrl: "https://gitlab/api/v3/"

But all i'm getting are 403 errors back - i'm assuming because of this, and i'm not entirely sure where to set the scopes...

...Is this something that can be set inside the helm chart as a configurable?

[manics]

There's a scopes field, see the example on https://zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html#giving-access-to-organizations-on-github

[CJCShadowsan]

There's a scopes field, see the example on https://zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html#giving-access-to-organizations-on-github

Yeah but that seems to not work...

I've tried the gitlab scopes read_user and read_api for reference:

    scopes:
      - "read_api"
      - "read_user"

I rebuild via helm...

I go through the auth procedure (after deleting the token) and i'm presented with:

Showing no permissions.

Any ideas?

[consideRatio]

Try adding openid, profile, email alongside read_api and read_user, I think that is the minimal configuration atm.

[CJCShadowsan]

Unfortunately, tried that...

...Was presented with the same thing.

What am I missing? 😢

[consideRatio]

@CJCShadowsan I don't aim to specifically help you atm, but to resolve this issue, but there can be overlap. With regards to solving this issue and finding out about sensible configuration, I'd like to ensure you are using the latest version of the oauthenticator, which means you should use the latest development version of the z2jh Helm chart. If you are using 0.9.0 or 0.9.1, please upgrade to the absolute latest version (0.9.0-n355.h9ca120bb) and post your entire auth section config from your config.yaml which you redact where needed for security.

Also, declare your GitLab's version.

[CJCShadowsan]

@CJCShadowsan I don't aim to specifically help you atm, but to resolve this issue, but there can be overlap. With regards to solving this issue and finding out about sensible configuration, I'd like to ensure you are using the latest version of the oauthenticator, which means you should use the latest development version of the z2jh Helm chart. If you are using 0.9.0 or 0.9.1, please upgrade to the absolute latest version (0.9.0-n355.h9ca120bb) and post your entire auth section config from your config.yaml which you redact where needed for security.

Also, declare your GitLab's version.

No problem, I was merely trying to keep it on-topic of gitlab, scope and documentation because if this is how it should work via Helm... Right now i've not seen it working yet so wanted to make sure the docs are right :)

Let me double-check everything and get back to you!

[CJCShadowsan]

Ok - i'm running 0.9.1 because the absolute latest helm chart recommended doesn't seem to work... 🤷

Relevant auth config:

auth:
  type: gitlab
  gitlab:
    clientId: "MySuperSecretClientID"
    clientSecret: "MySuperSecretClientSecret"
    callbackUrl: "https://myhubserver/hub/oauth_callback"
    gitlabHost: "https://gitlabserver/"
    gitlabApiUrl: "https://gitlabserver/api/v4/"
    scopes:
      - "read_api"
      - "read_user"
      - "openid"
      - "profile"
      - "email"

The application is created inside gitlab with the same permissions as listed here.

Gitlab version: GitLab Enterprise Edition 12.10.3-ee

Whenever I try to auth using this, I get presented with the authorise prompt but it lists no permissions requested. I authorise it, it goes back to the callback url and I get presented with a 500 error.

I log onto the pod, and inspect the logs and the 500 error is rather unhelpful because on the backend I get a 403 Forbidden error, which I can only guess is the fact there are no permissions granted.

I think i'm following documentation correctly...

[CJCShadowsan]

I've found it.

This:

auth:
  type: gitlab
  gitlab:
    clientId: "MySuperSecretClientID"
    clientSecret: "MySuperSecretClientSecret"
    callbackUrl: "https://myhubserver/hub/oauth_callback"
    gitlabHost: "https://gitlabserver/"
    gitlabApiUrl: "https://gitlabserver/api/v4/"
    scopes:
      - "read_api"
      - "read_user"
      - "openid"
      - "profile"
      - "email"

Should be THIS:

auth:
  type: gitlab
  gitlab:
    clientId: "MySuperSecretClientID"
    clientSecret: "MySuperSecretClientSecret"
    callbackUrl: "https://myhubserver/hub/oauth_callback"
    gitlabHost: "https://gitlabserver/"
    gitlabApiUrl: "https://gitlabserver/api/v4/"
  scopes:
    - "read_api"
    - "read_user"
    - "openid"
    - "profile"
    - "email"

Indentation means you don't set it inside the auth type definition, you set it globally 🤦‍♂️

Not sure if this is documented specifically this way. I'll double-check.

[consideRatio]

In general, I'm waiting eagerly to update the entire auth configuration of z2jh. It causes more issues than anything else

[manning-ncsa]

I was pulling my hair out trying to figure out why auth was failing for me until I found this discussion. I am using JupyterHub Helm chart v0.11.1. I was unable to authenticate using allowed_gitlab_groups when only scope read_user was listed, but when I added read_api, it worked. Hopefully this helps someone else.

Relevant part of my chart override values.yaml file:

  hub:
    baseUrl: /jupyter
    config:
      JupyterHub:
        admin_access: true
        authenticator_class: oauthenticator.gitlab.GitLabOAuthenticator
        GitLabOAuthenticator:
          oauth_callback_url: 'https://example.com/jupyter/hub/oauth_callback'
          client_id: '6c...523'
          client_secret: '76a8...39a'
          scope:
          - 'read_user'
          - 'read_api'
          allowed_gitlab_groups:
          - '12345678'
    ```