Merge pull request #580 from andygrunwald/issue-579

Cloud/Authentication: Removed `BearerAuthTransport`, Removed `PATAuthTransport`, Rename `BasicAuthTransport.Password` to `BasicAuthTransport.APIToken`

Author: andygrunwald

CHANGELOG.md

@@ -326,6 +326,60 @@ After:
 client.Project.GetAll(ctx, &GetQueryOptions{})
 ```
 
+#### Cloud/Authentication: `BearerAuthTransport` removed, `PATAuthTransport` removed
+
+If you used `BearerAuthTransport` or `PATAuthTransport` for authentication, please replace it with `BasicAuthTransport`.
+
+Before:
+
+```go
+tp := jira.BearerAuthTransport{
+	Token: "token",
+}
+client, err := jira.NewClient("https://...", tp.Client())
+```
+
+or
+
+```go
+tp := jira.PATAuthTransport{
+	Token: "token",
+}
+client, err := jira.NewClient("https://...", tp.Client())
+```
+
+After:
+
+```go
+tp := jira.BasicAuthTransport{
+	Username: "username",
+	APIToken: "token",
+}
+client, err := jira.NewClient("https://...", tp.Client())
+```
+
+#### Cloud/Authentication: `BasicAuthTransport.Password` was renamed to `BasicAuthTransport.APIToken`
+
+Before:
+
+```go
+tp := jira.BasicAuthTransport{
+	Username: "username",
+	Password: "token",
+}
+client, err := jira.NewClient("https://...", tp.Client())
+```
+
+After:
+
+```go
+tp := jira.BasicAuthTransport{
+	Username: "username",
+	APIToken: "token",
+}
+client, err := jira.NewClient("https://...", tp.Client())
+```
+
 ### Breaking changes
 
 * Jira On-Premise and Jira Cloud have now different clients, because the API differs
@@ -338,6 +392,9 @@ client.Project.GetAll(ctx, &GetQueryOptions{})
 * `Issue.Update` has been removed and `Issue.UpdateWithOptions` has been renamed to `Issue.Update`
 * `Issue.GetCreateMeta` has been removed and `Issue.GetCreateMetaWithOptions` has been renamed to `Issue.GetCreateMeta`
 * `Project.GetList` has been removed and `Project.ListWithOptions` has been renamed to `Project.GetAll`
+* Cloud/Authentication: Removed `BearerAuthTransport`, because it was a (kind of) duplicate of `BasicAuthTransport`
+* Cloud/Authentication: Removed `PATAuthTransport`, because it was a (kind of) duplicate of `BasicAuthTransport`
+* Cloud/Authentication: `BasicAuthTransport.Password` was renamed to `BasicAuthTransport.APIToken`
 
 ### Features
 

README.md

@@ -100,20 +100,21 @@ For convenience, capability for basic and cookie-based authentication is include
 
 Token-based authentication uses the basic authentication scheme, with a user-generated API token in place of a user's password. You can generate a token for your user [here](https://id.atlassian.com/manage-profile/security/api-tokens). Additional information about Atlassian Cloud API tokens can be found [here](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
 
-A more thorough, [runnable example](cloud/examples/basicauth/main.go) is provided in the examples directory.
+A more thorough, [runnable example](cloud/examples/basic_auth/main.go) is provided in the examples directory.
 
 ```go
 func main() {
 	tp := jira.BasicAuthTransport{
-		Username: "username",
-		Password: "token",
+		Username: "<username>",
+		APIToken: "<api-token>",
 	}
 
-	client, err := jira.NewClient(tp.Client(), "https://my.jira.com")
+	client, err := jira.NewClient("https://my.jira.com", tp.Client())
 
-	u, _, err := client.User.Get("some_user")
+	u, _, err = client.User.GetCurrentUser(context.Background())
 
-	fmt.Printf("\nEmail: %v\nSuccess!\n", u.EmailAddress)
+	fmt.Printf("Email: %v\n", u.EmailAddress)
+	fmt.Println("Success!")
 }
 ```
 

cloud/auth_transport_basic.go renamed to cloud/auth_transport_basic_auth.go

@@ -3,22 +3,25 @@ package cloud
 import "net/http"
 
 // BasicAuthTransport is an http.RoundTripper that authenticates all requests
-// using HTTP Basic Authentication with the provided username and password.
+// using HTTP Basic Authentication with the provided username and a Personal API Token.
+//
+// Jira docs: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
+// Create a token: https://id.atlassian.com/manage-profile/security/api-tokens
 type BasicAuthTransport struct {
 	Username string
-	Password string
+	APIToken string
 
 	// Transport is the underlying HTTP transport to use when making requests.
 	// It will default to http.DefaultTransport if nil.
 	Transport http.RoundTripper
 }
 
 // RoundTrip implements the RoundTripper interface.  We just add the
-// basic auth and return the RoundTripper for this transport type.
+// basic auth information and return the RoundTripper for this transport type.
 func (t *BasicAuthTransport) RoundTrip(req *http.Request) (*http.Response, error) {
 	req2 := cloneRequest(req) // per RoundTripper contract
 
-	req2.SetBasicAuth(t.Username, t.Password)
+	req2.SetBasicAuth(t.Username, t.APIToken)
 	return t.transport().RoundTrip(req2)
 }
 

cloud/auth_transport_basic_test.go renamed to cloud/auth_transport_basic_auth_test.go

@@ -10,7 +10,7 @@ func TestBasicAuthTransport(t *testing.T) {
 	setup()
 	defer teardown()
 
-	username, password := "username", "password"
+	username, apiToken := "username", "api_token"
 
 	testMux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 		u, p, ok := r.BasicAuth()
@@ -20,14 +20,14 @@ func TestBasicAuthTransport(t *testing.T) {
 		if u != username {
 			t.Errorf("request contained basic auth username %q, want %q", u, username)
 		}
-		if p != password {
-			t.Errorf("request contained basic auth password %q, want %q", p, password)
+		if p != apiToken {
+			t.Errorf("request contained basic auth password %q, want %q", p, apiToken)
 		}
 	})
 
 	tp := &BasicAuthTransport{
 		Username: username,
-		Password: password,
+		APIToken: apiToken,
 	}
 
 	basicAuthClient, _ := NewClient(testServer.URL, tp.Client())

cloud/auth_transport_bearer.go

@@ -36,7 +36,7 @@ func main() {
 
 	tp := jira.BasicAuthTransport{
 		Username: strings.TrimSpace(username),
-		Password: strings.TrimSpace(password),
+		APIToken: strings.TrimSpace(password),
 	}
 
 	client, err := jira.NewClient(strings.TrimSpace(jiraURL), tp.Client())

cloud/auth_transport_personal_access_token.go

@@ -0,0 +1,31 @@
+package main
+
+import (
+	"context"
+	"fmt"
+
+	jira "github.com/andygrunwald/go-jira/v2/cloud"
+)
+
+func main() {
+	jiraURL := "https://go-jira-opensource.atlassian.net/"
+
+	// Jira docs: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
+	// Create a new API token: https://id.atlassian.com/manage-profile/security/api-tokens
+	tp := jira.BasicAuthTransport{
+		Username: "<username>",
+		APIToken: "<api-token>",
+	}
+	client, err := jira.NewClient(jiraURL, tp.Client())
+	if err != nil {
+		panic(err)
+	}
+
+	u, _, err := client.User.GetSelf(context.Background())
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("Email: %v\n", u.EmailAddress)
+	fmt.Println("Success!")
+}