caddypaseto

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 25, 2025 License: MIT Imports: 15 Imported by: 0

README

caddy-paseto

This is a Caddy module that implements HTTP authentication using Platform-Agnostic Security Tokens. It is partly based on caddy-jwt.

Features

  • Supports local and public PASETO v2, v3, and v4 keys.
  • Token validation with optional time skew tolerance.
  • Extract tokens from query string values, headers, and cookies.
  • Configurable user and meta claim extraction.
  • Allow lists for user, issuer, and audience claims.

Usage

  1. Build a Caddy binary with this module:

    xcaddy build --with go.hackfix.me/caddy-paseto

  2. Use it in your Caddy configuration:

    {
	order pasetoauth before basicauth
}

example.com {
	pasetoauth {
		key 1930e37bda12ff798927482b7e4ef7b9c2a3c7f6a3acb08c7ea55a0ec5fb35cd
		version 4
		purpose public
		time_skew_tolerance 1m
		from_query token
		from_header X-Api-Token
		from_cookies user_session
		allow_users "Alice" "Bob"
		allow_issuers https://api.example.com
		allow_audiences https://api.example.io https://learn.example.com
		user_claims aud uid user_id username login
		meta_claims "IsAdmin->is_admin" "settings.payout.paypal.enabled->is_paypal_enabled"
	}

	respond "Hello {http.auth.user.id}!" 200
}

  3. Run the Caddy server:

    ./caddy run --config Caddyfile

[!TIP] If you need a simple way to create PASETO keys and tokens, consider using paseto-cli.

Documentation

  • key: The key used to verify or decrypt PASETO tokens. It must be the public key if purpose is "public", or the symmetric key if purpose is "local". It can be specified as either a hex or PEM encoded string.

  • purpose: The PASETO protocol purpose. It can either be "local" for shared-key (symmetric) encryption, or "public" for public-key (asymmetric) signing. The default is "public".

  • version: The PASETO protocol version. Valid values: 2, 3, 4. The default is 4.

  • time_skew_tolerance: The amount of time to allow token claim times (iat, nbf, exp) to be from the current system time to account for clock skew between systems. The default is 30s.

  • from_query: A list of HTTP request query string parameter names tokens should be retrieved from. If multiple names are specified, all the corresponding query values will be treated as candidate tokens, and each one will be verified until a valid one is reached.

    Priority: from_query > from_header > from_cookies.

  • from_header: Works like from_query, but defines a list of HTTP header names tokens should be retrieved from.

  • from_cookies: Works like from_query, but defines a list of HTTP cookie names tokens should be retrieved from.

  • user_claims: A list of token claim names from which to extract the ID of the authenticated user. By default, this value will be set to "sub".

    If multiple names are specified, the first non-empty value of the claim in the token payload will be used as the ID of the authenticated user, and the placeholder {http.auth.user.id} will be set to the ID. For example, the value uid username will set "eva" as the final user ID from the token payload: { "username": "eva" }.

    If no non-empty values are found, the request fails authentication.

  • meta_claims: A list of token claim names to populate {http.auth.user.*} metadata values.

    Syntax: <claim>[ -> <placeholder>].

    The placeholder is optional, and is used to remap a claim name to a metadata key. If not specified, the metadata key will be the same as the claim name.

    NOTE: The name in the placeholder should adhere to Caddy conventions (snake casing).

    Examples:

    • meta_claims group "IsAdmin -> is_admin": The value of the group claim will be available as {http.auth.user.group}, and the value of the IsAdmin claim will be available as {http.auth.user.is_admin}.

    • meta_claims "user_info.role -> role": Nested claim paths are supported with dot notation, so a token with the claim "user_info": { "role": "admin" } will set the value of {http.auth.user.role} as "admin".

  • allow_audience: A list of allowed audiences. If non-empty, the "aud" claim must exist in the token payload and its value must be specified here for verification to succeed. Otherwise, the "aud" claim is not required, and any value will be allowed.

  • allow_issuers: A list of allowed issuers. If non-empty, the "iss" claim must exist in the token payload and its value must be specified here for verification to succeed. Otherwise, the "iss" claim is not required, and any value will be allowed.

  • allow_users: A list of allowed users. If non-empty, and the user claim is defined in the token payload, only specified users will pass the verification. Otherwise, all users will be allowed.

License

MIT

Documentation

Overview

Package caddypaseto is a Caddy module that implements HTTP authentication using PASETO. It is partly based on caddy-jwt.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type PasetoAuth 

type PasetoAuth struct {
	// Key is the key used to verify or decrypt PASETO tokens.
	// It must be the public key if `purpose` is 'public', or the symmetric key if
	// `purpose` is 'local'. It can be specified as either a hex or PEM encoded string.
	Key string `json:"key"`

	// Purpose is the PASETO protocol purpose. It can either be 'local' for
	// shared-key (symmetric) encryption, or 'public' for public-key (asymmetric)
	// signing. The default is 'public'.
	Purpose paseto.Purpose `json:"purpose"`

	// Version is the PASETO protocol version. The default is 4.
	Version paseto.Version `json:"version"`

	// TimeSkewTolerance is the amount of time to allow token claim times (iat,
	// nbf, exp) to be from the current system time to account for clock skew
	// between systems. The default is 30s.
	TimeSkewTolerance time.Duration `json:"time_skew_tolerance"`

	// FromQuery defines a list of HTTP request query string parameter names
	// tokens should be retrieved from.
	//
	// If multiple names are specified, all the corresponding query values will be
	// treated as candidate tokens, and each one will be verified until a valid
	// one is reached.
	//
	// Priority: from_query > from_header > from_cookies.
	FromQuery []string `json:"from_query"`

	// FromHeader works like FromQuery, but defines a list of HTTP header names
	// tokens should be retrieved from.
	FromHeader []string `json:"from_header"`

	// FromCookie works like FromQuery, but defines a list of HTTP cookie names
	// tokens should be retrieved from.
	FromCookies []string `json:"from_cookies"`

	// UserClaims defines a list of token claim names from which to extract the ID
	// of the authenticated user.
	//
	// By default, this value will be set to []string{"sub"}.
	//
	// If multiple names are specified, the first non-empty value of the claim in
	// the token payload will be used as the ID of the authenticated user, and the
	// placeholder `{http.auth.user.id}` will be set to the ID. For example, the
	// value `uid username` will set "eva" as the final user ID from the token
	// payload: `{ "username": "eva" }`.
	//
	// If no non-empty values are found, the request fails authentication.
	UserClaims []string `json:"user_claims"`

	// MetaClaims defines a map to populate {http.auth.user.*} metadata placeholders.
	// The key is the claim in the token payload, the value is the placeholder name.
	// e.g. {"IsAdmin": "is_admin"} can populate {http.auth.user.is_admin} with
	// the value of `IsAdmin` in the token payload if found, otherwise "".
	//
	// NOTE: The name in the placeholder should adhere to Caddy conventions
	// (snake casing).
	//
	// Caddyfile:
	// Use syntax `<claim>[-> <placeholder>]` to define a map item. The placeholder is
	// optional, if not specified, use the same name as the claim.
	// E.g.:
	//
	//     meta_claims "IsAdmin -> is_admin" "group"
	//
	// is equal to {"IsAdmin": "is_admin", "group": "group"}.
	//
	// Nested claim paths are supported with dot notation. So for the following
	// token payload:
	//
	//     { ..., "user_info": { "role": "admin" }}
	//
	// If you want to populate {http.auth.user.role} with "admin", you can use
	//
	//     meta_claims "user_info.role -> role"
	MetaClaims map[string]string `json:"meta_claims"`

	// AllowAudiences defines a list of allowed audiences. If non-empty, the "aud"
	// claim must exist in the token payload and its value must be specified here
	// for verification to succeed. Otherwise, the "aud" claim is not required,
	// and any value will be allowed.
	AllowAudiences []string `json:"allow_audiences"`

	// AllowIssuers defines a list of allowed issuers. If non-empty, the "iss"
	// claim must exist in the token payload and its value must be specified here
	// for verification to succeed. Otherwise, the "iss" claim is not required,
	// and any value will be allowed.
	AllowIssuers []string `json:"allow_issuers"`

	// AllowUsers defines a list of allowed users. If non-empty, and the user
	// claim is defined in the token payload, only specified users will pass the
	// verification. Otherwise, all users will be allowed.
	AllowUsers []string `json:"allow_users"`
	// contains filtered or unexported fields
}

PasetoAuth implements PASETO authentication.

func (*PasetoAuth) Authenticate 

func (p *PasetoAuth) Authenticate(_ http.ResponseWriter, r *http.Request) (caddyauth.User, bool, error)

Authenticate extracts the token according to the module configuration, parses and validates it, and authenticates the user of the request.

func (PasetoAuth) CaddyModule 

func (PasetoAuth) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*PasetoAuth) Provision 

func (p *PasetoAuth) Provision(ctx caddy.Context) error

Provision sets up the module.

func (*PasetoAuth) Validate 

func (p *PasetoAuth) Validate() error

Validate validates that the module has a usable config, and initializes defaults and internal values.

Source Files

View all Source files

Directories

Path Synopsis
cmd
caddy-paseto command
Package main is a Caddy server with the caddy-paseto module.
 Package main is a Caddy server with the caddy-paseto module.
Package testutil implements some common test utilities.
 Package testutil implements some common test utilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.