oauth2: support PKCE

Implements incoming proposal golang/go#59835

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
@@ -71,12 +57,7 @@ type authHandlerSource struct {
 
 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)}
-	}
-	url := source.config.AuthCodeURL(source.state, authCodeUrlOptions...)
+	url := source.config.AuthCodeURLWithPKCE(source.state, source.pkce)
 	code, state, err := source.authHandler(url)
 	if err != nil {
 		return nil, err
@@ -86,9 +67,5 @@ 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)}
-	}
-	return source.config.Exchange(source.ctx, code, exchangeOptions...)
+	return source.config.ExchangeWithPKCE(source.ctx, code, source.pkce)
 }

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

@@ -121,7 +121,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)
 }
@@ -139,16 +139,12 @@ 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
-// 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.
-func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
+func (c *Config) AuthCodeURLWithPKCE(state string, pkce *PKCEParams, opts ...AuthCodeOption) string {
 	var buf bytes.Buffer
 	buf.WriteString(c.Endpoint.AuthURL)
 	v := url.Values{
@@ -162,9 +158,11 @@ 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)
 	}
+	if pkce != nil {
+		pkce.challengeOption().setValue(v)
+	}
 	for _, opt := range opts {
 		opt.setValue(v)
 	}
@@ -177,6 +175,10 @@ func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
 	return buf.String()
 }
 
+func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
+	return c.AuthCodeURLWithPKCE(state, nil, opts...)
+}
+
 // PasswordCredentialsToken converts a resource owner username and password
 // pair into a token.
 //
@@ -208,24 +210,28 @@ func (c *Config) PasswordCredentialsToken(ctx context.Context, username, passwor
 //
 // The code will be in the *http.Request.FormValue("code"). Before
 // calling Exchange, be sure to validate FormValue("state").
-//
-// Opts may include the PKCE verifier code if previously used in AuthCodeURL.
-// See https://www.oauth.com/oauth2-servers/pkce/ for more info.
-func (c *Config) Exchange(ctx context.Context, code string, opts ...AuthCodeOption) (*Token, error) {
+func (c *Config) ExchangeWithPKCE(ctx context.Context, code string, pkce *PKCEParams, opts ...AuthCodeOption) (*Token, error) {
 	v := url.Values{
 		"grant_type": {"authorization_code"},
 		"code":       {code},
 	}
 	if c.RedirectURL != "" {
 		v.Set("redirect_uri", c.RedirectURL)
 	}
+	if pkce != nil {
+		pkce.verifierOption().setValue(v)
+	}
 	for _, opt := range opts {
 		opt.setValue(v)
 	}
 	return retrieveToken(ctx, c, v)
 }
 
-// Client returns an HTTP client using the provided token.
+func (c *Config) Exchange(ctx context.Context, code string, opts ...AuthCodeOption) (*Token, error) {
+	return c.ExchangeWithPKCE(ctx, code, nil, opts...)
+}
+
+`345432Q// Client returns an HTTP client using the provided token.
 // The token will auto-refresh as necessary. The underlying
 // HTTP transport will be obtained using the provided context.
 // The returned client and its Transport should not be modified.

pkce.go

@@ -0,0 +1,64 @@
+// Copyright 2014 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package oauth2
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"io"
+	"net/url"
+)
+
+// 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,
+	}
+}