[JENKINS-74970] Log user name and repository on auth error

If Bitbucket Server responds with HTTP status 401 (Unauthorized) or
403 (Forbidden), and the HTTP response includes an "X-AUSERNAME"
header field that shows Bitbucket Server authenticated the user, then
add more information in the message of the BitbucketRequestException:

* The Bitbucket user name from the "X-AUSERNAME" response header field.
* The repository to which the request was sent.
* The project or user that owns the repository.

The behaviour on Bitbucket Cloud is unchanged.

Author: KalleOlaviNiemitalo

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/server/client/BitbucketServerAPIClient.java

@@ -87,8 +87,10 @@
 import jenkins.scm.api.SCMFile;
 import org.apache.commons.io.IOUtils;
 import org.apache.commons.lang.StringUtils;
+import org.apache.http.Header;
 import org.apache.http.HttpHost;
 import org.apache.http.HttpStatus;
+import org.apache.http.client.methods.CloseableHttpResponse;
 import org.apache.http.client.methods.HttpGet;
 import org.apache.http.conn.HttpClientConnectionManager;
 import org.apache.http.impl.client.CloseableHttpClient;
@@ -1051,4 +1053,49 @@ private Map<String,Object> collectLines(String response, final List<String> line
         return content;
     }
 
+    @Override
+    protected BitbucketRequestException buildResponseException(CloseableHttpResponse response, String errorMessage) {
+        // If the HTTP request failed because of an authorization
+        // problem, then make the exception message also show the
+        // Bitbucket user name with which Jenkins authenticated,
+        // the project name, and the repository name.
+        //
+        // Such an authorization problem can occur especially in a
+        // pull request from a personal fork: if Jenkins has been
+        // granted READ access on the target repository of the PR but
+        // not on the fork, then it can read the PR information from
+        // the target repository and check out the files, but cannot
+        // post a build status to the fork.
+        //
+        // If the HTTP request already includes valid credentials,
+        // but the Bitbucket user has not been granted access on the
+        // repository, then Bitbucket Server responds with HTTP status
+        // 401 (Unauthorized) and a WWW-Authenticate header field that
+        // requests OAuth, even though RFC 7235 section 2.1 recommends
+        // 403 (Forbidden).  Let's recognize both 401 and 403.
+        int httpStatus = response.getStatusLine().getStatusCode();
+        if (httpStatus == HttpStatus.SC_UNAUTHORIZED || httpStatus == HttpStatus.SC_FORBIDDEN) {
+            Header userNameHeader = response.getFirstHeader("X-AUSERNAME");
+            if (userNameHeader != null
+                && !userNameHeader.getValue().equals("anonymous")) {
+                String headers = StringUtils.join(response.getAllHeaders(), "\n");
+
+                // The message says "sufficient access" because it is
+                // too difficult for this method to know which level
+                // of access is actually needed.
+                // Posting a build status requires READ access, but
+                // deleting a build status requires ADMIN access.
+                String message = String.format("HTTP request error.%nPlease verify that the Bitbucket user \"%s\" is granted sufficient access on the repository \"%s/%s\".%nStatus: %s%nResponse: %s%n%s",
+                                               userNameHeader.getValue(),
+                                               getUserCentricOwner(),
+                                               getRepositoryName(),
+                                               response.getStatusLine(),
+                                               errorMessage,
+                                               headers);
+                return new BitbucketRequestException(httpStatus, message);
+            }
+        }
+
+        return super.buildResponseException(response, errorMessage);
+    }
 }