make PKCE easier

Author: hickford

authhandler/authhandler.go

@@ -13,21 +13,7 @@ import (
 	"golang.org/x/oauth2"
 )
 
-const (
-	// Parameter keys for AuthCodeURL method to support PKCE.
-	codeChallengeKey       = "code_challenge"
-	codeChallengeMethodKey = "code_challenge_method"
-
-	// Parameter key for Exchange method to support PKCE.
-	codeVerifierKey = "code_verifier"
-)
-
-// PKCEParams holds parameters to support PKCE.
-type PKCEParams struct {
-	Challenge       string // The unpadded, base64-url-encoded string of the encrypted code verifier.
-	ChallengeMethod string // The encryption method (ex. S256).
-	Verifier        string // The original, non-encrypted secret.
-}
+type PKCEParams = oauth2.PKCEParams
 
 // AuthorizationHandler is a 3-legged-OAuth helper that prompts
 // the user for OAuth consent at the specified auth code URL
@@ -73,8 +59,7 @@ func (source authHandlerSource) Token() (*oauth2.Token, error) {
 	// Step 1: Obtain auth code.
 	var authCodeUrlOptions []oauth2.AuthCodeOption
 	if source.pkce != nil && source.pkce.Challenge != "" && source.pkce.ChallengeMethod != "" {
-		authCodeUrlOptions = []oauth2.AuthCodeOption{oauth2.SetAuthURLParam(codeChallengeKey, source.pkce.Challenge),
-			oauth2.SetAuthURLParam(codeChallengeMethodKey, source.pkce.ChallengeMethod)}
+		authCodeUrlOptions = append(authCodeUrlOptions, source.pkce.ChallengeOption())
 	}
 	url := source.config.AuthCodeURL(source.state, authCodeUrlOptions...)
 	code, state, err := source.authHandler(url)
@@ -87,8 +72,8 @@ func (source authHandlerSource) Token() (*oauth2.Token, error) {
 
 	// Step 2: Exchange auth code for access token.
 	var exchangeOptions []oauth2.AuthCodeOption
-	if source.pkce != nil && source.pkce.Verifier != "" {
-		exchangeOptions = []oauth2.AuthCodeOption{oauth2.SetAuthURLParam(codeVerifierKey, source.pkce.Verifier)}
+	if source.pkce != nil {
+		exchangeOptions = append(exchangeOptions, source.pkce.VerifierOption())
 	}
 	return source.config.Exchange(source.ctx, code, exchangeOptions...)
 }

example_test.go

@@ -8,62 +8,19 @@ import (
 	"context"
 	"fmt"
 	"log"
-	"net/http"
-	"time"
 
 	"golang.org/x/oauth2"
 )
 
 func ExampleConfig() {
 	ctx := context.Background()
-	conf := &oauth2.Config{
-		ClientID:     "YOUR_CLIENT_ID",
-		ClientSecret: "YOUR_CLIENT_SECRET",
-		Scopes:       []string{"SCOPE1", "SCOPE2"},
-		Endpoint: oauth2.Endpoint{
-			AuthURL:  "https://provider.com/o/oauth2/auth",
-			TokenURL: "https://provider.com/o/oauth2/token",
-		},
-	}
+	var conf oauth2.Config
 
-	// Redirect user to consent page to ask for permission
-	// for the scopes specified above.
-	url := conf.AuthCodeURL("state", oauth2.AccessTypeOffline)
-	fmt.Printf("Visit the URL for the auth dialog: %v", url)
-
-	// Use the authorization code that is pushed to the redirect
-	// URL. Exchange will do the handshake to retrieve the
-	// initial access token. The HTTP Client returned by
-	// conf.Client will refresh the token as necessary.
-	var code string
-	if _, err := fmt.Scan(&code); err != nil {
-		log.Fatal(err)
-	}
-	tok, err := conf.Exchange(ctx, code)
-	if err != nil {
-		log.Fatal(err)
-	}
-
-	client := conf.Client(ctx, tok)
-	client.Get("...")
-}
-
-func ExampleConfig_customHTTP() {
-	ctx := context.Background()
-
-	conf := &oauth2.Config{
-		ClientID:     "YOUR_CLIENT_ID",
-		ClientSecret: "YOUR_CLIENT_SECRET",
-		Scopes:       []string{"SCOPE1", "SCOPE2"},
-		Endpoint: oauth2.Endpoint{
-			TokenURL: "https://provider.com/o/oauth2/token",
-			AuthURL:  "https://provider.com/o/oauth2/auth",
-		},
-	}
+	pkce := oauth2.GeneratePKCEParams()
 
 	// Redirect user to consent page to ask for permission
 	// for the scopes specified above.
-	url := conf.AuthCodeURL("state", oauth2.AccessTypeOffline)
+	url := conf.AuthCodeURL("state", oauth2.AccessTypeOffline, pkce.ChallengeOption())
 	fmt.Printf("Visit the URL for the auth dialog: %v", url)
 
 	// Use the authorization code that is pushed to the redirect
@@ -74,16 +31,11 @@ func ExampleConfig_customHTTP() {
 	if _, err := fmt.Scan(&code); err != nil {
 		log.Fatal(err)
 	}
-
-	// Use the custom HTTP client when requesting a token.
-	httpClient := &http.Client{Timeout: 2 * time.Second}
-	ctx = context.WithValue(ctx, oauth2.HTTPClient, httpClient)
-
-	tok, err := conf.Exchange(ctx, code)
+	tok, err := conf.Exchange(ctx, code, pkce.VerifierOption())
 	if err != nil {
 		log.Fatal(err)
 	}
 
 	client := conf.Client(ctx, tok)
-	_ = client
+	client.Get("...")
 }

oauth2.go

@@ -11,7 +11,11 @@ package oauth2 // import "golang.org/x/oauth2"
 import (
 	"bytes"
 	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
 	"errors"
+	"io"
 	"net/http"
 	"net/url"
 	"strings"
@@ -120,7 +124,7 @@ var (
 	ApprovalForce AuthCodeOption = SetAuthURLParam("prompt", "consent")
 )
 
-// An AuthCodeOption is passed to Config.AuthCodeURL.
+// An AuthCodeOption may be passed to Config.AuthCodeURL or Config.Exchange.
 type AuthCodeOption interface {
 	setValue(url.Values)
 }
@@ -138,15 +142,14 @@ func SetAuthURLParam(key, value string) AuthCodeOption {
 // AuthCodeURL returns a URL to OAuth 2.0 provider's consent page
 // that asks for permissions for the required scopes explicitly.
 //
-// State is a token to protect the user from CSRF attacks. You must
-// always provide a non-empty string and validate that it matches the
-// the state query parameter on your redirect callback.
-// See http://tools.ietf.org/html/rfc6749#section-10.12 for more info.
+// State is an opaque value used by the client to maintain state
+// between the request and callback.
 //
 // Opts may include AccessTypeOnline or AccessTypeOffline, as well
 // as ApprovalForce.
-// It can also be used to pass the PKCE challenge.
-// See https://www.oauth.com/oauth2-servers/pkce/ for more info.
+//
+// To protect against cross-site request forgery (CSRF),
+// it is recommended to pass PKCEParams.ChallengeOption().
 func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
 	var buf bytes.Buffer
 	buf.WriteString(c.Endpoint.AuthURL)
@@ -161,7 +164,6 @@ func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
 		v.Set("scope", strings.Join(c.Scopes, " "))
 	}
 	if state != "" {
-		// TODO(light): Docs say never to omit state; don't allow empty.
 		v.Set("state", state)
 	}
 	for _, opt := range opts {
@@ -379,3 +381,55 @@ func ReuseTokenSource(t *Token, src TokenSource) TokenSource {
 		new: src,
 	}
 }
+
+// PKCEParams holds a PKCE challenge and verifier as described in RFC 7636
+// https://datatracker.ietf.org/doc/html/rfc7636
+type PKCEParams struct {
+	Challenge       string
+	ChallengeMethod string
+	Verifier        string
+}
+
+const (
+	codeChallengeKey       = "code_challenge"
+	codeChallengeMethodKey = "code_challenge_method"
+	codeVerifierKey        = "code_verifier"
+)
+
+// ChallengeOption should be passed to Config.AuthCodeURL. The option returned sets the code_challenge and code_challenge_method parameters.
+func (p *PKCEParams) ChallengeOption() AuthCodeOption {
+	return set2Values{k1: codeChallengeKey, v1: p.Challenge, k2: codeChallengeMethodKey, v2: p.ChallengeMethod}
+}
+
+type set2Values struct{ k1, v1, k2, v2 string }
+
+func (p set2Values) setValue(m url.Values) {
+	m.Set(p.k1, p.v1)
+	m.Set(p.k2, p.v2)
+}
+
+// VerifierOption should be passed to Config.Exchange. The option returned sets the code_verifier parameters.
+func (p *PKCEParams) VerifierOption() AuthCodeOption {
+	return SetAuthURLParam(codeVerifierKey, p.Verifier)
+}
+
+// GeneratePKCEParams generates a code verifier with 32 octets of randomness and a S256 challenge (this follows recommendations in RFC 7636).
+//
+// A fresh verifier should be generated for each AuthCodeURL call.
+func GeneratePKCEParams() *PKCEParams {
+	// "RECOMMENDED that the output of a suitable random number generator be used to create a 32-octet
+	// sequence.  The octet sequence is then base64url-encoded to produce a 43-octet URL-safe string to use as the code verifier."
+	// https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+	data := make([]byte, 32)
+	if _, err := io.ReadFull(rand.Reader, data); err != nil {
+		panic(err)
+	}
+	verifier := base64.URLEncoding.EncodeToString(data)
+	sha := sha256.Sum256([]byte(verifier))
+	challenge := base64.URLEncoding.EncodeToString(sha[:])
+	return &PKCEParams{
+		Challenge:       challenge,
+		ChallengeMethod: "S256",
+		Verifier:        verifier,
+	}
+}