Add new options to GitHub App credentials to allow dynamic restrictions of the repositories and permissions available to installation access tokens in some contexts

docs/github-app.adoc

@@ -87,8 +87,9 @@ Fill out the form:
 - App ID: the github app ID, it can be found in the 'About' section of your GitHub app in the general tab.
 - API endpoint (optional, only required for GitHub enterprise this will only show up if a GitHub enterprise server is configured).
 - Key: click add, paste the contents of the converted private key
-- Advanced: (optional) If you've installed your same GitHub app on multiple organizations you need the next step
-  * Owner: the name of the organisation or user, i.e. jenkinsci for https://github.com/jenkinsci
+- Advanced: (optional):
+  * Repository access strategy: Controls what GitHub repositories will be accessible to these credentials in untrusted contexts (see below for details)
+  * Default permissions strategy: Controls what GitHub permissions will be accessible to these credentials in untrusted contexts (see below for details)
 - Click OK
 
 === link:https://github.com/jenkinsci/configuration-as-code-plugin[Configuration as Code Plugin]
@@ -135,6 +136,42 @@ Verify at the bottom of the scan log it says:
 Finished: SUCCESS
 ----
 
+=== Enhancing security using repository access strategies and default permissions strategies
+
+GitHub App Credentials offer advanced configuration options that can provide additional security in some scenarios.
+In particular, when GitHub App Credentials are used by an Organization Folder or Multibranch Pipeline, these strategies may dynamically restrict the accessible repositories and permissions available to the credentials when they are accessed in untrusted contexts, such as when they are accessed by a `withCredentials` step in one of the individual Pipeline jobs.
+See link:https://www.jenkins.io/doc/book/security/securing-org-folders-and-multibranch-pipelines/[this documentation] for additional information on why it may be beneficial to limit credentials in this way.
+These strategies do not apply when using the credentials in trusted contexts, such as during organization folder scans and branch indexing.
+Note also that Jenkins users who have Job/Configure permission in a context where the credentials are available are considered trusted and can bypass these strategies by configuring jobs as desired.
+In trusted contexts, the generated access tokens will have the same access as configured for the app installation in GitHub.
+
+The following repository access strategies are available:
+* **Infer owner and allow access to all owned repositories** (Default)
+    * The credentials may only be used in contexts where a GitHub organization can be inferred, such as Organization Folders and Multibranch Pipelines
+    * The access tokens generated in untrusted contexts will be able to access all repositories in the inferred GitHub organization that are accessible to the GitHub App installation.
+* **Infer accessible repository**
+    * The credentials may only be used in contexts where a GitHub organization and repository can be inferred, such as Organization Folders and Multibranch Pipelines
+    * The access tokens generated in untrusted contexts will only be able to access the inferred repository
+* **Specify accessible repositories**
+    * The access tokens generated in untrusted contexts will be able to access the repositories specified statically in the credential configuration
+    * If the GitHub app is installed in a single organization, the owner field may be left blank empty, in which case that organization will be accessed automatically
+    * Leaving the repositories field empty will result in all repositories accessible to the configured owner being accessible
+
+The following default permissions strategies are available:
+* Read-only access to repository contents
+    * The access tokens generated in untrusted contexts will only be able to read the repository contents
+* Read and write access to repository contents
+    * The access tokens generated in untrusted contexts will only be able to read and write the repository contents
+* All permissions available to the app installation (default)
+    * The access tokens generated in untrusted contexts will have the same permissions as the app installation in GitHub
+
+==== Repository access strategies and Pipeline libraries
+
+Repository inference for GitHub App Credentials does not work when checking out Pipeline libraries.
+If you have a GitHub App Credential for an Organization Folder or Multibranch Pipeline whose individual Pipeline jobs access a Pipeline library, the contextually inferred repository for the library checkout will be the repository for the Pipeline job rather than the library.
+This means that the library will be inaccessible if you use an inference-based repository access strategy which only provides access to a single contextually-inferred repository, or if the Pipeline library is in a different GitHub organization than the repository being built.
+For now, in this case, you either need to use a less restrictive strategy for the GitHub App credential, such as "Infer owner and allow access to all owned repositories", or you can define a second credential specifically for the Pipeline library which uses "Specify accessible repositories" and only allows access to the repository for the Pipeline library.
+
 === Help?
 
 Raise an issue on link:https://issues.jenkins-ci.org/[Jenkins jira]

src/main/java/org/jenkinsci/plugins/github_branch_source/Connector.java

@@ -227,7 +227,7 @@ public static FormValidation checkScanCredentials(
                     } finally {
                         Connector.release(connector);
                     }
-                } catch (IllegalArgumentException | InvalidPrivateKeyException e) {
+                } catch (IllegalArgumentException | IllegalStateException | InvalidPrivateKeyException e) {
                     String msg = "Exception validating credentials " + CredentialsNameProvider.name(credentials);
                     LOGGER.log(Level.WARNING, msg, e);
                     return FormValidation.error(e, msg);
@@ -261,8 +261,7 @@ public static StandardCredentials lookupScanCredentials(
     }
 
     /**
-     * Resolves the specified scan credentials in the specified context for use against the specified
-     * API endpoint.
+     * Retained for binary compatibility only.
      *
      * @param context the context.
      * @param apiUri the API endpoint.
@@ -281,6 +280,9 @@ public static StandardCredentials lookupScanCredentials(
      * Resolves the specified scan credentials in the specified context for use against the specified
      * API endpoint.
      *
+     * <p>Callers of this method must not expose the credentials to unprivileged users for
+     * uncontrolled usage.
+     *
      * @param context the context.
      * @param apiUri the API endpoint.
      * @param scanCredentialsId the credentials to resolve.
@@ -306,9 +308,20 @@ public static StandardCredentials lookupScanCredentials(
                         githubDomainRequirements(apiUri)),
                 CredentialsMatchers.allOf(
                         CredentialsMatchers.withId(scanCredentialsId), githubScanCredentialsMatcher()));
-
         if (c instanceof GitHubAppCredentials && repoOwner != null) {
-            c = ((GitHubAppCredentials) c).withOwner(repoOwner);
+            // Note: We considered adding an overload so that all existing callers in this plugin could
+            // specify an exact repository and granular permission, but decided against it. This method
+            // should only be called in contexts where the credential could not be exposed to users
+            // other than those who were able to create/configure whatever is using the credential in
+            // the first place. Those users would be able to steal the GitHub App refresh JWT, which
+            // they can then use to generate their own credentials, so dynamic limitations in this
+            // context have no benefits, and would unnecessarily increase the size of the connection
+            // cache because the cache keys are distinct for every context.
+            final var usageContext = GitHubAppUsageContext.builder()
+                    .inferredOwner(repoOwner)
+                    .trust()
+                    .build();
+            return ((GitHubAppCredentials) c).contextualize(usageContext);
         }
         return c;
     }
@@ -368,12 +381,15 @@ public static ListBoxModel listCheckoutCredentials(@CheckForNull Item context, S
             password = null;
             gitHubAppCredentials = (GitHubAppCredentials) credentials;
             hash = Util.getDigestOf(gitHubAppCredentials.getAppID()
-                    + gitHubAppCredentials.getOwner()
+                    + gitHubAppCredentials.getAccessibleRepositories()
+                    + gitHubAppCredentials.getPermissions()
                     + gitHubAppCredentials.getPrivateKey().getPlainText()
                     + SALT); // want to ensure pooling by credential
             authHash = Util.getDigestOf(gitHubAppCredentials.getAppID()
                     + "::"
-                    + gitHubAppCredentials.getOwner()
+                    + gitHubAppCredentials.getAccessibleRepositories()
+                    + "::"
+                    + gitHubAppCredentials.getPermissions()
                     + "::"
                     + gitHubAppCredentials.getPrivateKey().getPlainText()
                     + "::"