Merge pull request #607 from mminns/issue/573-OAuth2-support-for-Bitbucket-DC

Issue/573 OAuth2 support for Bitbucket DC

Author: mjcheetham

docs/bitbucket-development.md

@@ -123,6 +123,76 @@ be accessed using the credentials `admin`/`admin` at
 Atlassian has [documentation][atlassian-sdk] on how to download and install
 their SDK.
 
+## OAuth2 Configuration
+
+Bitbucket DC [7.20](https://confluence.atlassian.com/bitbucketserver/bitbucket-data-center-and-server-7-20-release-notes-1101934428.html)
+added support for OAuth2 Incoming Application Links and this can be used to
+support OAuth2 authentication for Git. This is especially useful in environments
+where Bitbucket uses SSO as it removes the requirement for users to manage
+[SSH keys](https://confluence.atlassian.com/display/BITBUCKETSERVER0717/Using+SSH+keys+to+secure+Git+operations)
+or manual [HTTP access tokens](https://confluence.atlassian.com/display/BITBUCKETSERVER0717/Personal+access+tokens).
+
+### Host Configuration
+
+For more details see
+[Bitbucket's documentation on Data Center and Server Application Links to other Applications](https://confluence.atlassian.com/bitbucketserver/link-to-other-applications-1018764620.html)
+
+Create Incoming OAuth 2 Application Link:
+<!-- markdownlint-disable MD034 -->
+1. Navigate to Administration/Application Links
+1. Create Link
+   1. Screen 1
+      - External Application [check]
+      - Incoming Application [check]
+   1. Screen 2
+      - Name : GCM
+      - Redirect URL : `http://localhost:34106/`
+      - Application Permissions : Repositories.Read [check], Repositories.Write [check]
+   1. Save
+   <!-- markdownlint-enable MD034 -->
+   1. Copy the `ClientId` and `ClientSecret` to configure GCM
+
+### Client Configuration
+
+Set the OAuth2 configuration use the `ClientId` and `ClientSecret` copied above,
+(for details see [credential.bitbucketDataCenterOAuthClientId](configuration.md#credential.bitbucketDataCenterOAuthClientId)
+and [credential.bitbucketDataCenterOAuthClientSecret](configuration.md#credential.bitbucketDataCenterOAuthClientSecret))
+
+    ❯ git config --global credential.bitbucketDataCenterOAuthClientId {`Copied ClientId`}
+
+    ❯ git config --global credential.bitbucketDataCenterOAuthClientSecret {`Copied ClientSecret`}
+<!-- markdownlint-disable MD034 -->
+As described in [Configuration options](configuration.md#Configuration%20options)
+the settings can be made more specific to apply only to a specific Bitbucket DC
+host by specifying the host url, e.g. https://bitbucket.example.com/
+<!-- markdownlint-enable MD034 -->
+
+    ❯ git config --global credential.https://bitbucket.example.com.bitbucketDataCenterOAuthClientId {`Copied ClientId`}
+
+    ❯ git config --global credential.https://bitbucket.example.com.bitbucketDataCenterOAuthClientSecret {`Copied ClientSecret`}
+<!-- markdownlint-disable MD034 -->
+Due to the way GCM resolves hosts and determines REST API urls, if the Bitbucket
+DC instance is hosted under a relative url (e.g. https://example.com/bitbucket)
+it is necessary to configure Git to send the full path to GCM. This is done
+using the [credential.useHttpPath](configuration.md#credential.useHttpPath)  
+setting.
+    ❯ git config --global credential.https://example.com/bitbucket.usehttppath true
+<!-- markdownlint-enable MD034 -->
+
+If a port number is used in the url of the Bitbucket DC instance the Git
+configuration needs to reflect this. However, due to [Issue 608](https://github.com/GitCredentialManager/git-credential-manager/issues/608)
+the port is ignored when resolving [credential.bitbucketDataCenterOAuthClientId](configuration.md#credential.bitbucketDataCenterOAuthClientId)
+and [credential.bitbucketDataCenterOAuthClientSecret](configuration.md#credential.bitbucketDataCenterOAuthClientSecret).
+<!-- markdownlint-disable MD034 -->
+For example, a Bitbucket DC host at https://example.com:7990/bitbucket would
+require configuration in the form:
+<!-- markdownlint-enable MD034 -->
+    ❯ git config --global credential.https://example.com/bitbucket.bitbucketDataCenterOAuthClientId {`Copied ClientId`}
+
+    ❯ git config --global credential.https://example.com/bitbucket.bitbucketDataCenterOAuthClientSecret {`Copied ClientSecret`}
+
+    ❯ git config --global credential.https://example.com:7990/bitbucket.usehttppath true
+
 [additional-info]:https://confluence.atlassian.com/display/BITBUCKET/App+passwords
 [atlas-run-standalone]: https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/
 [bitbucket]: https://bitbucket.org

docs/configuration.md

@@ -272,7 +272,7 @@ Value|Refresh Credentials Before Returning
 #### Example
 
 ```shell
-git config --global credential.bitbucketAlwaysRefreshCredentials 1
+git config --global credential.bitbucketAlwaysRefreshCredentials true
 ```
 
 Defaults to false/disabled.
@@ -281,6 +281,79 @@ Defaults to false/disabled.
 
 ---
 
+### credential.bitbucketValidateStoredCredentials
+
+Forces GCM to validate any stored credentials before returning them to Git. It
+does this by calling a REST API resource that requires authentication.
+
+Disabling this option reduces the HTTP traffic within GCM when it is retrieving
+credentials. This may improve user performance, but will increase the number of
+times Git remote calls fail to authenticate with the host and therefore require
+the user to re-try the Git remote call.
+
+Enabling this option helps ensure Git is always provided with valid credentials.
+
+Value|Validate credentials
+-|-
+`true`, `1`, `yes`, `on`_(default)_|Always
+`false`, `0`, `no`, `off`|Never
+
+#### Example
+
+```shell
+git config --global credential.bitbucketValidateStoredCredentials true
+```
+
+Defaults to true/enabled.
+
+**Also see: [GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS](environment.md#GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS)**
+
+---
+
+### credential.bitbucketDataCenterOAuthClientId
+
+To use OAuth with Bitbucket DC it is necessary to create an external, incoming
+[AppLink](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).
+
+It is then necessary to configure the local GCM installation with both the OAuth
+[ClientId](configuration.md#credential.bitbucketDataCenterOAuthClientId) and
+[ClientSecret](configuration.md#credential.bitbucketDataCenterOauthSecret) from
+the AppLink.
+
+#### Example
+
+```shell
+git config --global credential.bitbucketDataCenterOAuthClientId 1111111111111111111
+```
+
+Defaults to undefined.
+
+**Also see: [GCM_BITBUCKET_DATACENTER_CLIENTID](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTID)**
+
+---
+
+### credential.bitbucketDataCenterOAuthClientSecret
+
+To use OAuth with Bitbucket DC it is necessary to create an external, incoming
+[AppLink](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).
+
+It is then necessary to configure the local GCM installation with both the OAuth
+[ClientId](configuration.md#credential.bitbucketDataCenterOAuthClientId) and
+[ClientSecret](configuration.md#credential.bitbucketDataCenterOauthSecret)
+from the AppLink.
+
+#### Example
+
+```shell
+git config --global credential.bitbucketDataCenterOAuthClientSecret 222222222222222222222
+```
+
+Defaults to undefined.
+
+**Also see: [GCM_BITBUCKET_DATACENTER_CLIENTSECRET](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTSECRET)**
+
+---
+
 ### credential.gitHubAuthModes
 
 Override the available authentication modes presented during GitHub
@@ -336,7 +409,8 @@ git config --global credential.gitLabAuthModes "browser"
 ### credential.namespace
 
 Use a custom namespace prefix for credentials read and written in the OS
-credential store. Credentials will be stored in the format `{namespace}:{service}`.
+credential store. Credentials will be stored in the format
+`{namespace}:{service}`.
 
 Defaults to the value `git`.
 

docs/environment.md

@@ -430,7 +430,98 @@ export GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1
 
 Defaults to false/disabled.
 
-**Also see: [credential.bitbucketAlwaysRefreshCredentials][credential-bitbucketalwaysrefreshcredentials]**
+**Also see: [credential.bitbucketAlwaysRefreshCredentials](configuration.md#credentialbitbucketAlwaysRefreshCredentials)**
+
+---
+
+### GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS
+
+Forces GCM to validate any stored credentials before returning them to Git. It
+does this by calling a REST API resource that requires authentication.
+
+Disabling this option reduces the HTTP traffic within GCM when it is retrieving
+credentials. This may improve user performance, but will increase the number of
+times Git remote calls fail to authenticate with the host and therefore require
+the user to re-try the Git remote call.
+
+Enabling this option helps ensure Git is always provided with valid credentials.
+
+Value|Validate credentials
+-|-
+`true`, `1`, `yes`, `on`_(default)_|Always
+`false`, `0`, `no`, `off`|Never
+
+#### Windows
+
+```batch
+SET GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_BITBUCKET_VALIDATE_STORED_CREDENTIALS=1
+```
+
+Defaults to true/enabled.
+
+**Also see: [credential.bitbucketValidateStoredCredentials](configuration.md#credentialbitbucketValidateStoredCredentials)**
+
+---
+
+### GCM_BITBUCKET_DATACENTER_CLIENTID
+
+To use OAuth with Bitbucket DC it is necessary to create an external, incoming
+[AppLink](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).
+
+It is then necessary to configure the local GCM installation with the OAuth
+[ClientId](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTID) and
+[ClientSecret](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTSECRET)
+from the AppLink.
+
+#### Windows
+
+```batch
+SET GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_BITBUCKET_DATACENTER_CLIENTID=1111111111111111111
+```
+
+Defaults to undefined.
+
+**Also see: [credential.bitbucketDataCenterOAuthClientId](configuration.md#credentialbitbucketDataCenterOAuthClientId)**
+
+---
+
+### GCM_BITBUCKET_DATACENTER_CLIENTSECRET
+
+To use OAuth with Bitbucket DC it is necessary to create an external, incoming
+[AppLink](https://confluence.atlassian.com/bitbucketserver/configure-an-incoming-link-1108483657.html).
+
+It is then necessary to configure the local GCM installation with the OAuth
+[ClientId](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTID) and
+[ClientSecret](environment.md#GCM_BITBUCKET_DATACENTER_CLIENTSECRET)
+from the AppLink.
+
+#### Windows
+
+```batch
+SET GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222
+```
+
+#### macOS/Linux
+
+```bash
+export GCM_BITBUCKET_DATACENTER_CLIENTSECRET=222222222222222222222
+```
+
+Defaults to undefined.
+
+**Also see: [credential.bitbucketDataCenterOAuthClientSecret](configuration.md#credentialbitbucketDataCenterOAuthClientSecret)**
 
 ---
 
@@ -501,7 +592,8 @@ export GCM_GITLAB_AUTHMODES="browser"
 ### GCM_NAMESPACE
 
 Use a custom namespace prefix for credentials read and written in the OS
-credential store. Credentials will be stored in the format `{namespace}:{service}`.
+credential store. Credentials will be stored in the format
+`{namespace}:{service}`.
 
 Defaults to the value `git`.
 

src/shared/Atlassian.Bitbucket.Tests/Atlassian.Bitbucket.Tests.csproj

@@ -13,7 +13,7 @@
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.1.0" />
-    <PackageReference Include="ReportGenerator" Version="4.8.13" />
+    <PackageReference Include="ReportGenerator" Version="5.1.9" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.3.1" />
     <DotNetCliToolReference Include="dotnet-xunit" Version="2.3.1" />
   </ItemGroup>

src/shared/Atlassian.Bitbucket.Tests/BitbucketHelperTest.cs

@@ -0,0 +1,60 @@
+using System;
+using Xunit;
+
+namespace Atlassian.Bitbucket.Tests
+{
+    public class BitbucketHelperTest
+    {
+        [Theory]
+        [InlineData(null, false)]
+        [InlineData("", false)]
+        [InlineData("    ", false)]
+        [InlineData("bitbucket.org", true)]
+        [InlineData("BITBUCKET.ORG", true)]
+        [InlineData("BiTbUcKeT.OrG", true)]
+        [InlineData("bitbucket.example.com", false)]
+        [InlineData("bitbucket.example.org", false)]
+        [InlineData("bitbucket.org.com", false)]
+        [InlineData("bitbucket.org.org", false)]
+        public void BitbucketHelper_IsBitbucketOrg_StringHost(string str, bool expected)
+        {
+            bool actual = BitbucketHelper.IsBitbucketOrg(str);
+            Assert.Equal(expected, actual);
+        }
+
+        [Theory]
+        [InlineData("http://bitbucket.org", true)]
+        [InlineData("https://bitbucket.org", true)]
+        [InlineData("http://bitbucket.org/path", true)]
+        [InlineData("https://bitbucket.org/path", true)]
+        [InlineData("http://BITBUCKET.ORG", true)]
+        [InlineData("https://BITBUCKET.ORG", true)]
+        [InlineData("http://BITBUCKET.ORG/PATH", true)]
+        [InlineData("https://BITBUCKET.ORG/PATH", true)]
+        [InlineData("http://BiTbUcKeT.OrG", true)]
+        [InlineData("https://BiTbUcKeT.OrG", true)]
+        [InlineData("http://BiTbUcKeT.OrG/pAtH", true)]
+        [InlineData("https://BiTbUcKeT.OrG/pAtH", true)]
+        [InlineData("http://bitbucket.example.com", false)]
+        [InlineData("https://bitbucket.example.com", false)]
+        [InlineData("http://bitbucket.example.com/path", false)]
+        [InlineData("https://bitbucket.example.com/path", false)]
+        [InlineData("http://bitbucket.example.org", false)]
+        [InlineData("https://bitbucket.example.org", false)]
+        [InlineData("http://bitbucket.example.org/path", false)]
+        [InlineData("https://bitbucket.example.org/path", false)]
+        [InlineData("http://bitbucket.org.com", false)]
+        [InlineData("https://bitbucket.org.com", false)]
+        [InlineData("http://bitbucket.org.com/path", false)]
+        [InlineData("https://bitbucket.org.com/path", false)]
+        [InlineData("http://bitbucket.org.org", false)]
+        [InlineData("https://bitbucket.org.org", false)]
+        [InlineData("http://bitbucket.org.org/path", false)]
+        [InlineData("https://bitbucket.org.org/path", false)]
+        public void BitbucketHelper_IsBitbucketOrg_Uri(string str, bool expected)
+        {
+            bool actual = BitbucketHelper.IsBitbucketOrg(new Uri(str));
+            Assert.Equal(expected, actual);
+        }
+    }
+}