auth

Documentation

Overview

Package auth provides authentication and authorization support.

Index

• Constants
• type Auth
  • func New(algorithm string, lookupFunc PublicKeyLookup, keys Keys) (*Auth, error)
  • func (a *Auth) AddKey(privateKey *rsa.PrivateKey, kid string)
  • func (a *Auth) GenerateToken(kid string, claims Claims) (string, error)
  • func (a *Auth) RemoveKey(kid string)
  • func (a *Auth) ValidateToken(tokenStr string) (Claims, error)
• type Claims
  • func (c Claims) HasRole(roles ...string) bool
  • func (c Claims) Valid() error
• type Keys
• type PublicKeyLookup

Constants

const (
	RoleAdmin    = "ADMIN"
	RoleMaster   = "MASTER"
	RoleOperator = "OPERATOR"
)

These are the expected values for Claims.Roles.

const Key ctxKey = 1

Key is used to store/retrieve a Claims value from a context.Context.

Types

type Auth

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

Auth is used to authenticate clients. It can generate a token for a set of user claims and recreate the claims by parsing the token.

func New

func New(algorithm string, lookupFunc PublicKeyLookup, keys Keys) (*Auth, error)

New creates an *Authenticator.

An authenticator maintains the state required to handle JWT processing.

It requires a set of keys (Keys) for generating tokens. The algorithms to use (RS256 | HS256), and the key lookup function to perform the job of retrieving a public key for a given KID.

func (*Auth) AddKey

func (a *Auth) AddKey(privateKey *rsa.PrivateKey, kid string)

AddKey adds a private key and kid to the local store.

func (*Auth) GenerateToken

func (a *Auth) GenerateToken(kid string, claims Claims) (string, error)

GenerateToken generates a JWT using the provided claims based on a given KID

func (*Auth) RemoveKey

func (a *Auth) RemoveKey(kid string)

RemoveKey removes from local storage a key based on the provided kid.

func (*Auth) ValidateToken

func (a *Auth) ValidateToken(tokenStr string) (Claims, error)

ValidateToken recreates the Claims used to generate a token. It verifies that the token was signed a valid key.

type Claims

type Claims struct {
	jwt.RegisteredClaims
	Roles []string `json:"roles"`
}

Claims represents the authorization claims transmitted via a JWT.

func (Claims) HasRole

func (c Claims) HasRole(roles ...string) bool

HasRole returns true if the claims has at least one of the provided roles.

func (Claims) Valid

func (c Claims) Valid() error

Valid is called for validating parsed tokens. It wraps original jwt.RegisteredClaims.Valid method and provides custom wrapped error.

type Keys

type Keys map[string]*rsa.PrivateKey

Keys represents an in memory store of keys.

type PublicKeyLookup

type PublicKeyLookup func(publicKID string) (*rsa.PublicKey, error)

KeyLookupFunc defines the signature of a function to lookup public keys.

In a production system, a key id (KID) is used to retrieve the correct public key to parse a JWT for auth and claims. A key lookup function is provided for retrieving a public key for a given KID.

A key lookup function is required for creating an Authenticator (type Auth).

* Private keys should be rotated. During the transition period, tokens signed with the old and new keys can coexist by looking up the correct public key by KID.

* KID to public key resolution is usually accomplished via a public JWKS endpoint. See https://auth0.com/docs/jwks for more details.