pkce

README

mirg/go-pkce

Helpers to use the Proof Key for Code Exchange (PKCE) protocol when utilizing the Authorization Code flow for OAuth2.

See RFC 7636 for more information on PKCE.

Usage

Installation

go get git.sr.ht/~mirg/go-pkce

Redirecting out

var config oauth2.Config

// Generate a new verifier using default options.
ver := pkce.NewVerifier()

// Get the URL for authentication using the authorization code flow.
authCodeURL := config.AuthCodeURL("my-state", pkce.AuthCodeURLOptions(ver)...)

Code exchange

var (
	config oauth2.Config
	r *http.Request
)

code := r.URL.Query().Get("code")

// Exchange the code for the token. pkce.ExchangeOptions adds the required
// query parameters.
token, err := config.Exchange(r.Context(), code, pkce.ExchangeOptions(ver)...)

License

MIT, see LICENSE.

Copyright 2022 Marcus Pettersen Irgens

Documentation

Overview

Package pkce provides helpers to use the Proof Key for Code Exchange (PKCE) protocol when utilizing the Authorization Code flow for OAuth2.

See https://datatracker.ietf.org/doc/html/rfc7636 for more information on PKCE.

Index

• Variables
• func AuthCodeURLOptions(v Verifier) []oauth2.AuthCodeOption
• func ExchangeOptions(v Verifier) []oauth2.AuthCodeOption
• type Challenge
  • func GetChallenge(v Verifier) Challenge
• type Method
  • func (m Method) String() string
• type Verifier
  • func NewVerifier() Verifier
• type VerifierOptions
  • func (o VerifierOptions) AuthCodeURLOptions(v Verifier) []oauth2.AuthCodeOption
  • func (o VerifierOptions) ExchangeOptions(v Verifier) []oauth2.AuthCodeOption
  • func (o VerifierOptions) GetChallenge(v Verifier) Challenge
  • func (o VerifierOptions) NewVerifier() Verifier
  • func (o VerifierOptions) Valid(v Verifier, c Challenge) bool

Examples

• ExchangeOptions
• NewVerifier

Variables

var DefaultVerifierOptions = VerifierOptions{
	Length: DefaultVerifierLength,
	Method: SHA256,
}

DefaultVerifierOptions has sane default values for the PKCE protocol.

Functions

func AuthCodeURLOptions

func AuthCodeURLOptions(v Verifier) []oauth2.AuthCodeOption

AuthCodeURLOptions returns oauth2.AuthCodeOptions for the AuthCodeURL method of oauth2.Config using the default options.

func ExchangeOptions

func ExchangeOptions(v Verifier) []oauth2.AuthCodeOption

ExchangeOptions returns oauth2.AuthCodeOptions for the Exchange method of oauth2.Config using the default options.

Example

// Substitute this config with your actual oauth2 configuration.
var config oauth2.Config
// In this example, the user has returned to the OAuth2 redirect URL.
var r *http.Request
// our verifier generated when we redirected the user out, stored somewhere
var ver pkce.Verifier

code, _ := r.URL.Query().Get("code"), r.URL.Query().Get("state")

// Exchange the code for the token. pkce.ExchangeOptions adds the required
// query parameters.
token, err := config.Exchange(r.Context(), code, pkce.ExchangeOptions(ver)...)
if err != nil {
	panic(err) // handle this gracefully
}

// Use your token.
_ = token

Types

type Challenge

type Challenge string

Challenge holds the encoded code challenge as described in RFC 7636 section 4.2.

func GetChallenge

func GetChallenge(v Verifier) Challenge

GetChallenge returns the challenge for Verifier using the default options.

type Method

type Method int

Method is the code challenge method as defined in RFC 7636 section 3.

const (
	// DefaultVerifierLength is the default and recommended length of the code
	// verifier. See RFC 7636 section 4.1.
	DefaultVerifierLength = 43

	// Plain challenge type. Never use this.
	Plain Method = -1

	// SHA256 challenge type.
	SHA256 Method = iota
)

func (Method) String

func (m Method) String() string

String returns the string representation of Method, specifically the representation used when sending the method with the Authorization Request. See RFC 7636 section 4.3. for names and RFC 6749 section 4.1.1. for the auth code flow.

type Verifier

type Verifier string

Verifier holds the encoded code verifier as described in RFC 7636 section 4.1.

func NewVerifier

func NewVerifier() Verifier

NewVerifier creates a new code verifier with the default options.

Example

// Substitute this config with your actual oauth2 configuration.
var config oauth2.Config

// Generate a new verifier.
ver := pkce.NewVerifier()

// Get the URL for authentication using the authorization code flow.
authCodeURL := config.AuthCodeURL("my-state", pkce.AuthCodeURLOptions(ver)...)

// Now store the verifier and use it when the client returns, and redirect the user.
_ = authCodeURL

type VerifierOptions

type VerifierOptions struct {
	// Desired length of the verifier. Must be between 43 and 128, inclusive.
	// As a special case, 0 defaults to the minimum value of 43.
	Length uint8

	// Challenge method as per RFC7636 section 4.3. Note that if the client is
	// capable of using "S256", it MUST use "S256", as "S256" is Mandatory To
	// Implement (MTI) on the server.
	Method Method
}

VerifierOptions are the options for dealing with verifiers.

func (VerifierOptions) AuthCodeURLOptions

func (o VerifierOptions) AuthCodeURLOptions(v Verifier) []oauth2.AuthCodeOption

AuthCodeURLOptions returns the authorization code flow options for oauth2.Config.AuthCodeURL.

func (VerifierOptions) ExchangeOptions

func (o VerifierOptions) ExchangeOptions(v Verifier) []oauth2.AuthCodeOption

ExchangeOptions returns the authorization code flow options for oauth2.Config.Exchange.

func (VerifierOptions) GetChallenge

func (o VerifierOptions) GetChallenge(v Verifier) Challenge

GetChallenge returns a code challenge using VerifierOptions. If an invalid value for VerifierOptions.Method is set, the behaviour is undefined.

func (VerifierOptions) NewVerifier

func (o VerifierOptions) NewVerifier() Verifier

NewVerifier creates a code verifier using the configuration values in VerifierOptions. NewVerifier panics if VerifierOptions.Length is less than 43 or more than 128, except for 0, which defaults to (the recommended) minimum value, 43. The resulting verifier is ready for use and does not need any additional encoding.

func (VerifierOptions) Valid

func (o VerifierOptions) Valid(v Verifier, c Challenge) bool

Valid checks if a Verifier is valid for the given Challenge.