jwtauth

Documentation

Overview

Package jwtauth includes helper functions for creating HTTP clients and servers that can perform JWT authorization via Bearer tokens.

Index

• Constants
• func NewHTTPClient(src TokenSource) *http.Client
• type Error
  • func (e *Error) Write(rw http.ResponseWriter)
• type HTTPVerifier
  • func (v *HTTPVerifier) AddAuthorization(handler http.Handler) http.Handler
• type JWTTokenSource
  • func (s *JWTTokenSource) Token() (*Token, error)
• type KeyFunc
• type Token
  • func (t *Token) String() string
• type TokenSource

Constants

const (
	// DefaultTokenLifetime is the default duration tokens are valid for.
	DefaultTokenLifetime = 10 * time.Minute
	// DefaultAcceptableSkew is the clock skew allowed between token creation and token validation
	// machines. Tokens are not valid before (iat - clock_skew) and after (exp + clock_skew).
	DefaultAcceptableSkew = 5 * time.Second
)

Functions

func NewHTTPClient

func NewHTTPClient(src TokenSource) *http.Client

NewHTTPClient constructs a new HTTP client that attempts to perform authorization via Bearer tokens created by src.

If src is nil then a default HTTP client is returned (i.e., one that does not perform any authorization).

For a simple example of how to use this, see the test.

Types

type Error

type Error struct {
	// Code is the HTTP code to send back to the client.
	Code int
	// Title is a short description of the error.
	Title string
}

Error models an error that can be sent in the respresentation of an OpenAPI JSON error, as defined in the CA OpenAPI Specification.

func (*Error) Write

func (e *Error) Write(rw http.ResponseWriter)

type HTTPVerifier

type HTTPVerifier struct {
	// Generator that creates keys for HS256. For security reasons, the keys must be
	// at least 256-bit long (see https://tools.ietf.org/html/rfc7518#section-3.2). If the key is
	// not sufficiently long, token creation will return an error.
	Generator KeyFunc
	// Logger is an optional Logger to be used for listing successful/unsuccessful authorization
	// attempts. If nil, no logging is done.
	Logger log.Logger
}

HTTPVerifier verifies a JWT token as defined by the SCION CA JWT specification.

The only accepted algorithm is HS256.

func (*HTTPVerifier) AddAuthorization

func (v *HTTPVerifier) AddAuthorization(handler http.Handler) http.Handler

AddAuthorization decorates handler with a step that first performs JWT Bearer authorization before chaining the call to the initial handler.

type JWTTokenSource

type JWTTokenSource struct {
	// Subject is an informational field that will be used as the JWT "sub" and
	// "iss" claims. If empty, the "sub" and "iss" claims are not set.
	Subject string
	// Lifetime is the duration a token is valid for. If it is 0, then DefaultTokenLifetime is
	// used.
	Lifetime time.Duration
	// IssuedAt is the timestamp when the token should report that it was issued. Values are
	// rounded down to whole seconds. If not set, time.Now() is used instead.
	IssuedAt time.Time
	// Generator that creates symmetric keys for HS256. For security
	// reasons, the generated key must be at least 256-bit long (see
	// https://tools.ietf.org/html/rfc7518#section-3.2). If the key is not
	// sufficiently long, token creation will return an error.
	Generator KeyFunc
}

JWTTokenSource creates JWT tokens as defined by the SCION CA JWT specification.

The signature algorithm is set to HS256.

func (*JWTTokenSource) Token

func (s *JWTTokenSource) Token() (*Token, error)

type KeyFunc

type KeyFunc func() ([]byte, error)

KeyFunc is a generator for keys used in JWT token creation.

type Token

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

Token is an HTTP Bearer token used by the SCION control-plane.

The String method returns the representation of the token as it should be used in HTTP headers.

func (*Token) String

func (t *Token) String() string

type TokenSource

type TokenSource interface {
	Token() (*Token, error)
}

A TokenSource creates Bearer tokens for HTTP clients to use.