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
- type Method
- type 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 ¶
Constants ¶
This section is empty.
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
Output:
Types ¶
type Challenge ¶
type Challenge string
Challenge holds the encoded code challenge as described in RFC 7636 section 4.2.
func GetChallenge ¶
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 ¶
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
Output:
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.
Source Files