pkce

README

PKCE Library for Go

go-pkce provides a PKCE library for Go, implementing the S256 challenge method.

Functions are provided for generating verifiers, challenges from verifiers, and validating a challenge matches a verifier.

Additionally a wrapper around golang.org/x/oauth2.Config has been provided, which adds the additional parameters to be sent to the server.

Usage

Some usage examples.

Generate a new code verifier, challenge, and send to the server

func ExampleConfig() {
  ctx := context.Background()
  conf := &pkce.Config{
    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",
      },
    },
  }

  verifier, _ := pkce.NewCodeVerifier(32)
  challenge, _ := pkce.CodeChallenge(verifier)

  url := conf.AuthCodeURL("state", challenge, oauth2.AccessTypeOffline)

  fmt.Printf("Visit the URL and log in: %s\n", url)
  fmt.Print("Enter code from return URI: ")

  code := ""
  if _, err := fmt.Scan(&code); err != nil {
    log.Fatal(err)
  }
  tok, err := conf.Exchange(ctx, code, verifier)
  if err != nil {
    log.Fatal(err)
  }

  client := conf.Client(ctx, tok)
}

Documentation

Index

• Constants
• Variables
• func CodeChallenge(verifier string) (string, error)
• func NewCodeVerifier(length int) (string, error)
• func VerifyChallenge(verifier, challenge string) bool
• func VerifyChallengeErr(verifier, challenge string) (bool, error)
• type Config
  • func (c *Config) AuthCodeURL(state, challenge string, opts ...oauth2.AuthCodeOption) string
  • func (c *Config) Exchange(ctx context.Context, code, verifier string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)

Constants

const (
	// ParamCodeChallenge is the key used to send the challenge value to the server.
	ParamCodeChallenge = "code_challenge"

	// ParamCodeChallengeMethod is the key used to send the challenge method to the server.
	ParamCodeChallengeMethod = "code_challenge_method"

	// ParamCodeVerifier is the key used to send the code verifier to the server.
	ParamCodeVerifier = "code_verifier"

	// MethodS256 is the value to send with ParamCodeChallengeMethod to indicate we are using the
	// S256 encoding method for our challenge.
	MethodS256 = "S256"
)

Variables

var (
	// ErrCodeVerifierByteLengthInvalid is returned when calling NewCodeVerifier with a byte length that is outside the permitted value
	// (32-96 bytes).
	ErrCodeVerifierByteLengthInvalid = errors.New("length for new code verifier must be between 32-96 bytes to produce a code verifier string between 43-128 characters")

	// ErrCodeVerifierLengthInvalid is returned when calling CodeChallenge with a verifier that is outside the
	// permitted length (43-128 characters).
	ErrCodeVerifierLengthInvalid = errors.New("code verifier must be between 43-128 characters")
)

Functions

func CodeChallenge

func CodeChallenge(verifier string) (string, error)

CodeChallenge takes a verifier, ensures it is within acceptable length, and generates the challenge to be sent to the server. Errors may be returned if the verifier length is invalid, or there is an error during SHA-256 hashing.

func NewCodeVerifier

func NewCodeVerifier(length int) (string, error)

NewCodeVerifier returns a Base64 encoded string of random bytes of the given length. Length must be between 32-96, in order to produce a Base64 string between 43-128 characters in length. Will return the base64 encoded string, or an error if a byte cannot be generated.

func VerifyChallenge

func VerifyChallenge(verifier, challenge string) bool

VerifyChallenge is the same as VerifyChallengeErr, but errors are ignored and a single boolean value will be returned.

func VerifyChallengeErr

func VerifyChallengeErr(verifier, challenge string) (bool, error)

VerifyChallengeErr takes a given verifier and challenge and returns if they match. Errors may be returned if CodeChallenge(verifier) errors.

Types

type Config

type Config struct {
	oauth2.Config
}

Config is a wrapper around oauth2.Config. See https://pkg.go.dev/golang.org/x/oauth2#Config.

func (*Config) AuthCodeURL

func (c *Config) AuthCodeURL(state, challenge string, opts ...oauth2.AuthCodeOption) string

AuthCodeURL is a wrapper around oauth2's Config.AuthCodeURL, and injects the code_challenge_method of S256 and the provided challenge value into the request.

func (*Config) Exchange

func (c *Config) Exchange(ctx context.Context, code, verifier string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)

Exchange is a wrapper around oauth2's Config.Exchange, and injects the provided verifier value into the request.