Read API scope support

[shikher-srivastava]

Feature enhancement for #118
Added a scope configuration property replacing hard-coded 'api' to allow customizing the OAuth scopes requested during login.
Added an "OAuth Scope" dropdown menu.
Added a dedicated help.html,
The default choice safely remains api to preserve backwards compatibility.

Testing done

Verified backwards compatibility for api and tested read_api scoped client token by installing the packaged hpi into an existing jenkins controller.

Submitter checklist

• Make sure you are opening from a topic/feature/bugfix branch (right side) and not your main branch!
• Ensure that the pull request title represents the desired changelog entry
• Please describe what you did
• Link to relevant issues in GitHub or Jira
• Link to relevant pull requests, esp. upstream and downstream changes
• Ensure you have provided tests that demonstrate the feature works or the issue is fixed

[zbynek]

Not a maintainer, just passing by and wondering:

Reducing scopes is a good principle, what is the advantage of using api if read_api works (i.e. do users ever need the dropdown)?

Wouldn't one of the even smaller scopes be also sufficient, such as profile or read_user?
-> looks like read_api is minimal, because the plugin checks per-repository permissions

It might make sense to update the docs: https://github.com/jenkinsci/gitlab-oauth-plugin/blob/master/docs/README.md -- the scope set on GitLab side does not have to be api if you don't request it.

[shikher-srivastava]

Not a maintainer, just passing by and wondering:

Reducing scopes is a good principle, what is the advantage of using api if read_api works (i.e. do users ever need the dropdown)?

Wouldn't one of the even smaller scopes be also sufficient, such as profile or read_user?
-> looks like read_api is minimal, because the plugin checks per-repository permissions

It might make sense to update the docs: https://github.com/jenkinsci/gitlab-oauth-plugin/blob/master/docs/README.md -- the scope set on GitLab side does not have to be api if you don't request it.

You are correct, and that was my original fix; just replacing the hardcoded api scope. That does break any preconfigured api scope token however locking you out of the controller and mandating a cli fix.
Only reason to maintain backwards compatibility was to avoid that since, from my testing there are no uses of the full api scope.

[zbynek]

Hm, you're right, if I try to login with read_api and the app is configured to use api scope, it won't work.
But the description is maybe a bit misleading:

Required if you need this plugin or other plugins to actively manage repository states.

This plugin does not manage repository states and does not expose the token to other plugins (AFAIK). The plugins that write to GitLab use separate credentials. Maybe the description should make it clear that the scope you set here should match whatever you've set in GitLab and that read_api is recomended and api is only needed for previously created OAuth applications.

[shikher-srivastava]

the description is maybe a bit misleading:

Cleaned up the word salad to hopefully make it clearer.

This plugin does not manage repository states and does not expose the token to other plugins (AFAIK).

Exactly the dilemma I had. The plugin itself has no use of the full scope, any other implementation however could theoretically access the token via SecurityContextHolder. It'd make sense for eg. with https://plugins.jenkins.io/gitlab-branch-source/

[zbynek]

It might make sense to update the docs: https://github.com/jenkinsci/gitlab-oauth-plugin/blob/master/docs/README.md

The documentation update is still needed, it should say that the scope set in GitLab must match the scope in Jenkins settings. Otherwise looks good 👍