Read API scope support (#219)

* Add configurable OAuth scope (Fix #118)

* Improve OAuth scope UX with dropdown and tooltip

* cleanup

* Revise OAuth scope help text for clarity

Updated the description of the OAuth scope and adjusted recommendations.

* README.md: docs updated for read_api scope

* Update src/main/webapp/help/realm/scope-help.html

Co-authored-by: Zbynek Konecny <zbynek1729@gmail.com>

---------

Co-authored-by: Shikher <shikher@example.com>
Co-authored-by: Zbynek Konecny <zbynek1729@gmail.com>
Co-authored-by: Kris Stern <88480540+krisstern@users.noreply.github.com>

Author: 4 people

docs/README.md

@@ -7,9 +7,10 @@ also supported.
 ## Setup
 
 Before configuring the plugin you must create a GitLab application
-registration. In the Scopes section mark **api**.
+registration. In the Scopes section mark **read_api** (recommended) or
+**api**.
 
-the authorization callback URL takes a specific value. It must be
+The authorization callback URL takes a specific value. It must be
 `http://myserver.example.com:8080/securityRealm/finishLogin` where
 myserver.example.com:8080 is the location of the Jenkins server.
 
@@ -28,8 +29,9 @@ realm to authenticate Jenkins users via GitLab OAuth.
     **GitLab Authentication Plugin**.
 2.  The settings to configure are: GitLab Web URI, GitLab API URI,
     Client ID, Client Secret, and OAuth Scope(s).
-3.  If you're using GitLab Enterprise then the API URI is
-    <https://ghe.acme.com/api/v3>. The prefix
+3.  Select the scope configured during GitLab application registration in the **OAuth Scope(s)** dropdown.
+4.  If you're using GitLab Enterprise then the API URI is
+    <https://ghe.acme.com/api/v3>. The prefix
     "[api/v3](https://ghe.acme.com/api/v3)" will be
     completed by the plugin
 

src/main/java/org/jenkinsci/plugins/GitLabSecurityRealm.java

@@ -43,6 +43,7 @@
 import hudson.security.SecurityRealm;
 import hudson.security.UserMayOrMayNotExistException2;
 import hudson.tasks.Mailer;
+import hudson.util.ListBoxModel;
 import hudson.util.Secret;
 import jakarta.servlet.http.HttpSession;
 import java.io.IOException;
@@ -77,6 +78,7 @@
 import org.gitlab4j.models.Constants.TokenType;
 import org.jfree.util.Log;
 import org.kohsuke.stapler.DataBoundConstructor;
+import org.kohsuke.stapler.DataBoundSetter;
 import org.kohsuke.stapler.Header;
 import org.kohsuke.stapler.HttpRedirect;
 import org.kohsuke.stapler.HttpResponse;
@@ -107,6 +109,7 @@ public class GitLabSecurityRealm extends SecurityRealm {
     private String gitlabApiUri;
     private String clientID;
     private Secret clientSecret;
+    private String scope = "api";
 
     /**
      * @param gitlabWebUri
@@ -199,6 +202,10 @@ public void marshal(Object source, HierarchicalStreamWriter writer, MarshallingC
             writer.startNode("clientSecret");
             writer.setValue(realm.clientSecret.getEncryptedValue());
             writer.endNode();
+
+            writer.startNode("scope");
+            writer.setValue(realm.getScope());
+            writer.endNode();
         }
 
         @Override
@@ -234,6 +241,9 @@ private void setValue(GitLabSecurityRealm realm, String node, String value) {
                 case "gitlabapiuri":
                     realm.setGitlabApiUri(value);
                     break;
+                case "scope":
+                    realm.setScope(value);
+                    break;
                 default:
                     throw new ConversionException("Invalid node value = " + node);
             }
@@ -263,6 +273,15 @@ public Secret getClientSecret() {
         return clientSecret;
     }
 
+    public String getScope() {
+        return scope;
+    }
+
+    @DataBoundSetter
+    public void setScope(String scope) {
+        this.scope = scope;
+    }
+
     // "from" is coming from SecurityRealm/loginLink.jelly
     public HttpResponse doCommenceLogin(
             StaplerRequest2 request, @QueryParameter String from, @Header("Referer") final String referer)
@@ -290,7 +309,7 @@ public HttpResponse doCommenceLogin(
         parameters.add(new BasicNameValuePair("redirect_uri", buildRedirectUrl(request)));
         parameters.add(new BasicNameValuePair("response_type", "code"));
         parameters.add(new BasicNameValuePair("client_id", clientID));
-        parameters.add(new BasicNameValuePair("scope", "api"));
+        parameters.add(new BasicNameValuePair("scope", getScope()));
         parameters.add(new BasicNameValuePair("state", state));
 
         return new HttpRedirect(
@@ -530,6 +549,13 @@ public DescriptorImpl() {
         public DescriptorImpl(Class<? extends SecurityRealm> clazz) {
             super(clazz);
         }
+
+        public ListBoxModel doFillScopeItems() {
+            ListBoxModel items = new ListBoxModel();
+            items.add("api", "api");
+            items.add("read_api", "read_api");
+            return items;
+        }
     }
 
     // Overridden for better type safety.
@@ -586,6 +612,7 @@ public boolean equals(Object object) {
             return this.getGitlabWebUri().equals(obj.getGitlabWebUri())
                     && this.getGitlabApiUri().equals(obj.getGitlabApiUri())
                     && this.getClientID().equals(obj.getClientID())
+                    && this.getScope().equals(obj.getScope())
                     && this.clientSecret.equals(obj.clientSecret);
         } else {
             return false;

src/main/resources/org/jenkinsci/plugins/GitLabSecurityRealm/config.jelly

@@ -20,5 +20,9 @@
             <f:password />
         </f:entry>
 
+        <f:entry title="OAuth Scope(s)" field="scope" help="/plugin/gitlab-oauth/help/realm/scope-help.html">
+            <f:select default="api" />
+        </f:entry>
+
     </f:section>
 </j:jelly>

src/main/webapp/help/realm/scope-help.html

@@ -0,0 +1,7 @@
+<div>
+  The <b>Token Scope</b> from the GitLab application entry being configured. Recommended value: <strong>read_api</strong>.
+  <ul>
+    <li><strong>api:</strong> Full read/write access to the GitLab API. (Legacy support)</li>
+    <li><strong>read_api:</strong> Read-only access to the GitLab API. (Recommended)</li>
+  </ul>
+</div>