auth

README

Auth

The core/auth package provides functions for services to issue and sign api consumer tokens.

Using the issuer

Start a new issuer

You can initiate an token issuer by passing a valid RSA or ECDSA PEM block.

var private = []byte(`... private key ...`)
issuer := auth.NewIssuerFromPEM(private, jwt.SigningMethodRS256)

Issue new tokens

A token can be issued with any struct that follows the jwt.Claims interface.

claims := jwt.StandardClaims{
	Id:        "1234",
	Issuer:    "Tests",
	Audience:  "Developers",
	Subject:   "Example",
	ExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
	IssuedAt:  time.Now().Unix(),
	NotBefore: time.Now().Unix(),
}
raw, err := issuer.Issue(&claims)
if err != nil {
	return
}

Using the parser

Start a new parser

You can initiate an token parser by passing a valid RSA or ECDSA PEM block.

var public = []byte(`... public key ...`)
var fn func(pk crypto.PublicKey) jwt.Keyfunc {
	return func(token *jwt.Token) (interface{}, error) {
		if _, ok := token.Method.(*jwt.SigningMethodRSA); !ok {
			return pk, fmt.Errorf("unknown algorithm: %v", token.Header["alg"])
		}
		return pk, nil
	}
}
parser := auth.NewParserFromPEM(public, fn)

Parse existing tokens

Now you can parse any token that is signed with the public key provided to the parser.

var claims jwt.StandardClaims
err := parser.Parse(`... jwt ...`, &claims)
if err != nil {
	return
}

Mocking the issuer & parser

An issuer can be mocked with a temporary key pair for testing.

issuer, parser, err := authmock.NewRSAIssuerAndParser()
if err != nil {
	log.Fatalln(err)
}

Documentation

Overview

Package auth provides functions for services to issue and sign api consumer tokens.

Index

• Variables
• func PrivateKeyFromPEM(key []byte) (crypto.PrivateKey, error)
• func PrivateKeyFromPEMWithPassword(key []byte, password string) (crypto.PrivateKey, error)
• func PublicKeyFromPEM(key []byte) (crypto.PublicKey, error)
• type Issuer
  • func NewIssuer(private crypto.PrivateKey, method jwt.SigningMethod) *Issuer
  • func NewIssuerFromPEM(key []byte, method jwt.SigningMethod) (*Issuer, error)
  • func NewIssuerFromPEMWithPassword(key []byte, password string, method jwt.SigningMethod) (*Issuer, error)
  • func (i *Issuer) Issue(claims jwt.Claims) (string, error)
• type Parser
  • func NewParser(pk crypto.PublicKey, fn PublicKeyFunc) *Parser
  • func NewParserFromPEM(key []byte, fn PublicKeyFunc) (*Parser, error)
  • func (p *Parser) Parse(raw string, claims jwt.Claims) error
• type PublicKeyFunc
• type RSAPublicKeyCopierRenewer

Examples

• Issuer.Issue
• Parser.Parse

Variables

var (
	// ErrKeyMustBePEMEncoded happens when the PEM format is not valid.
	ErrKeyMustBePEMEncoded = errors.New("invalid key: must be PEM encoded PKCS1 or PKCS8 private key")
	// ErrNotRSAPrivateKey happens when the key is not a valid RSA private key.
	ErrNotRSAPrivateKey = errors.New("invalid key: must be a valid RSA private key")
	// ErrNotPrivateKey happens when the key is neither an RSA or ECDSA private key.
	ErrNotPrivateKey = errors.New("invalid key: must be either an RSA or ECDSA private key")
	// ErrNotPublicKey happens when the key is neither an RSA or ECDSA public key.
	ErrNotPublicKey = errors.New("invalid key: must be either an RSA or ECDSA public key")
)

Functions

func PrivateKeyFromPEM

func PrivateKeyFromPEM(key []byte) (crypto.PrivateKey, error)

PrivateKeyFromPEM will take a private key PEM and derive the private key from it.

func PrivateKeyFromPEMWithPassword

func PrivateKeyFromPEMWithPassword(key []byte, password string) (crypto.PrivateKey, error)

PrivateKeyFromPEMWithPassword will take a private key PEM with a password and derive the private key from it.

func PublicKeyFromPEM

func PublicKeyFromPEM(key []byte) (crypto.PublicKey, error)

PublicKeyFromPEM will take a public key PEM and derive the public key from it.

Types

type Issuer

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

Issuer represents a set of methods for generating a JWT with a private key

func NewIssuer

func NewIssuer(private crypto.PrivateKey, method jwt.SigningMethod) *Issuer

NewIssuer creates a new issuer.

func NewIssuerFromPEM

func NewIssuerFromPEM(key []byte, method jwt.SigningMethod) (*Issuer, error)

NewIssuerFromPEM will take a private key PEM and derive the private key from it.

func NewIssuerFromPEMWithPassword

func NewIssuerFromPEMWithPassword(key []byte, password string, method jwt.SigningMethod) (*Issuer, error)

NewIssuerFromPEMWithPassword will take a private key PEM with a password and derive the private key from it.

func (*Issuer) Issue

func (i *Issuer) Issue(claims jwt.Claims) (string, error)

Issue will sign a JWT and return its string representation.

Example

claims := jwt.StandardClaims{
	Id:        "1234",
	Issuer:    "Tests",
	Audience:  "Developers",
	Subject:   "Example",
	ExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
	IssuedAt:  time.Now().Unix(),
	NotBefore: time.Now().Unix(),
}
raw, err := issuer.Issue(&claims)
if err != nil {
	return
}
fmt.Println(raw)

type Parser

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

Parser represents a set of methods for parsing and validating a JWT against a public key

func NewParser

func NewParser(pk crypto.PublicKey, fn PublicKeyFunc) *Parser

NewParser returns a new parser with a public key.

func NewParserFromPEM

func NewParserFromPEM(key []byte, fn PublicKeyFunc) (*Parser, error)

NewParserFromPEM will take a PEM and derive the public key from it and instantiate a parser.

func (*Parser) Parse

func (p *Parser) Parse(raw string, claims jwt.Claims) error

Parse takes a string and returns a valid jwt token

Example

var claims jwt.StandardClaims
err := parser.Parse(`... jwt key ...`, &claims)
if err != nil {
	return
}

type PublicKeyFunc

type PublicKeyFunc func(crypto.PublicKey) jwt.Keyfunc

PublicKeyFunc is used to parse tokens using a public key.

type RSAPublicKeyCopierRenewer

type RSAPublicKeyCopierRenewer interface {
	Copy() rsa.PublicKey
	Renew()
}

RSAPublicKeyCopierRenewer represents the combination of a Copier and Renewer interface