Add personal access token support (#495)

This authentication method is only available for Bitbucket Server but not for Bitbucket Cloud.

It has been introduced in Bitbucket Server 5.5:
- https://confluence.atlassian.com/bitbucketserver/bitbucket-server-5-5-release-notes-938037662.html

Documentation can be found here:
- https://confluence.atlassian.com/bitbucketserver0716/personal-access-tokens-1086402495.html

Co-authored-by: Günter Grodotzki <gunter@grodotzki.com>

Author: darxriggs

docs/USER_GUIDE.adoc

@@ -99,27 +99,40 @@ properly configured in _Manage Jenkins_ » _Configure System_
 [id=bitbucket-creds-config]
 == Credentials configuration
 
-The configuration of Bitbucket plugin (for both _Bitbucket Multibranch_ projects and _Bitbucket Team/Project_) has
+The configuration of the plugin (for both _Bitbucket Multibranch_ projects and _Bitbucket Team/Project_) has
 two credentials to configure:
 
-. *Scan Credentials*: credentials used to access Bitbucket API in order to discover repositories, branches and pull requests.
-If not set then anonymous access is used, so only public repositories, branches and pull requests are discovered and managed. Note that the
-Webhooks auto-register feature requires scan credentials to be set. Only HTTP or OAuth credentials are accepted in this field.
-. *Checkout Credentials*: credentials used to check out sources once the repository, branch or pull request is discovered. HTTP, SSH and OAuth credentials
-are allowed. If not set then _Scan Credentials_ are used.
+. *Scan Credentials*: Credentials used to access Bitbucket API in order to discover repositories, branches and pull requests.
+If not set then anonymous access is used, so only public repositories, branches and pull requests are discovered and managed.
+Note that the Webhooks auto-register feature requires scan credentials to be set.
+HTTP Basic Authentication, Access Token and OAuth credentials are supported.
+. *Checkout Credentials*: Credentials used to check out sources once the repository, branch or pull request is discovered.
+HTTP Basic Authentication, SSH and OAuth credentials are supported.
+If not set then _Scan Credentials_ are used.
 
 image::images/screenshot-3.png[scaledwidth=90%]
 
+=== Access Token
+
+The plugin can make use of an access token (Bitbucket Server only) instead of the standard username/password.
+
+First create a new _personal access token_ in Bitbucket as instructed in the https://confluence.atlassian.com/bitbucketserver0716/personal-access-tokens-1086402495.html[Bitbucket Personal Access Tokens Documentation].
+At least allow _read_ access for repositories. If you want the plugin to install the webhooks, allow _admin_ access for repositories.
+
+Then create new _Secret text credentials_ in Jenkins and enter the Bitbucket personal access token value in the _Secret_ field.
+
+When configuring a multi-branch project, add the _Checkout over SSH_ behavior to a branch source, as the token can only be used for the Bitbucket API.
+
 === OAuth credentials
 
-Bitbucket plugin can make use of OAuth credentials instead of the standard username/password.
+The plugin can make use of OAuth credentials (Bitbucket Cloud only) instead of the standard username/password.
 
-First create a new OAuth consumer as instructed in https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html[Bitbucket OAuth Documentation].
-Don't forget to check _This is a private consumer_ and at least allow read access to the repositories and Pull requests. If you want the Bitbucket to install the Webhooks also allow the read and write access of the Webhooks
+First create a new _OAuth consumer_ in Bitbucket as instructed in the https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html[Bitbucket OAuth Documentation].
+Don't forget to check _This is a private consumer_ and at least allow _read_ access for repositories and pull requests. If you want the plugin to install the webhooks, also allow _read_ and _write_ access for webhooks.
 
 image::images/screenshot-10.png[scaledwidth=90%]
 
-Then create new _Username with password credentials_, enter the Bitbucket OAuth consumer key in _Username_ field and the Bitbucket OAuth consumer secret in _Password_ field
+Then create new _Username with password credentials_ in Jenkins, enter the Bitbucket OAuth consumer key in the _Username_ field and the Bitbucket OAuth consumer secret in the _Password_ field.
 
 image::images/screenshot-11.png[scaledwidth=90%]
 
@@ -128,7 +141,7 @@ image::images/screenshot-12.png[scaledwidth=90%]
 [id=bitbucket-misc-config]
 == Miscellaneous configuration
 
-In case of slow network, you can increase socket timeout using the link:https://jenkins.io/doc/book/managing/script-console/[Script Console] :
+In case of slow network, you can increase socket timeout using the link:https://jenkins.io/doc/book/managing/script-console/[Script Console]:
 
 [source,groovy]
 ----

pom.xml

@@ -148,6 +148,10 @@
       <artifactId>authentication-tokens</artifactId>
       <version>1.3</version>
    </dependency>
+   <dependency>
+      <groupId>org.jenkins-ci.plugins</groupId>
+      <artifactId>plain-credentials</artifactId>
+   </dependency>
    <dependency>
       <groupId>org.scribe</groupId>
       <artifactId>scribe</artifactId>

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/credentials/BitbucketAccessTokenAuthenticator.java

@@ -0,0 +1,34 @@
+package com.cloudbees.jenkins.plugins.bitbucket.api.credentials;
+
+import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketAuthenticator;
+import hudson.util.Secret;
+import org.apache.http.HttpHeaders;
+import org.apache.http.HttpRequest;
+import org.jenkinsci.plugins.plaincredentials.StringCredentials;
+
+/**
+ * Authenticator that uses an access token.
+ */
+public class BitbucketAccessTokenAuthenticator extends BitbucketAuthenticator {
+
+    private final Secret token;
+
+    /**
+     * Constructor.
+     *
+     * @param credentials the access token that will be used
+     */
+    public BitbucketAccessTokenAuthenticator(StringCredentials credentials) {
+        super(credentials);
+        token = credentials.getSecret();
+    }
+
+    /**
+     * Provides the access token as header.
+     *
+     * @param request the request
+     */
+    public void configureRequest(HttpRequest request) {
+        request.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + token.getPlainText());
+    }
+}

src/main/java/com/cloudbees/jenkins/plugins/bitbucket/api/credentials/BitbucketAccessTokenAuthenticatorSource.java

@@ -0,0 +1,46 @@
+package com.cloudbees.jenkins.plugins.bitbucket.api.credentials;
+
+import com.cloudbees.jenkins.plugins.bitbucket.api.BitbucketAuthenticator;
+import edu.umd.cs.findbugs.annotations.NonNull;
+import hudson.Extension;
+import jenkins.authentication.tokens.api.AuthenticationTokenContext;
+import jenkins.authentication.tokens.api.AuthenticationTokenSource;
+import org.jenkinsci.plugins.plaincredentials.StringCredentials;
+
+/**
+ * Source for access token authenticators.
+ */
+@Extension
+public class BitbucketAccessTokenAuthenticatorSource extends AuthenticationTokenSource<BitbucketAccessTokenAuthenticator, StringCredentials> {
+
+    /**
+     * Constructor.
+     */
+    public BitbucketAccessTokenAuthenticatorSource() {
+        super(BitbucketAccessTokenAuthenticator.class, StringCredentials.class);
+    }
+
+    /**
+     * Converts string credentials to an authenticator.
+     *
+     * @param credentials the access token
+     * @return an authenticator that will use the access token
+     */
+    @NonNull
+    @Override
+    public BitbucketAccessTokenAuthenticator convert(@NonNull StringCredentials credentials) {
+        return new BitbucketAccessTokenAuthenticator(credentials);
+    }
+
+    /**
+     * Whether this source works in the given context.
+     *
+     * @param ctx the context
+     * @return whether this can authenticate given the context
+     */
+    @Override
+    public boolean isFit(AuthenticationTokenContext ctx) {
+        return ctx.mustHave(BitbucketAuthenticator.SCHEME, "https")
+            && ctx.mustHave(BitbucketAuthenticator.BITBUCKET_INSTANCE_TYPE, BitbucketAuthenticator.BITBUCKET_INSTANCE_TYPE_SERVER);
+    }
+}

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/BitbucketSCMNavigator/help-credentialsId.html

@@ -1,3 +1,6 @@
 <div>
-    Credentials used to scan branches (also the default credentials to use when checking out sources)
+    Credentials used to scan branches (also the default credentials to use when checking out sources).
+    <p>
+        For security reasons most credentials are only available when HTTPS is used.
+    </p>
 </div>

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/BitbucketSCMSource/help-credentialsId.html

@@ -1,3 +1,6 @@
 <div>
-    Credentials used to scan branches (also the default credentials to use when checking out sources)
+    Credentials used to scan branches (also the default credentials to use when checking out sources).
+    <p>
+        For security reasons most credentials are only available when HTTPS is used.
+    </p>
 </div>

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/SSHCheckoutTrait/help.html

@@ -1,5 +1,5 @@
 <div>
-    By default the discovered branches / pull requests will all use the same username / password credentials
+    By default the discovered branches / pull requests will all use the same credentials
     that were used for discovery when checking out sources. This means that the checkout will be using the
     <code>https://</code> protocol for the Git repository.
     <p>

src/main/resources/com/cloudbees/jenkins/plugins/bitbucket/endpoints/AbstractBitbucketEndpoint/help-credentialsId.html

@@ -1,4 +1,7 @@
 <div>
     Select the credentials to use for managing hooks. Both GLOBAL and SYSTEM scoped credentials are eligible as the
     management of hooks is run in the context of Jenkins itself and not in the context of the individual items.
+    <p>
+        For security reasons most credentials are only available when HTTPS is used.
+    </p>
 </div>