auth

Documentation

Overview

Package auth provides authentication and authorization utilities.

Index

• Variables
• func Anonymous[T any](handleError func(http.ResponseWriter, *http.Request, error)) func(http.Handler) http.Handler
• func Authenticate(identify func(context.Context, *sess.Session) (any, error), ...) func(http.Handler) http.Handler
• func Authenticated[T any](handleError func(http.ResponseWriter, *http.Request, error)) func(http.Handler) http.Handler
• func CSRF(handleError func(http.ResponseWriter, *http.Request, error)) func(http.Handler) http.Handler
• func GenerateCSRFToken() string
• func GenerateJWT(jwks JWKS, customClaims Claims, ttl time.Duration) (string, error)
• func GetCSRFToken(ctx context.Context) string
• func GetCSRFTokenOrCreate(ctx context.Context) string
• func GetFreshCSRFToken(ctx context.Context) string
• func GetIdentity[T any](ctx context.Context) (T, error)
• func MustGetIdentity[T any](ctx context.Context) T
• func RefreshCSRFToken(ctx context.Context)
• type Claims
  • func ParseJWT(jwks JWKS, bearer string, leeway time.Duration) (Claims, error)
• type JWK
• type JWKS
  • func (jwks JWKS) Add(jwk JWK)
  • func (jwks JWKS) GetActive() (JWK, bool)
  • func (jwks JWKS) GetByKid(kid string) (JWK, bool)
  • func (jwks JWKS) Remove(jwk JWK)
• type OAuth2AuthStrategy
• type OAuth2Controller
  • func NewOAuth2Controller(config *oauth2.Config, strategy OAuth2AuthStrategy) *OAuth2Controller
  • func (p *OAuth2Controller) Callback(w http.ResponseWriter, r *http.Request)
  • func (p *OAuth2Controller) Login(w http.ResponseWriter, r *http.Request)

Variables

var (
	ErrCtxIdentityMissing = errors.New("missing identity context")
	ErrCtxSessionMissing  = errors.New("missing session context")
)

var (
	ErrJWTActiveKeyMissing   = errors.New("missing active key")
	ErrJWTClaimsParseFailure = errors.New("failed to parse claims")
	ErrJWTInvalid            = errors.New("invalid")
	ErrJWTKidClaimMissing    = errors.New("missing kid claim")
	ErrJWTKidClaimUnknown    = errors.New("unknown kid claim")
	ErrJWTSignFailure        = errors.New("failed to sign")
)

var (
	ErrOAuthAuthenticateFailure = errors.New("failed to authenticate")
	ErrOAuthCSRFTokenMismatch   = errors.New("CSRF mismatch")
	ErrOAuthExchangeFailure     = errors.New("failed to exchange authorization code")
	ErrOAuthInitiateFailure     = errors.New("failed to initiate")
)

var CSRFTokenKey = "csrf-token"

var ErrAuthIdentifyFailure = errors.New("failed to identify")

var ErrCSRFTokenMismatch = errors.New("CSRF mismatch")

var OAuthCSRFTokenKey = "oauth-csrf-token"

OAuthCSRFTokenKey is the session key for the OAuth CSRF token.

Functions

func Anonymous

func Anonymous[T any](
	handleError func(http.ResponseWriter, *http.Request, error),
) func(http.Handler) http.Handler

func Authenticate

func Authenticate(
	identify func(context.Context, *sess.Session) (any, error),
	handleError func(http.ResponseWriter, *http.Request, error),
) func(http.Handler) http.Handler

Authenticate authenticates the user and sets the identity in the context.

func Authenticated

func Authenticated[T any](
	handleError func(http.ResponseWriter, *http.Request, error),
) func(http.Handler) http.Handler

Authenticated ensures that the user is authenticated.

func CSRF

func CSRF(
	handleError func(http.ResponseWriter, *http.Request, error),
) func(http.Handler) http.Handler

CSRF protects against cross-site request forgery attacks.

func GenerateCSRFToken

func GenerateCSRFToken() string

GenerateCSRFToken generates a new CSRF token.

func GenerateJWT

func GenerateJWT(
	jwks JWKS,
	customClaims Claims,
	ttl time.Duration,
) (string, error)

GenerateJWT generates a JWT.

func GetCSRFToken

func GetCSRFToken(ctx context.Context) string

GetCSRFToken returns the CSRF token from the session.

func GetCSRFTokenOrCreate

func GetCSRFTokenOrCreate(ctx context.Context) string

GetCSRFTokenOrCreate returns the CSRF token from the session or creates a new one.

func GetFreshCSRFToken

func GetFreshCSRFToken(ctx context.Context) string

GetFreshCSRFToken returns a fresh CSRF token and stores it in the session.

func GetIdentity

func GetIdentity[T any](ctx context.Context) (T, error)

GetIdentity returns the identity from the context.

func MustGetIdentity

func MustGetIdentity[T any](ctx context.Context) T

MustGetIdentity returns the identity from the context or panics if it is missing.

func RefreshCSRFToken

func RefreshCSRFToken(ctx context.Context)

RefreshCSRFToken refreshes the CSRF token in the session.

Types

type Claims

type Claims map[string]any

Claims represents the claims of a JWT.

func ParseJWT

func ParseJWT(
	jwks JWKS,
	bearer string,
	leeway time.Duration,
) (Claims, error)

ParseJWT parses a JWT and returns its claims.

type JWK

type JWK struct {
	Kid    string
	Value  []byte
	Active bool
}

JWK represents a JSON Web Key.

type JWKS

type JWKS map[string]JWK

JWKS represents a map of JSON Web Keys.

func (JWKS) Add

func (jwks JWKS) Add(jwk JWK)

Add adds a JWK to the JWKS.

func (JWKS) GetActive

func (jwks JWKS) GetActive() (JWK, bool)

GetActive returns the first active JWK or the first JWK if none are active.

func (JWKS) GetByKid

func (jwks JWKS) GetByKid(kid string) (JWK, bool)

GetByKid returns the JWK with the given key ID.

func (JWKS) Remove

func (jwks JWKS) Remove(jwk JWK)

Remove removes a JWK from the JWKS.

type OAuth2AuthStrategy

type OAuth2AuthStrategy interface {
	Initiate(*http.Request, *sess.Session) error
	Authenticate(context.Context, *oauth2.Token, *sess.Session) (string, error)
	HandleError(http.ResponseWriter, *http.Request, error)
}

OAuth2AuthStrategy is the interface for OAuth2 authentication strategies.

type OAuth2Controller

type OAuth2Controller struct {
	// contains filtered or unexported fields
}

OAuth2Controller is a controller for OAuth2 authentication.

func NewOAuth2Controller

func NewOAuth2Controller(
	config *oauth2.Config,
	strategy OAuth2AuthStrategy,
) *OAuth2Controller

NewOAuth2Controller creates a new OAuth2Controller.

func (*OAuth2Controller) Callback

func (p *OAuth2Controller) Callback(w http.ResponseWriter, r *http.Request)

Callback handles the OAuth2 callback.

func (*OAuth2Controller) Login

func (p *OAuth2Controller) Login(w http.ResponseWriter, r *http.Request)

Login initiates the OAuth2 login flow.